girust_doc — Documentation officielle gitrust

Sources de la documentation publique de gitrust, forge Git self-hosted en Rust.

Site publié : demo.gitrust.eu — 6 langues (fr, en, de, es, pt, it).

Ce qu'il y a dedans

Quatre manuels organisés selon Diátaxis :

Manuel	Public	Contenu
`user_manual/`	Utilisateurs finaux de la forge	Inscription, SSH, dépôts, PR, issues, CI, notifications
`administration_manual/`	Ops / self-hosters	Installation, config, sauvegarde, mise à jour, conformité ANSSI
`developer_manual/`	Contributeurs core + API clients	Architecture, patrons de code, API REST, tests, QA
`template/`	Tous	Configs et scripts copiables (`.env`, Docker, nginx, systemd, CI…)

Chaque manuel suit les 4 modes Diátaxis : tutorials, how-to, reference, explanation. Les tutoriels respectent un template pédagogique strict (objectifs Bloom, scaffolding, checkpoints, troubleshoot) — voir CONTRIBUTING.md.

Démarrage rapide

Prérequis

cargo install mdbook mdbook-mermaid mdbook-i18n-helpers
npm install -g markdownlint-cli2 @mermaid-js/mermaid-cli
sudo apt install gettext   # pour msginit / msgmerge (Debian/Ubuntu)
mdbook-mermaid install .   # une seule fois

Construire et prévisualiser

mdbook serve --open                    # dev FR avec rechargement auto
mdbook build -d book/fr                # FR en statique
MDBOOK_BOOK__LANGUAGE=en mdbook build -d book/en   # EN
./scripts/build-all-langs.sh           # les 6 langues + landing page

Sortie dans book/.

Vérifier la qualité

