diff --git a/doc_markdown_guide.md b/doc_markdown_guide.md index b42deefe..928315e5 100644 --- a/doc_markdown_guide.md +++ b/doc_markdown_guide.md @@ -1,16 +1,252 @@ -# Markdown Guide +# Guide Markdown -Markdown is a markup language from 2004, with many add-ons supporting its function and existence. This guide explores the possibilities and formatting of the language in the context of YunoHost documentation, and not the Markdown language on its own. +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 formatting of text using tags, in human-readable format; even with formatting. Outside of plaintext editors, a number of specific programs exist. (Markdown on [framalibre.org](https://framalibre.org/recherche-par-crit-res?keys=markdown)). It is easy to deal with. +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](https://framalibre.org/recherche-par-crit-res?keys=markdown)). It is relatively easy to use. -## The different title levels +## The different levels of titles + +By writing titles as follows: +```Markdown +# 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 : -Write headlines like this: ```markdown -# Level 1 -## Level 2 -### Level 3 -#### Level 4 -##### Level 5 -###### Level 6 +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: + +```markdown +[Text to display](https://lelien.tld) +``` + +will be displayed as such: +[Text to display](https://lelien.tld) + +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`) : +```markdown +[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 : + +```markdown +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: + +```markdown +[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. + +```markdown +[Yunohost Logo](/images/logo.png) +``` +[Yunohost Logo](/images/logo.png) + + +It is possible to make a link with an image, for example : +```markdown +[! [Yunohost Logo](/images/logo.png)](/write_documentation) +``` +[! [Yunohost Logo](/images/logo.png)](/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: + +```markdown +>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](contributordoc) 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. + +```markdown +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: + +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 +5. List 4 +3. List 5 +4. 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: +```markdown ++ 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 | +|:-------------------------|:---------------:|-------------------------:| +|`:-----` | `:----:` | `-----:` | + +```markdown +|| 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 | | Or *italic* | +| More lines | |! [An image](/images/cd.jpg) | [Or a link](/contributordoc) | + +## Code block + +To display plain text, `blocks of code' can be created using the grave accent `Alt Gr + è` : + +```markdown +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`. +''' +```markdown +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)](https://daringfireball.net/projects/markdown/) + + Markdown Tutorial on [markdowntutorial.com](https://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](https://forum.yunohost.org) or by direct message on the IRC room: **#yunohost** on [irc.freenode.net](https://irc.freenode.net). diff --git a/doc_markdown_guide_fr.md b/doc_markdown_guide_fr.md index 0fd54bd3..12e6071f 100644 --- a/doc_markdown_guide_fr.md +++ b/doc_markdown_guide_fr.md @@ -71,13 +71,16 @@ Du texte qui sera ne sait même pas qu'il a une ancre Ce qui s'affiche : Du texte qui sera ne sait même pas qu'il a une ancre +Il est aussi possible de directement renvoyer une ancre au titre, en notant le lien en minuscule avec des `-` à la place des espaces. Il ne reste plus qu'à désigner l'ancre au texte que l'on souhaite rendre interactif : ```markdown -[Mon titre qui renvoie](#nom-du-titre) +[Mon ancre qui renvoie vers les listes](#nomdelancre) +[Mon ancre qui renvoie vers le titre des tableaux](#les-tableaux) ``` -[Mon titre qui renvoie](#nomdelancre) +[Mon ancre qui renvoie vers les listes](#nomdelancre) +[Mon ancre qui renvoie vers le titre des tableaux](#les-tableaux) ## Afficher des images @@ -122,7 +125,7 @@ Les listes permettent d'afficher une suite de textes dans une présentation faci ### Listes ordonnées -Les listes ordonnées peuvent s'incrémenter autant que vous le désirez, il n'est pas obligé de donner la bonne correspondance au nombre. Il est possible de noter avec des `1.` comme des `7.` et installer trois espaces pour marquer l'incrémentation. Pour une meilleure compréhension du texte brut, il peut être bien d'utiliser les chiffres de manières croissantes pour marquer l'incrémentation, mais c'est bien les trois `espaces` conséquents avant la sous-liste qui désigneront l'incrémentation. +Les listes ordonnées peuvent s'incrémenter autant que vous le désirez, il n'est pas obligé de donner la bonne correspondance au nombre. Il est possible de noter avec des `1.` et installer trois espaces pour marquer l'incrémentation. Pour une meilleure compréhension du texte brut, il peut être bien d'utiliser les chiffres de manières croissantes pour marquer l'incrémentation, mais c'est bien les trois `espaces` conséquents avant la sous-liste qui désigneront l'incrémentation. ```markdown 1. Liste 1 @@ -133,9 +136,9 @@ Les listes ordonnées peuvent s'incrémenter autant que vous le désirez, il n'e 1. Liste 3b1 1. Liste 3b2 1. Liste 3b3 - 4. Liste 1 - 4. Liste 2 - 4. liste 3 + 1. Liste 1 + 1. Liste 2 + 1. liste 3 1. Liste 4 1. Liste 5 1. liste 6 @@ -151,9 +154,9 @@ On obtient : 1. Liste 3b1 1. Liste 3b2 1. Liste 3b3 - 4. Liste 1 - 4. Liste 2 - 4. liste 3 + 1. Liste 1 + 1. Liste 2 + 1. liste 3 5. Liste 4 3. Liste 5 4. liste 6