h759bkyo4/Documentation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Initial version of a Markdown documentation (#221)

Browse source 
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 <c0d3b3rg@kl1pp3l.de>
Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/221
Co-authored-by: jklippel <jklippel@noreply.codeberg.org>
Co-committed-by: jklippel <jklippel@noreply.codeberg.org>
This commit is contained in:
jklippel 2022-04-23 21:18:08 +02:00 committed by Otto Richter
parent 3b3309a90e
commit 5f022adfc6
12 changed files with 652 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -1,3 +1,4 @@
node_modules/
_site/
pages.git/
.idea/

BIN
assets/images/markdown/mermaid-example.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 4.8 KiB

23
content/markdown/faq.md Normal file
View file

@ -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.

20
content/markdown/index.md
View file

@ -4,5 +4,21 @@ eleventyNavigation:
title: Writing in Markdown
icon: pen-nib
order: 40
draft: true
---
---
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/)

115
content/markdown/introduction-to-markdown.md Normal file
View file

@ -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 <img src="https://codeberg.org/assets/img/emoji/codeberg.png" class="codeberg-design" style="border-style:none;width:1em;height:1em" alt="The Codeberg mountain" /> and `:gitea:` rendered as <img src="https://codeberg.org/assets/img/emoji/gitea.png" class="codeberg-design" style="border-style:none;height:1em;width=1em" alt="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)

45
content/markdown/markdown-styleguide.md Normal file
View file

@ -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:
<https://codeberg.org/>
## 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.

61
content/markdown/preformatted-text.md Normal file
View file

@ -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"
```

138
content/markdown/tables-in-markdown.md Normal file
View file

@ -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.

63
content/markdown/topics.md Normal file
View file

@ -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
---------------------

31
content/markdown/using-images.md Normal file
View file

@ -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.

75
content/markdown/using-links.md Normal file
View file

@ -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 `<https://codeberg.org>` to your
text. This will lead to the following rendering of the link to <https://codeberg.org>.
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)

82
content/markdown/using-lists.md Normal file
View file

@ -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.)