Merge pull request #1592 from YunoHost/writedoc_links

Clarify how to write internal links

pages/04.contribute/02.write_documentation/02.markdown_guide/doc_markdown_guide.fr.md

@@ -60,14 +60,16 @@ Pour créer un lien vers un site hors de la documentation de YunoHost :
 s'affichera comme tel :
 [Texte à afficher](https://lelien.tld)
 
-C'est identique pour les pages de la documentation, excepté que le lien est interne. Il renvoie au fichier du wiki, sans extension de langue et de fichier (le `_fr.md`) :
+C'est identique pour les pages de la documentation, excepté que le lien est interne. Le nom de la page est sa route par défault définie dans son *header*:
 ```markdown
 [Page du wiki](/write_documentation)
 ```
 
-Le lien renverra vers la page avec la bonne configuration de langue si la page existe.
+Le lien renverra vers la page avec la bonne configuration de langue si la page existe, ou vers une autre langue disponible (l'anglais, généralement) si elle n'existe pas.
 [Page du wiki](/write_documentation)
 
+! Notez qu'il ne faut donc pas préciser le code de langue au début des liens vers d'autres pages de la documentation : `/fr`, `/en`, etc. sont superflus.
+
 ### Créer des ancres
 Une ancre permet de faire un lien vers un point précis dans une page, c'est comme ça que fonctionnent les index en haut de page. Pour créer une ancre, il faut insérer du code à l'endroit de l'ancre sous la forme suivante :
 

pages/04.contribute/02.write_documentation/02.markdown_guide/doc_markdown_guide.md

@@ -60,14 +60,16 @@ To create a link to a site outside of the YunoHost documentation:
 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 `_fr.md`):
+It is the same for the documentation pages, except that the link is internal. The page name is its default route, as defined in its page header:
 ```markdown
 [Wiki Page](/write_documentation)
 ```
 
-The link will return to the page with the correct language setting if the page exists.
+The link will return to the page with the correct language setting if the page exists, or defaults to the next available language (French, usually):
 [Wiki page](/write_documentation)
 
+! Note that language codes are thus not to be included at the beginning of the links to other documentation pages: `/en`, `/fr`, etc. are superfluous.
+
 ### 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 :
 

pages/04.contribute/02.write_documentation/write_documentation.fr.md

@@ -77,6 +77,8 @@ routes:
 
 Vous pouvez utiliser la syntaxe Markdown, consultez la page de [documentation dédiée](/doc_markdown_guide) pour plus d'information.
 
+! Notez qu'il ne faut pas préciser le code de langue au début des liens vers d'autres pages de la documentation : `/fr`, `/en`, etc. sont superflus.
+
 Pour étendre les fonctionnalités de Markdown, des extensions ont été ajoutées à Grav. Vous pouvez consulter leur propre documentation sur GitHub pour découvrir comment vous en servir.
 ```text
 anchors

pages/04.contribute/02.write_documentation/write_documentation.md

@@ -78,6 +78,8 @@ routes:
 
 You can use Markdown syntax, refer to the [documentation](/doc_markdown_guide) for further information.
 
+! Note that language codes are not to be included at the beginning of the links to other documentation pages: `/en`, `/fr`, etc. are superfluous.
+
 To improve Markdown capabilities, additional plugins are installed in Grav. You can refer to their own documentation on GitHub to see how to use them.
 ```text
 anchors