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 <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:
parent
3b3309a90e
commit
5f022adfc6
1
.gitignore
vendored
1
.gitignore
vendored
|
@ -1,3 +1,4 @@
|
||||||
node_modules/
|
node_modules/
|
||||||
_site/
|
_site/
|
||||||
pages.git/
|
pages.git/
|
||||||
|
.idea/
|
||||||
|
|
BIN
assets/images/markdown/mermaid-example.png
Normal file
BIN
assets/images/markdown/mermaid-example.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 4.8 KiB |
23
content/markdown/faq.md
Normal file
23
content/markdown/faq.md
Normal 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.
|
|
@ -4,5 +4,21 @@ eleventyNavigation:
|
||||||
title: Writing in Markdown
|
title: Writing in Markdown
|
||||||
icon: pen-nib
|
icon: pen-nib
|
||||||
order: 40
|
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
115
content/markdown/introduction-to-markdown.md
Normal 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
45
content/markdown/markdown-styleguide.md
Normal 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
61
content/markdown/preformatted-text.md
Normal 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
138
content/markdown/tables-in-markdown.md
Normal 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
63
content/markdown/topics.md
Normal 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
31
content/markdown/using-images.md
Normal 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
75
content/markdown/using-links.md
Normal 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
82
content/markdown/using-lists.md
Normal 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.)
|
Loading…
Reference in a new issue