Transforme des documents collaboratifs Docs en site statique avec Zensical. Homepage stylisée incluse.

Exemple : Document source → Site généré

Requiert Python 3.14+ et uv.

# 1. Cloner le projet
git clone git@github.com:CoopCodeCommun/Docs2static.git
cd Docs2static

# 2. Installer les dépendances
uv sync

# 3. Configurer
cp env_example .env
# Éditez .env : au minimum DOCS_URL (URL de votre document Docs racine)

# 4. Build du site (fetch + génération markdown + assets)
make build

# 5. Servir localement (live reload)
make serve   # → http://localhost:8000

Le .env suivant produit le site CoopCodeCommun.github.io/Docs2static :

DOCS_URL=https://notes.liiib.re/docs/fa5583b2-37fc-4016-998f-f5237fd41642/
GITHUB_REPO=https://github.com/CoopCodeCommun/Docs2static
BACKEND=zensical

Pour déployer sur GitHub/GitLab Pages (mainteneurs uniquement, nécessite une clé SSH avec write access) :

uv run docs2static --deploy

Cette commande build et force-push le site dans la branche gh-pages (ou gl-pages pour GitLab) du dépôt configuré dans GITHUB_REPO / GITLAB_REPO. La page Mentions légales, le CNAME (si domaine custom), robots.txt, humans.txt et sitemap.xml sont régénérés à chaque deploy.

make audit invoque le skill docs-content-curator (embarqué dans .claude/skills/) qui lit vos Docs source via le MCP lasuite-docs et vérifie :

• Frontmatter : clés obligatoires (titre), recommandées (résumé, auteur·ice, image), orthographes
• Images : alt text, format (WebP/AVIF), dimensions raisonnables
• SEO : longueur title/description, unicité H1, canonical, Open Graph
• Données structurées : Schema.org JSON-LD (Organization, Event, Article…), BreadcrumbList
• Mentions légales : page auto-générée par défaut, ou page custom via legal_url:
• FAQ : suggestion de page FAQPage Schema.org

Sortie : rapport structuré (✅ / ⚠️ / ❌ / 💡) avec score /100 et patches optionnels appliqués via MCP (confirmation explicite requise avant écriture). Pré-requis : CLI Claude Code installée et MCP lasuite-docs configuré.

Ajoutez un bloc frontmatter au debut de vos documents Docs :

---
titre: Ma page
auteur·ice: Jonas
brouillon: non
resume: Description de la page
date: 2026-01-15
---

Dans le document racine Docs :

• 1re image → logo du site (logo_file dans les metadonnees)
• 2e image → image hero de fond (hero_image dans les metadonnees)

Docs2Static extrait automatiquement ces champs si absents du frontmatter :

Le template par defaut est phantom (inspire de HTML5UP Phantom). La homepage est generee dynamiquement depuis l'arbre de navigation : chaque section enfant devient une tuile coloree avec image, titre et extrait.

Pour changer de template :

# Dans le frontmatter du document racine
template: phantom

Ou via variable d'environnement :

TEMPLATE=phantom

Les templates sont stockes dans docs2static/assets/templates/{nom}/ avec les sous-dossiers overrides/ et stylesheets/.

Pour integrer un contenu externe (agenda, formulaire, etc.), ajoutez une cle iframe dans le frontmatter :

---
iframe: src="https://example.com/embed/" width="100%" height="1000px"
---

L'iframe sera affichee sous le contenu de la page.

docs2static/
  main.py                # Orchestration : API, arbre, frontmatter, images
  zensical_backend.py    # Integration Zensical : navigation, toml, deploiement
  assets/templates/      # Templates homepage (phantom, etc.)
    phantom/
      overrides/         # Surcharge du theme Zensical (main.html)
      stylesheets/       # CSS homepage (home.css)

Pipeline : Docs API -> arbre -> frontmatter -> images -> Markdown -> Zensical build -> deploy

Pour plus de details, voir guideline.md.

uv run python -m pytest tests/

# Avec options
uv run python tests/test_main.py --no-cache     # Sans cache
uv run python tests/test_main.py --deploy        # Test deploiement reel
uv run python tests/test_main.py --test-zensical # Test rendu interactif

Un token PyPI est nécessaire pour publier. Le générer sur pypi.org → Account settings → API tokens.

Stocker le token dans un gestionnaire de secrets (KeePass, Vault, Bitwarden, etc.) — ne jamais le committer.

Pour éviter de le ressaisir à chaque fois, l'exporter comme variable d'environnement :

export UV_PUBLISH_TOKEN=pypi-...

# 1. Mettre à jour la version dans pyproject.toml
#    version = "X.Y.Z"

# 2. Mettre à jour CHANGELOG.md

# 3. Builder, publier, tagger et pousser
make release

Apache 2.0 - Voir LICENSE.

• Inspire par le travail de Sylvain Zimmer (stack Node.js).
• Developpe par CoopCodeCommun en Python, style FALC.