La doc de la doc de SARAH
Depuis quelques années la doc de SARAH se trouve sur le wiki d’un projet GitHub. J’aime les projets SaaS qui s’occupent de tout pour moi: IHM, authentification, maintenance, etc …
Le mois dernier, avec Aymeric dMdV, nous avons mis en place une petite innovation exploitant les sites statiques de GitHub.
Portail
L’idée de départ est de concevoir une page portail HTML dans laquelle seront chargés des contenus dynamiques.
[crayon]
<div class="doc-sidebar" data-page="sidebar1"></div>
[/crayon]
Les zones indiquées dans l’attribut data-page sont remplacées par un fichier Markdown:
- Téléchargé en Ajax
- Transformé en HTML
- Amélioré en JavaScript
Certains liens sont, par exemple, réécris de manière à aller sur ?page=NomDeLaPage.
[crayon]
<div id="doc-content" data-page="Home"></div>
[/crayon]
Au chargement de la page, le conteneur principal doc-content recevra un attribut data-page correspondant à l’attribut page de l’URL.
CMS
GitHub fournit toute l’IHM pour éditer un fichier Markdown sans compétence d’informaticien.
Nous avons donc une belle et simple séparation entre la présentation et le contenu.
Multilinguisme
Un des besoins de la communauté était d’avoir une doc en Anglais et en Français.
Nous avons donc introduit une petit mécanique qui enregistre en LocalStorage la langue de l’utilisateur.
Ensuite le code portail va chercher le NomDeLaPage.md dans le dossier /en ou /fr.
Bonus
Marketplace
Dans un cas particulier, le doc-content est remplacé par une IFrame du Marketplace. Ce qui permet de mutualiser les IHM.
Block
Le site statique utilisant Bootstrap j’ai enrichi le format Markdown pour générer des <div class="block-thing"></div> pour tous les block-thing.
Il est alors très simple de zoner le Markdown pour ensuite mettre le HTML dans des onglets Bootstrap par exemple !
Sommaire
Pour éviter d’être redondant, le sommaire est généré automatiquement à partir des balises H2 et H3.