diff --git a/.gitignore b/.gitignore
index 9870175..1c3f58b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
node_modules/
_site/
pages.git/
+.idea/
diff --git a/assets/images/markdown/mermaid-example.png b/assets/images/markdown/mermaid-example.png
new file mode 100644
index 0000000..6de04fc
Binary files /dev/null and b/assets/images/markdown/mermaid-example.png differ
diff --git a/content/markdown/faq.md b/content/markdown/faq.md
new file mode 100644
index 0000000..baf39a3
--- /dev/null
+++ b/content/markdown/faq.md
@@ -0,0 +1,23 @@
+---
+eleventyNavigation:
+ key: MarkdownFAQ
+ title: Markdown FAQ
+ parent: Markdown
+ order: 90
+---
+
+This section contains frequently asked questions regarding the use of Markdown on Codeberg.
+
+## Why doesn't my markdown render correctly?
+
+Sometimes markdown is rendered differently on different sides. If your markdown renders
+correctly on another forge or in your editor but does not get rendered correctly at Codeberg,
+it is probably due to a difference in the Markdown flavour used by the side/editor.
+
+Codeberg uses Gitea at it's core. Gitea uses [Goldmark](https://github.com/yuin/goldmark) as rendering engine.
+Goldmark is compliant with [CommonMark 0.30](https://spec.commonmark.org/0.30/).
+
+Please refer to the CommonMark 0.30 specification on what gets rendered and why.
+
+If you want to correct your rendering you either have to adapt to Codebergs rendering or
+you must find another way to find an approach common to platforms/software used (and/or supported) by you.
\ No newline at end of file
diff --git a/content/markdown/index.md b/content/markdown/index.md
index 0e9e1d9..412e1ee 100644
--- a/content/markdown/index.md
+++ b/content/markdown/index.md
@@ -4,5 +4,21 @@ eleventyNavigation:
title: Writing in Markdown
icon: pen-nib
order: 40
- draft: true
----
\ No newline at end of file
+---
+
+On these pages, you will learn how to use Markdown in issues, texts and articles on Codeberg.
+
+The Codeberg platform (based on [Gitea](https://gitea.io/)) uses Markdown as markup language for text formatting.
+Gitea uses [Goldmark](https://github.com/yuin/goldmark) as rendering engine which is compliant with [CommonMark 0.30](https://spec.commonmark.org/0.30/).
+The documentation of Codeberg is rendered using [markdown-it](https://github.com/markdown-it/markdown-it) which also support CommonMark.
+
+## Further reading
+
+You can read more about markdown in the following articles.
+Additionally there are a lot of articles on the internet introducing Markdown. Just use the search engine of your choice to
+look them up and learn more about Markdown.
+
+- [A strongly defined, highly compatible specification of Markdown](https://commonmark.org/)
+- [English Wikipedia article on Markdown](https://en.wikipedia.org/wiki/Markdown)
+- [The Markdown Guide](https://www.markdownguide.org/)
+
diff --git a/content/markdown/introduction-to-markdown.md b/content/markdown/introduction-to-markdown.md
new file mode 100644
index 0000000..150d946
--- /dev/null
+++ b/content/markdown/introduction-to-markdown.md
@@ -0,0 +1,115 @@
+---
+eleventyNavigation:
+ key: IntroductionToMarkdown
+ title: Introduction to Markdown
+ parent: Markdown
+ order: 20
+---
+
+Markdown files are basically a normal text files. The file extension `.md` specifies that a file can be rendered as Markdown.
+You can also use Markdown in many object of the Codeberg platform (Issues, Pull-Requests, etc.).
+
+## Text section
+
+To write a markdown file, simply write the text into a text editor of your choice.
+Markdown does not consider single line breaks as start of a new paragraph.
+You can write all your text into one long line or introduce a new line every once in a while.
+It is common practice to introduce a new line at about 80 characters to enable users to easily read the plain un-rendered version of the markdown file.
+It is however recommended to make a line break in Markdown at logical steps, e.g. at the end of a sentence.
+It makes diffs easier to understand, as the context of the complete sentence is preserved.
+
+If you want to start a new paragraph, use two or more empty new lines to separate the text.
+Beware that in the Gitea rendering, text in repos and comment fields the linebreaks are rendered differently.
+For example a simple line break is considered in the comments and leads to a new paragraph.
+
+### Highlighting text sections
+
+In text sections it is possible to highlight passages using **bold** and *italics*.
+
+### Bold
+
+To mark a text as bold use two stars at the start of the section you want to highlight `**`
+At the end of the section to be highlighted add another two stars `**`.
+Alternatively you can use two underline characters `__` at the beginning and the end of the section
+to get the same effect
+
+Example:
+
+```
+This is a **highlighted text**.
+```
+
+The example gets rendered as:
+
+This is a **highlighted text**.
+
+```
+This is also __highlighted text__.
+```
+
+The example gets rendered as:
+
+This is also __highlighted text__.
+
+### Italics
+
+To mark a text in italics use one stars at the start of the section you want to highlight `*`
+At the end of the section to be highlighted add another two stars `*`.
+Alternatively you can use one underline character `_` at the beginning and the end of the section
+to get the same effect
+
+Example:
+
+```
+This is a *highlighted text*.
+```
+
+The example gets rendered as:
+
+This is a *highlighted text*.
+
+```
+This is also _highlighted text_.
+```
+
+The example gets rendered as:
+
+This is also _highlighted text_.
+
+## Gitea specifics
+
+### Emoticons
+Text may contain references to emoticons which are then rendered as a small image.
+These are marked using a colon `:`, followed by the identifier of the emoticon to use, followed by another colon `:`.
+
+Examples of the emoticons are: `:codeberg:` leading to 
and `:gitea:` rendered as 
.
+
+### Referencing issue
+
+Issues in Codeberg/Gitea can be referenced in the comments of an issue or a pull request by using a hash mark `#` followed by the number of the issue.
+The renderer will then include a link to the referenced issue into the comment.
+Additionally, a ping back link to the comment containing the reference will be added to the issues referenced in this way.
+
+### Checkboxes
+
+You can add checkboxes to comments by using square brackets containing a space `[ ]`. These can be checked/unchecked later without editing the comment.
+This can for example be useful when creating a Todo list.
+
+### Mermaid diagrams
+
+Gitea can render [Mermaid diagrams](https://mermaid-js.github.io/mermaid/#/) in issues, pull-requests and comments.
+
+Use the render hint `mermaid` on the preformatted section containing the code of the Mermaid diagram.
+
+E.g.
+
+ ```mermaid
+ graph TD;
+ A(stuff)-->B[one];
+ A-->C[two];
+ A-->D[three];
+ ```
+
+is rendered to:
+
+
\ No newline at end of file
diff --git a/content/markdown/markdown-styleguide.md b/content/markdown/markdown-styleguide.md
new file mode 100644
index 0000000..d9e7046
--- /dev/null
+++ b/content/markdown/markdown-styleguide.md
@@ -0,0 +1,45 @@
+---
+eleventyNavigation:
+key: MarkdownStyleguide
+title: Markdown Styleguide
+parent: Markdown
+order: 10
+---
+
+This document should guide you to a use of the Markdown format which is commonly used in Codeberg.
+
+## Bold
+
+Use two stars at the beginning and the end of a section to highlight the **section in bold**.
+
+## Italics
+
+Use one star at the beginning and the end of a section to highlight the *section in italics*.
+
+## Links
+
+Use `[link description](link)` to link to another section, article or website.
+
+To link to an url without any Link-Description, surround the link by less-than `<` and
+greater-than `>` characters. This is preferred to just adding an url within the text as it
+is easier to parse the marked up urls.
+
+Example:
+
+
+
+## Topics
+
+Use ATX-Style topics by adding one or more hash `#` signs to the start of the topic line.
+
+## Preformatted sections
+
+Use a single backtick character to preformat a word or a section within a line.
+
+Use triple backticks to begin and end a preformatted section.
+
+Use rendering hints to tell the renderer whether to syntax highlight your section and which language should be used.
+
+## Tables
+
+Always delimit both sides of a table with pipes `|`. Keep the tables readable even in the un-rendered text-form.
\ No newline at end of file
diff --git a/content/markdown/preformatted-text.md b/content/markdown/preformatted-text.md
new file mode 100644
index 0000000..ad74690
--- /dev/null
+++ b/content/markdown/preformatted-text.md
@@ -0,0 +1,61 @@
+---
+eleventyNavigation:
+ key: PreformattedText
+ title: Preformatted Text
+ parent: Markdown
+ order: 50
+---
+
+There are two ways to use preformatted text withing your Markdown document:
+
+- By using indentation
+- By using one or more backticks at the beginning and the end of a preformatted section
+
+## Using indentation
+
+You can preformat a section of text or code by indenting the code with 4 or more spaces or a tab:
+
+ this
+ is
+ displayed
+ as
+ preformatted
+
+It is not possible to add a rendering hint. It is not possible to preformat text within a line using this syntax.
+
+## Using backticks
+
+You can preformat a section of text by starting a section of text with one or more backtick characters.
+
+```
+this
+is
+displayed
+as
+preformatted
+```
+
+You can also preformat a section of text within a line using the backtick syntax.
+The following text is for example `preformatted` by using the backtick syntax.
+
+### Rendering hints
+
+Sometime renders use hints to syntax highlight the code in a preformatted section.
+
+To provide a hint, simple add the language name at the end of the introductory backtick(s).
+
+For example using `shell` as hint will tell the renderer that the given code can be highlighted as shell script:
+
+```shell
+#!/bin/bash
+
+echo "Hello world"
+```
+
+The same would be rendered without syntax highlighting if the hint is not given:
+
+```
+#!/bin/bash
+
+echo "Hello world"
+```
diff --git a/content/markdown/tables-in-markdown.md b/content/markdown/tables-in-markdown.md
new file mode 100644
index 0000000..4162d03
--- /dev/null
+++ b/content/markdown/tables-in-markdown.md
@@ -0,0 +1,138 @@
+---
+eleventyNavigation:
+ key: TablesInMarkdown
+ title: Tables in Markdown
+ parent: Markdown
+ order: 70
+---
+
+Markdown Articles can contain tables to structure presented data.
+
+## table syntax
+
+Markdown tables are written ("drawn") using the characters pipe `|`, dash `-` and colon `:`.
+
+A simple table looks like this
+
+```
+| This | is | a |
+| --- | --- | --- |
+| simple | table | example |
+```
+
+| This | is | a |
+| --- | --- | --- |
+| simple | table | example |
+
+The table columns do not have to align in the un-rendered text, but it improves readability to keep everything aligned
+in the un-rendered form as well.
+
+Some editors align the table structure automatically.
+
+The first line a table forms the head of the table. It is separated from the rest of the data by a line containing dashes.
+
+```
+| Name | Comment |
+|:-------|:------------------------------------------------------------------------|
+| Alice | Always involved in various communications |
+| Bob | A good guy, who likes to communicate with Alice |
+| Malroy | Not so nice guy. Tries to mess with the communication of Alice and Bob. |
+```
+
+| Name | Comment |
+|:-------|:------------------------------------------------------------------------|
+| Alice | Always involved in various communications |
+| Bob | A good guy, who likes to communicate with Alice |
+| Malroy | Not so nice guy. Tries to mess with the communication of Alice and Bob. |
+
+The line following the header line may contain a formatting help to the renderer.
+
+It depends on the place of the colon `:` (if any) how the table is rendered.
+
+If the colon is to the left of the line of dashes separating data from the header, the data is rendered in a left-aligned
+form.
+
+For example
+
+```
+| Left oriented rendering |
+|:------------------------|
+| 150.0 |
+| or text |
+```
+
+Renders as:
+
+| Left oriented rendering |
+|:------------------------|
+| 150.0 |
+| or text |
+
+Whereas:
+
+```shell
+| Right oriented rendering |
+|-------------------------:|
+| 150.0 |
+| or text |
+```
+
+is rendered as
+
+| Right oriented rendering |
+|-------------------------:|
+| 150.0 |
+| or text |
+
+If the rendering hint is placed on both sides of the dashed line, the data is rendered as centered:
+
+```
+| Centerd rendering |
+|:-----------------:|
+| 150.0 |
+| or text |
+```
+
+Is rendered as:
+
+| Centerd rendering |
+|:-----------------:|
+| 150.0 |
+| or text |
+
+Providing no rendering hint leaves it to the renderer to decide how to render the data. Left-aligned is a common default.
+
+```shell
+| Un-hinted rendering |
+|---------------------|
+| 150.0 |
+| or text |
+```
+
+Is rendered as:
+
+| Un-hinted rendering |
+|---------------------|
+| 150.0 |
+| or text |
+
+
+## Table variations
+
+Some renderers allow to omit the delimiting pipe symbols `|` at the side of the table:
+
+```
+This | is | a
+--- | --- | ---
+simple | table | example
+```
+
+Is rendered as:
+
+This | is | a
+--- | --- | ---
+simple | table | example
+
+This is even considered an error by some editors.
+
+However, for readability reasons we propose to use the delimited form within Codeberg.
diff --git a/content/markdown/topics.md b/content/markdown/topics.md
new file mode 100644
index 0000000..61c8619
--- /dev/null
+++ b/content/markdown/topics.md
@@ -0,0 +1,63 @@
+---
+eleventyNavigation:
+ key: Topics
+ title: Topics
+ parent: Markdown
+ order: 40
+---
+
+Markdown helps you to divide a document into several parts using topics.
+
+Topics can be specified in two ways:
+
+- with one or more leading hash characters `#` (ATX-Style)
+- by underlining a topic with dashes `-` or equal signs `=` (Setext-Style)
+
+The Setext provides only two layers of subdivision and the ATX-Style up to 6.
+
+The Codeberg documentation uses ATX-style. In the documentation the first topic
+is omitted as it is already provided in the header section of the documentation file.
+See the article on [How to create a new article?](/improving-documentation/create-article.md)
+for further details.
+
+**Note:** This document may seem a little unstructured, as there are a bunch of topics with only a small
+amount of text. Unfortunately there is no other way to present the topic of Topics in Markdown.
+
+### Examples of topics with hash characters
+
+```shell
+# 1st Topic
+```
+
+# 1st Topic
+
+```shell
+## 2nd Topic
+```
+
+## 2nd Topic
+
+```shell
+### 3rd Topic
+```
+
+### 3rd Topic
+
+### Examples of topics with dashes and equal signs
+
+```
+This is a topic
+===============
+```
+
+This is a topic
+===============
+
+```
+This is another topic
+---------------------
+```
+
+This is another topic
+---------------------
+
diff --git a/content/markdown/using-images.md b/content/markdown/using-images.md
new file mode 100644
index 0000000..f5f9a40
--- /dev/null
+++ b/content/markdown/using-images.md
@@ -0,0 +1,31 @@
+---
+eleventyNavigation:
+ key: UsingImages
+ title: Using Images
+ parent: Markdown
+ order: 60
+---
+
+It is possible to include images into the rendered form of a Markdown article.
+
+Please refer to the [article on Screenshots](/improving-documentation/screenshots/) on how to use and include images in the Codeberg documentation.
+
+The syntax of including images is similar to the syntax of links.
+
+```shell
+
+```
+
+
+
+The image link consists of three parts:
+
+- The alternative text - is added in the `alt` attribute of the rendered image
+- the link part - is a URI or URL to an image file, which is then included in the rendered article
+- the title - is added into the `title` attribute of the rendered image (most browser show it on mouse-over)
+
+## Location of image files
+
+Image files can be placed within the folder structure of your article or documentation.
+Apart from that images can be referenced by a URL and are thus included from the internet location the URL points to.
+
diff --git a/content/markdown/using-links.md b/content/markdown/using-links.md
new file mode 100644
index 0000000..d56cda0
--- /dev/null
+++ b/content/markdown/using-links.md
@@ -0,0 +1,75 @@
+---
+eleventyNavigation:
+ key: UsingLinks
+ title: Using Links
+ parent: Markdown
+ order: 30
+---
+
+You can use links to refer to other articles, sections in articles or to other websites.
+
+## Links with description
+
+It is always good for readability to not just paste an url into your text but to provide
+a description of your link. Only the description of the link will be in the rendered form of
+your text and the link will be added as html-link.
+
+Links with description have the following markup: `[Link description](link-url)`.
+
+For example:
+
+```
+[Link to Codeberg](https://codeberg.org/)
+```
+
+Gets rendered as:
+
+[Link to Codeberg](https://codeberg.org/)
+
+## Links without description
+
+To add a link using the url withing your text use `<` and `>` to mark the links.
+For example, if you want to add to `https://codeberg.org/` add `` to your
+text. This will lead to the following rendering of the link to .
+You can also simply add the link to your text to have the same effect: https://codeberg.org
+However it is easier to parse links in the text if the links are explicitly marked by the less
+than `<` and greater than `>` characters.
+
+## URIs and URLs
+
+You can link to another article by specifying the file or path name URI (without specifying the protocol part of an URL).
+
+For example, you can link to the introductory article of this section of the documentation by using its
+path name in the link:
+
+```
+[Link to Introductory article](/markdown/)
+```
+
+This is rendered as:
+
+[Link to Introductory article](/markdown/)
+
+You can also link to a section in an article by specifying the section using an introducing hash character `#`.
+
+For example, you can link to the section on "Links without description" in this same article by using:
+
+```
+[Link to the "links-without-description" section](#links-without-description)
+```
+
+This is rendered as:
+
+[Link to the "links-without-description" section](#links-without-description)
+
+You can link to another article's section using the same syntax.
+
+For example, you can link to the section on "Bold" in the article "Introduction to Markdown" by using:
+
+```
+[Link to the bold section](/markdown/introduction-to-markdown/#bold)
+```
+
+This is rendered as:
+
+[Link to the bold section](/markdown/introduction-to-markdown/#bold)
\ No newline at end of file
diff --git a/content/markdown/using-lists.md b/content/markdown/using-lists.md
new file mode 100644
index 0000000..e14df92
--- /dev/null
+++ b/content/markdown/using-lists.md
@@ -0,0 +1,82 @@
+---
+eleventyNavigation:
+ key: UsingLists
+ title: Using Lists
+ parent: Markdown
+ order: 60
+---
+
+You can use lists in your markdown article.
+
+## Unnumbered lists
+
+To use an unnumbered list (bullet point list), simple begin your list items with a dash `-` or a star `*`.
+
+For example:
+
+```
+- This
+- is
+- a
+- simple
+- bullet
+- point
+- list
+```
+
+Gets rendered as:
+
+- This
+- is
+- a
+- simple
+- bullet
+- point
+- list
+
+## Numbered lists
+
+To use a numbered list, simply begin your list items with a number.
+
+```shell
+1. This
+2. is
+3. a
+4. numbered
+5. point
+6. list
+```
+
+Gets rendered as:
+
+1. This
+2. is
+3. a
+4. numbered
+5. point
+6. list
+
+Note that the numbers do not have to be counted up (even though it is easier to read in the non-renderd form):
+
+```
+1. This
+1. is
+1. also
+1. a
+1. numbered
+1. point
+1. list
+```
+
+will also render to a correctly numbered list:
+
+1. This
+1. is
+1. also
+1. a
+1. numbered
+1. point
+1. list
+
+Some editors even autocorrect this to a correctly numbered list. (So if the example above does no longer start with `1.`
+on each line, please feel free to reintroduce the mistake for illustration purposes.)
\ No newline at end of file