markdownlint-cli2 "**/*.md" "#!book/**" "#!node_modules/**"
for f in diagrams/*.mmd; do mmdc -i "$f" -o /tmp/test.svg; done

Pipeline CI Dagger (mode Power)

Le dossier .dagger/ contient un module Dagger Python qui reproduit tout le pipeline dans un conteneur reproductible. Utilisé par gitrust-ci en Power Mode :

dagger call -m .dagger/ ci --source=. export --path=./public
dagger call -m .dagger/ build --source=. --lang=en export --path=./public/en
dagger call -m .dagger/ lint --source=.

Voir .dagger/README.md pour les détails.

Traduction (workflow gettext)

Langue source : français. Les autres langues vivent dans po/*.po et sont fusionnées au build par mdbook-i18n-helpers.

# Extraire les chaînes à traduire
MDBOOK_OUTPUT='{"xgettext":{"pot-file":"messages.pot"}}' mdbook build -d po

# Mettre à jour une langue
msgmerge --update po/en.po po/messages.pot

Workflow complet : CONTRIBUTING.md §3.

Export PDF

Deux implémentations au choix — produit pdf/documentation-<lang>.pdf (une par langue).

Option Rust (recommandée) — `scripts/build-pdf/`

Wrapper léger autour de wkhtmltopdf (backend par défaut) avec fallback automatique vers chromium --headless si wkhtmltopdf n'est pas installé.

sudo apt install wkhtmltopdf               # ou brew install wkhtmltopdf

cargo run --release --manifest-path scripts/build-pdf/Cargo.toml            # les 6 langues
cargo run --release --manifest-path scripts/build-pdf/Cargo.toml -- fr en   # langues spécifiques

# Forcer chromium si wkhtmltopdf est trouvé mais non souhaité :
PDF_BACKEND=chromium cargo run --release --manifest-path scripts/build-pdf/Cargo.toml -- fr

wkhtmltopdf est ~10× plus rapide que Chromium complet sur un print.html de 94 pages et évite les crashes V8 sur les documents volumineux. Laisse 3 s à Mermaid pour se rendre via le JS QtWebKit embarqué.

Option Python — `scripts/build-pdf.py`

# Python 3.9+ uniquement. Pour Python 3.8 : pip install 'weasyprint==60.2' 'pydyf==0.8.0'
pip install weasyprint

./scripts/build-pdf.py              # les 6 langues
./scripts/build-pdf.py fr en        # langues spécifiques
OUT_DIR=./dist ./scripts/build-pdf.py

Pur Python, pas de binaire externe. Attention : weasyprint n'exécute pas le JavaScript, les diagrammes Mermaid restent en source brute. Préférer la version Rust pour un rendu fidèle.

SEO & AI Search Readiness

Optimisé pour indexation Google + découverte AI search (ChatGPT, Claude, Perplexity). Voir seo/AUDIT.md pour le rapport détaillé (score 88 %).

Artefacts générés automatiquement au build

book/
├── robots.txt          # bots IA autorisés (GPTBot, ClaudeBot, PerplexityBot, Google-Extended)
├── llms.txt            # manifest llmstxt.org avec 25+ liens directs
├── sitemap.xml         # index des 6 sitemaps par langue
└── <lang>/sitemap.xml  # 95 URLs/lang avec hreflang + priorité Diátaxis

Chaque page HTML contient :

<link rel="canonical"> pointant vers l'URL publiée
6 <link rel="alternate" hreflang="…"> + x-default
OpenGraph + Twitter Cards complets
JSON-LD @graph : Organization + WebSite + TechArticle

Configuration dans theme/head.hbs. Post-traitement dans scripts/seo-postbuild.sh — appelé automatiquement par build-all-langs.sh.

Changer l'URL de publication

Par défaut https://demo.gitrust.eu/docs. Pour un staging :

SITE_BASE_URL=https://staging.example.com/docs ./scripts/build-all-langs.sh

Captures d'écran (Playwright)

Les tutoriels user_manual/ et administration_manual/ référencent des captures dans screenshots/. Le script Playwright s'authentifie sur une instance gitrust et prend les captures automatiquement :

GITRUST_URL=https://votre-instance.example \
GITRUST_USER=votre-login \
GITRUST_PASS='votre-mot-de-passe' \
node scripts/screenshot-runner/capture.mjs

Structure du dépôt

girust_doc/
├── book.toml                   # config mdBook (thème gitrust, mermaid, i18n)
├── src/                        # sources mdBook (FR canonique)
│   ├── SUMMARY.md              # table des matières globale
│   ├── introduction.md
│   └── <manuel>/               # symlinks vers les 4 manuels racine
├── user_manual/                # ┐
├── administration_manual/      # ├ 4 manuels × 4 dossiers Diátaxis
├── developer_manual/           # ┤   (tutorials/ how-to/ reference/ explanation/)
├── template/                   # ┘
├── diagrams/                   # sources Mermaid partagées (.mmd)
├── po/                         # traductions gettext (en, de, es, pt, it)
├── screenshots/                # captures Playwright + placeholders
├── theme/                      # thème mdBook (palette gitrust + head.hbs SEO)
├── seo/                        # robots.txt, llms.txt, AUDIT.md
├── pdf/                        # sortie PDF par langue (gitignoré)
├── book/                       # sortie mdBook par langue (gitignoré)
├── .dagger/                    # module Dagger Python (pipeline CI)
├── scripts/
│   ├── build-all-langs.sh      # builde les 6 langues + SEO postbuild
│   ├── build-pdf.py            # export PDF (weasyprint, sans JS)
│   ├── build-pdf/              # export PDF (Rust → wkhtmltopdf / chromium)
│   ├── seo-postbuild.sh        # génère sitemap, robots, llms
│   └── screenshot-runner/      # Playwright (capture.mjs, capture-usermanual.mjs)
├── .plans/                     # plans de travail versionnés
├── .github/workflows/          # CI GitHub Actions (build + lint)
├── CONTRIBUTING.md             # workflow PR, Diátaxis, pédagogie, i18n
├── .markdownlint.yaml
└── .gitignore

Contribuer

Lire CONTRIBUTING.md avant toute PR. Points clés :

Choisir le mode Diátaxis avant de créer un fichier (tutorial / how-to / reference / explanation).
Tutoriels : respecter la checklist pédagogique (objectifs Bloom, prérequis, checkpoints, troubleshoot, récap).
Mermaid : source unique par diagramme dans diagrams/.
Traduction : modifier uniquement les po/*.po, jamais les .md non-FR.
Screenshots : via Playwright, pas en ligne de commande manuelle.

État du projet

Indicateur	Valeur
Pages Markdown	94
Stubs restants	0
Langues buildées	6 (fr + en, de, es, pt, it)
URLs indexées (sitemap)	570 (95 × 6)
Pages tutorielles avec template pédagogique	8 (3 user + 3 admin + 2 dev)
Captures d'écran (Playwright + placeholders)	42
Diagrammes Mermaid centralisés	dans `diagrams/` + inline dans les `.md`
Pipeline CI	Dagger Python + GitHub Actions YAML
Export PDF	Rust (wkhtmltopdf, défaut) ou Python (weasyprint) → `pdf/`
SEO score (cf. `seo/AUDIT.md`)	88 / 100

Licence

Documentation publiée sous CC BY 4.0. Module Dagger et scripts sous même licence que gitrust (voir dépôt principal).

Eric / documentation