docs2static 0.1.0

Fetch collaborative documents from a Docs instance and generate static sites with Zensical

Docs2Static

Transforme des documents collaboratifs Docs en site statique avec Zensical. Homepage stylisee incluse.

Exemple : Document source -> Site genere

Installation

# Avec pip
pip install docs2static

# Avec uv
uv add docs2static

# Depuis les sources
git clone [e-mail]:CoopCodeCommun/Docs2static.git
cd Docs2static
uv sync

Requiert Python 3.14+.

Configuration

cp env_example .env

Variables dans le .env :

Variable	Description
DOCS_URL	URL du document Docs racine
GITHUB_REPO	Adresse SSH du depot GitHub (ex: [e-mail]:User/Repo.git)
GITLAB_REPO	Adresse SSH du depot GitLab (alternative)
BACKEND	Moteur statique (par defaut : zensical)

Usage CLI

# Telecharger les documents et construire le site
docs2static

# Deployer sur GitHub/GitLab Pages (sans retelecharger)
docs2static --deploy

# Forcer le telechargement sans cache
docs2static --no-cache

# Specifier le format de sortie
docs2static -f html        # html, markdown ou both

Options

Option	Description
-f, --format	Format de sortie (html, markdown, both)
--no-cache	Ignorer le cache SQLite (24h par defaut)
-b, --backend	Moteur de site statique
-d, --deploy	Deployer sans retelecharger

Metadonnees (frontmatter)

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
---

Cle (FR / EN)	Usage
titre / title	Titre de la page
auteur·ice / author	Auteur du site (copyright)
resume / summary	Description du site ou extrait
licence / license	Licence affichee dans le copyright
brouillon / draft	oui / true = page et enfants ignores
date	Date du document (AAAA-MM-JJ)

Deploiement en production

GitHub Actions

Creez .github/workflows/docs2static.yml :

name: Build & Deploy Documentation

on:
  schedule:
    - cron: '0 6 * * *'   # Tous les jours a 6h
  workflow_dispatch:        # Lancement manuel

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Setup Python
        run: uv python install 3.14

      - name: Install docs2static
        run: uv add docs2static

      - name: Build & Deploy
        env:
          DOCS_URL: ${{ secrets.DOCS_URL }}
          GITHUB_REPO: ${{ secrets.GITHUB_REPO }}
          BACKEND: zensical
        run: |
          uv run docs2static
          uv run docs2static --deploy

Ajoutez les secrets DOCS_URL et GITHUB_REPO dans les parametres du depot. Configurez une cle SSH de deploiement avec acces en ecriture au depot cible.

GitLab CI

Creez .gitlab-ci.yml :

pages:
  image: python:3.14
  stage: deploy
  script:
    - pip install uv
    - uv add docs2static
    - uv run docs2static
    - uv run docs2static --deploy
  variables:
    DOCS_URL: $DOCS_URL
    GITLAB_REPO: $GITLAB_REPO
    BACKEND: zensical
  only:
    - schedules
    - web

Ajoutez les variables DOCS_URL et GITLAB_REPO dans CI/CD > Variables.

Deploiement manuel (serveur)

# Installation
pip install docs2static

# Configuration
export DOCS_URL="https://notes.liiib.re/docs/votre-doc-id/"
export GITHUB_REPO="[e-mail]:Org/Repo.git"
export BACKEND="zensical"

# Execution
docs2static              # Telecharge + build
docs2static --deploy     # Deploie sur Pages

# Cron (optionnel)
echo "0 6 * * * cd /opt/docs && docs2static && docs2static --deploy" | crontab -

Architecture

docs2static/
  main.py                # Orchestration : API, arbre, frontmatter, images
  zensical_backend.py    # Integration Zensical : navigation, toml, deploiement
  assets/                # Template homepage + CSS embarques

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

Pour plus de details, voir guideline.md.

Tests

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

Licence

Apache 2.0 - Voir LICENSE.

Credits

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