8.5 KiB
Guide Markdown
Markdown is a markup language created in 2004, many add-ons developing the possibilities of this language exist. The objective of this guide is to aim for the exhaustiveness of the possibilities of this formatting language within the framework of the YunoHost documentation and not Markdown languages in general.
Markdown allows text to be formatted using tags, it allows human reading of the text; even with formatting. Even if only one notepad is needed there are many markdowns software (Markdown on framalibre.org). It is relatively easy to use.
The different levels of titles
By writing titles as follows:
# Level 1 title
## Level 2 title
### Level 3 title
#### Level 4 title
### Level 5 title
#### Level 6 title
They appear like this:
Level 1 title
Level 2 title
Level 3 title
Level 4 title
Level 5 title
Level 6 title
Formatting in paragraphs
To type a line break without creating a new paragraph, it is necessary to type two consecutive spaces. Otherwise, the text will continue in a row respecting the general constraints of the page style.
By writing this :
For text in *italic you have to frame it with an asterisk* `*`
To write **bold text by two asterisks** `**`
You can also ~~bar the text~~ by framing it with two tildes `~`
It reads like this:
For text in italic you have to frame it with an asterisk *
To write bold text by two asterisks **
You can also bar the text by framing it with two tildes ~
Create links
To create a link to a site outside of the YunoHost documentation:
[Text to display](https://lelien.tld)
will be displayed as such: Text to display
It is the same for the documentation pages, except that the link is internal. It refers to the wiki file, without language and file extension (the _en.md) :
[Wiki Page](/write_documentation)
The link will return to the page with the correct language setting if the page exists. Wiki page](/write_documentation)
Create anchors
An anchor allows you to make a link to a specific point in a page, that's how the indexes at the top of the page work. To create an anchor, you need to insert code at the anchor location in the following form :
Text that will be doesn't even know it has an anchor.
What's displayed is: Text that will be doesn't even know it has an anchor.
It is also possible to return an anchor directly to the title, noting the link in lower case with -s instead of spaces.
All that remains is to designate the anchor to the text you want to make interactive:
[My Anchor Returns to Lists] [#AnchorName]
[My Anchor that refers to the title of the tables](#the tables)
[My Anchor Returns to Lists] [#AnchorName] [My Anchor that refers to the title of the tables](#the tables)
Displaying images
To display images, the principle is the same as for links, except that a ! is added before the text to be displayed, which is considered here as the text to be displayed if the image cannot be loaded. A description of the image is appropriate.
[Yunohost Logo](/images/logo.png)
It is possible to make a link with an image, for example :
[! [Yunohost Logo](/images/logo.png)](/write_documentation)
[! Yunohost Logo](/write_documentation)
The insert of text to be displayed if the image cannot be loaded between the brackets in the image link is not mandatory but strongly recommended.
Format a quote
Quotes are used to highlight a statement made by another person, the wiki itself manages the way it is highlighted. Markdown uses a closing chevron, this symbol: >, to announce a quote. Just add it before the quote, as such:
>First level quotation text
>which can be formatted in different lines
>> And a second quote
>> with double rafters
Will be displayed :
First level quotation text which can be formatted in different lines
And a second quote with double rafters
Lists
Lists allow to display a series of texts in an easy presentation, this is how indexes such as the contributing documentation page are written.
Ordered lists
The ordered lists can be incremented as much as you wish, it is not necessary to give the right match to the number. It is possible to write down with 1. and put in three spaces to mark the increment. For a better understanding of the plain text, it may be fine to use the numbers in ascending order to mark the increment, but it is the three consistent `spaces' before the sub-list that will mark the increment.
1. List 1
1. List 2
1. list 3
1. List 3a
1. List 3b
1. List 3b1
1. List 3b2
1. List 3b3
1. List 1
1. List 2
1. list 3
1. List 4
1. List 5
1. list 6
You get:
- List 1
- List 2
- list 3
- List 3a
- List 3b
- List 3b1
- List 3b2
- List 3b3
- List 1
- List 2
- list 3
- List 4
- List 5
- list 6
Unordered lists
To create an unordered list, use the symbols *, + or *. This will not change the appearance of the marker in the text output. It is the incrementing of the list that will define the visual. For a better reading of the plain text, it may be good to use the different symbols to mark the increment, but it is the three spaces before the sub-list that will indicate the increment.
As such:
+ List 1
+ List 2
+ list 3
- List 3a
- List 3b
* List 3b1
* List 3b2
* List 3b3
+ List 1
+ List 2
+ list 3
- List 4
* List 5
+ list 6
This will read:
- List 1
- List 2
- list 3
- List 3a
- List 3b
- List 3b1
- List 3b2
- List 3b3
- List 1
- List 2
- list 3
- List 4
- List 5
- list 6
Tables
To create an array, use the vertical bar | and dashes --. It is mandatory to add a line of dashes under the first line of the table. There is no constraint in the size of the table. It is possible to format the array with the : in the second row of the array, three options are available:
| Left aligned column | Centered column | Right aligned column |
|---|---|---|
:----- |
:----: |
-----: |
|| One table | | One column | | One second | | As many as you want |
|:--------------:|:-----------:|:-----------:|:--------------------:|
| | And formatted line | | And bold text | | Or *italic* |
| More lines | |! [An image](/images/cd.jpg) | [Or a link](/contributordoc) |
Which would say this:
| ? A table ? ? A column ? ? A second ? ? As many as you want ? | |||
|---|---|---|---|
| And formatted line | And bold text | ||
| More lines | ! An image | Or a link |
Code block
To display plain text, blocks of code' can be created using the grave accent Alt Gr + è` :
Either inline, for example to highlight a key like `Ctrl`.
or directly as a block. The only difference is in the amount of bass accents: At least three low pitched accents at the opening and closing of the block and two low pitched accents that frame the piece of text to be formatted in a line.
Which will give the rendering:
Either inline, for example to highlight a key like Ctrl.
'''
or directly as a block.
The only difference is in the amount of bass accents:
At least three low pitched accents at the opening and closing of the block and two low pitched accents that frame the piece of text to be formatted in a line.
'''
Useful links
- The documentation of the original Markdown language: daringfireball.net/projects/markdown (en)
- Markdown Tutorial on markdowntutorial.com
Going further
In a more general way, to understand how a text is formatted just inspect the source document with a note application. This does not mean that the YunoHost wiki will be able to exploit it. There are many other possibilities to use markdown syntax, feel free to add missing features. If you've noticed some missing features and/or have questions, please contact us on the forum or by direct message on the IRC room: #yunohost on irc.freenode.net.