From 5f022adfc643c18af37d651dc72651a0ed2b8150 Mon Sep 17 00:00:00 2001 From: jklippel Date: Sat, 23 Apr 2022 21:18:08 +0200 Subject: [PATCH] Initial version of a Markdown documentation (#221) Add initial version of a Markdown documentation to explain Markdown to new contributors. Also provides a styleguide to guide to a consistent use of the Markdown markup within Codeberg. Fixes #59 Co-authored-by: Jan Klippel Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/221 Co-authored-by: jklippel Co-committed-by: jklippel --- .gitignore | 1 + assets/images/markdown/mermaid-example.png | Bin 0 -> 4895 bytes content/markdown/faq.md | 23 ++++ content/markdown/index.md | 20 ++- content/markdown/introduction-to-markdown.md | 115 ++++++++++++++++ content/markdown/markdown-styleguide.md | 45 ++++++ content/markdown/preformatted-text.md | 61 ++++++++ content/markdown/tables-in-markdown.md | 138 +++++++++++++++++++ content/markdown/topics.md | 63 +++++++++ content/markdown/using-images.md | 31 +++++ content/markdown/using-links.md | 75 ++++++++++ content/markdown/using-lists.md | 82 +++++++++++ 12 files changed, 652 insertions(+), 2 deletions(-) create mode 100644 assets/images/markdown/mermaid-example.png create mode 100644 content/markdown/faq.md create mode 100644 content/markdown/introduction-to-markdown.md create mode 100644 content/markdown/markdown-styleguide.md create mode 100644 content/markdown/preformatted-text.md create mode 100644 content/markdown/tables-in-markdown.md create mode 100644 content/markdown/topics.md create mode 100644 content/markdown/using-images.md create mode 100644 content/markdown/using-links.md create mode 100644 content/markdown/using-lists.md 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 0000000000000000000000000000000000000000..6de04fc47c844e9af14e3b35e87a54c9643ea751 GIT binary patch literal 4895 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 D!p%hl literal 0 HcmV?d00001 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 The Codeberg mountain and `:gitea:` rendered as The Gitea tea cup. + +### 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: + +![Mermaid Example rendering](/assets/images/markdown/mermaid-example.png) \ 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 alternative text](images/image.png "title") +``` + +![Codeberg Logo](https://design.codeberg.org/logo-kit/horizontal.png "The Codeberg Logo") + +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