--- title: "Portail de documentation" weight: 50 description: "Navigation publique, recherche plein texte, front matter YAML et organisation des documents." --- # Portail de documentation Le mode **documentation** (et le mode **hybride**) transforme MarginaliaMD en portail de documentation publique. Les documents sont organisés en projets, navigables via une arborescence latérale, et indexés pour la recherche plein texte. ## Page d'accueil La page d'accueil affiche les projets sous forme de cartes. Chaque projet correspond à un dossier dans `data/documents/`. ![Page d'accueil du portail avec les cartes de projets organisées par catégorie](screenshots/portail-accueil.webp) Les cartes affichent : - Le nom du projet (tiré du front matter de son fichier `index.md`, ou du nom de dossier) - La description (champ `description` du front matter) - Le nombre de documents dans le projet ### Filtres par catégorie Si vos projets définissent des catégories via le front matter, une barre de filtres apparaît au-dessus des cartes. Cliquez sur une catégorie pour n'afficher que les projets correspondants. Les catégories sont identifiées par des badges colorés. ### Filtres par type Si vos projets définissent un type (par exemple `module-dolibarr`, `application`), une barre de filtres par type apparaît en complément. ## Navigation ### Arborescence latérale En consultant un document, un panneau latéral gauche affiche l'arborescence complète du projet. Les dossiers sont dépliables et les fichiers sont triés par poids (`weight`) puis par nom. ![Vue d'un document avec l'arborescence de navigation à gauche et la table des matières à droite](screenshots/portail-navigation.webp) ### Fil d'Ariane Un fil d'Ariane (breadcrumb) apparaît au-dessus du contenu, indiquant le chemin depuis la racine du projet jusqu'au document courant. ### Navigation précédent / suivant En bas de chaque document, des boutons **Précédent** et **Suivant** permettent de parcourir les documents dans l'ordre défini par les poids. ### Table des matières Un panneau latéral droit affiche la table des matières du document courant, construite automatiquement à partir des titres h1 à h4. Les entrées sont cliquables et défilent jusqu'à la section correspondante. ## Recherche plein texte La barre de recherche sur la page d'accueil utilise SQLite FTS5 pour la recherche plein texte. Le contenu indexé comprend le titre, le chemin du fichier et le texte du document (Markdown dépouillé de ses balises). ![Résultats de recherche avec les extraits de texte et les badges de projet](screenshots/portail-recherche.webp) La recherche est insensible aux accents : une recherche sur "echeancier" trouvera "échéancier". Les résultats affichent un extrait du passage correspondant avec le terme recherché mis en évidence. La recherche se déclenche automatiquement après 2 caractères saisis, avec un délai de 300 ms pour limiter les requêtes. ## Front matter YAML Chaque fichier Markdown peut commencer par un bloc de métadonnées YAML délimité par `---`. Ces métadonnées contrôlent l'affichage et l'organisation du document dans le portail. ```yaml --- title: "Titre de la page" weight: 10 description: "Description courte pour les cartes et la recherche." category: "Catégorie du projet" type: "module-dolibarr" annotations: true --- ``` ### Champs disponibles | Champ | Type | Description | |-------|------|-------------| | `title` | texte | Titre affiché dans la navigation, le fil d'Ariane et les résultats de recherche. Si absent, le nom du fichier est utilisé. | | `weight` | entier | Ordre de tri dans la navigation. Les documents sont triés par poids croissant puis par nom. Utilisez des multiples de 10 (10, 20, 30...) pour pouvoir intercaler des pages. | | `description` | texte | Description courte (1-2 phrases). Affichée dans la carte du projet (uniquement pour `index.md`). | | `category` | texte | Catégorie du projet pour le regroupement sur la page d'accueil. Séparateur `;` pour plusieurs catégories (ex: `"Finances; Direction"`). Uniquement dans `index.md`. | | `type` | texte | Type de projet pour le filtre sur la page d'accueil (ex: `"module-dolibarr"`, `"application"`). Uniquement dans `index.md`. | | `annotations` | booléen | Active les annotations en mode hybride. Ignoré en mode documentation (annotations toujours désactivées) et en mode revue (toujours activées). | ### Convention de poids ```yaml weight: 1 # index.md (toujours en premier) weight: 10 # Installation weight: 20 # Configuration weight: 30 # Utilisation weight: 40 # Fonctionnalités avancées weight: 50 # FAQ ``` ### Le fichier index.md Chaque projet (dossier) devrait contenir un fichier `index.md`. C'est la page d'entrée du projet : son `title` et sa `description` sont utilisés pour la carte sur la page d'accueil. Les champs `category` et `type` ne sont nécessaires que dans ce fichier. ## Organisation des documents ### Structure recommandée ``` data/documents/ ├── mon-projet/ │ ├── index.md # Page d'accueil du projet │ ├── installation.md │ ├── configuration.md │ ├── utilisation.md │ ├── faq.md │ └── screenshots/ │ ├── ecran-principal.webp │ └── configuration.webp └── autre-projet/ ├── index.md └── ... ``` ### URLs propres En mode documentation, les documents sont accessibles via des URLs propres sans extension `.md` : | URL | Fichier affiché | |-----|----------------| | `/mon-projet/` | `mon-projet/index.md` | | `/mon-projet/installation` | `mon-projet/installation.md` | | `/mon-projet/configuration` | `mon-projet/configuration.md` | ### Liens entre documents Pour créer un lien vers une autre page du même portail, utilisez le format URL propre : ```markdown Consultez la page [Installation](/mon-projet/installation). ``` > **Liens relatifs** : Les liens relatifs comme `[voir ici](installation.md)` ne sont pas résolus automatiquement. Utilisez toujours le chemin absolu avec `/nom-du-projet/page`. ### Images Les images référencées avec un chemin relatif sont servies automatiquement via l'API MarginaliaMD : ```markdown ![Description de la capture](screenshots/ecran-principal.webp) ``` Formats supportés : PNG, JPG, GIF, SVG, WebP. ## Indexation ### Indexation automatique En mode documentation et hybride, les documents sont indexés automatiquement lorsqu'un visiteur navigue dans le portail. L'arborescence et la consultation d'un document déclenchent l'indexation si nécessaire. ### Indexation manuelle (CLI) Pour indexer tous les documents en une seule opération : ```bash php cli/index-documents.php ``` Ce script parcourt récursivement `data/documents/`, analyse le front matter de chaque fichier et met à jour la base de données et l'index de recherche FTS5. ### Collecte de captures d'écran (CLI) Un outil interactif permet de collecter les captures d'écran référencées dans la documentation : ```bash php cli/collect-screenshots.php nom-du-projet ``` L'outil parcourt les fichiers Markdown, identifie les images manquantes et guide la capture interactive avec flameshot. Les images capturées sont automatiquement converties en WebP. ## Lightbox Les images dans les documents s'affichent avec une taille réduite. Cliquez sur une image pour l'ouvrir en plein écran dans une lightbox. Le texte alternatif de l'image est affiché comme légende en dessous. Fermez la lightbox en cliquant en dehors de l'image, sur le bouton X, ou avec la touche Escape.