Structures interne de navigation

La structure de la documentation est simple dans la mesure ou la navigation et l’intégration des divers éléments sont basés sur la hierarichie des fichiers. La hierarchie étant potentiellement infinie, la navigation s’adapte automatiquement aux éléments présents

Au premier niveau du dossier src se trouvent les fichiers/dossiers suivants :

• index.md
• 000_doc_produit.md
• 000_doc_produit/
• 010_doc_admin.md
• 010_doc_admin/
• …

Le principe est simple : tous les fichiers md vont se retrouver construits en fichiers html dans le même path. Ainsi, à la base du site, il y a :

• index.html
• 000_doc_produit.html
• 010_doc_admin.html

Chaque fichier .md contient un descripteur en entête en yaml qui permet au système de savoir comment le builder et comment générer la navigation. Ces fichiers contiennent un entête du type :

---
title: Guides
---

Ceci permet de spécifier le nom de l’entrée dans la navigation. Toutes les entrées de premier niveau apparaitront également à la fin du fichier index.html dans l’ordre défini par l’entrée order.

Le système fonctionne ensuite recursivement, c’est à dire que tout les fichiers .md contenu dans le dossier du même nom que le .md du premier niveau (ex : guides) sera référencé à la fin de guides.md et comme sous entrée dans la navigation.

Par exemple, avec la hiérarchie suivante :

• 050_doc_dev.md
• 050_doc_dev/documentation.md
• 050_doc_dev/documentation/redaction.md

Redaction.html sera un sous niveau de documentation.html qui sera un sous niveau de guides. La navigation s’adaptera automatiquement.

Une autre possibilité est de générer une page en plusieurs petits morceaux. Au lieu de déclarer un nouveau sous-niveau dans le dossier du même nom qu’une entrée, il est possible déclarer des morceaux. Un morceau est déclaré de la façon suivante :

---
metaType: api_entry
title: Framework et language
---

Avec la hiérarchie suivante :

• 050_doc_dev.md
• 050_doc_dev/documentation.md
• 050_doc_dev/documentation/morceau01.md
• 050_doc_dev/documentation/autremorceau.md

et que les fichiers du sous dossier documentation sont de metaType api_entry, alors le contenu de ces morceaux seront mis ensemble à la suite du texte contenu dans documentation.md. Une table des matières apparaitra en haut de la page documentation.html permettant d’accéder à un morceau directement.