Docs2Static 🚀

Français | English

---

Français

Docs2Static est un outil en Python permettant de transformer des documents édités collaborativement sur Docs (basé sur BlockNote) en un site web statique professionnel.

🌟 Principes

• Récupération récursive : Télécharge automatiquement toute l'arborescence (pages enfants, petits-enfants, etc.).
• Conversion intelligente : Transforme le contenu en Markdown propre pour les générateurs de sites statiques.
• Gestion des médias : Télécharge les images localement et met à jour les liens automatiquement.
• Intégration Zensical : Configure et construit automatiquement votre site avec le moteur Zensical.
• Déploiement automatisé : Publie votre site sur GitHub Pages ou GitLab Pages en une seule commande via SSH.

🛠️ Installation

Ce projet utilise uv pour la gestion des dépendances.

# Cloner le dépôt
git clone <votre-depot>
cd Docs2static

# Installer les dépendances
uv sync

⚙️ Configuration

Copiez le fichier d'exemple et remplissez-le avec vos informations :

cp env_example .env

Variables dans le .env :

• DOCS_URL : L'URL de votre document Docs racine.
• GITHUB_REPO : L'adresse SSH de votre dépôt GitHub (ex: git@github.com:User/Repo.git).
• GITLAB_REPO : L'adresse SSH de votre dépôt GitLab (alternative).
• BACKEND : Le moteur statique utilisé (par défaut : zensical).

🚀 Utilisation

1. Télécharger les documents

Télécharge le contenu depuis Docs et prépare la structure locale dans content/source :

uv run python3 main.py

2. Déployer sur GitHub Pages

Génère le site statique et l'envoie sur la branche gh-pages :

uv run python3 main.py --deploy

Options disponibles :

• -f, --format : Choisir le format (html, markdown ou both).
• --no-cache : Forcer le téléchargement sans utiliser le cache local.
• -b, --backend : Spécifier le backend (ex: zensical).
• -d, --deploy : Déployer sans retélécharger les fichiers.

🧪 Tests

Pour vérifier que tout fonctionne correctement avec des données réelles :

uv run python3 test_main.py

---

English

Docs2Static is a Python tool that transforms collaborative documents from Docs (based on BlockNote) into a professional static website.

🌟 Principles

• Recursive Fetching: Automatically downloads the entire tree structure (children, grandchildren, etc.).
• Smart Conversion: Converts content into clean Markdown for static site generators.
• Media Management: Downloads images locally and updates links automatically.
• Zensical Integration: Automatically configures and builds your site using the Zensical engine.
• Automated Deployment: Publishes your site to GitHub Pages or GitLab Pages in a single command via SSH.

🛠️ Installation

This project uses uv for dependency management.

# Clone the repository
git clone <your-repo>
cd Docs2static

# Install dependencies
uv sync

⚙️ Configuration

Copy the example file and fill it with your information:

cp env_example .env

Variables in .env:

• DOCS_URL: The URL of your root Docs document.
• GITHUB_REPO: The SSH address of your GitHub repository (e.g., git@github.com:User/Repo.git).
• GITLAB_REPO: The SSH address of your GitLab repository (alternative).
• BACKEND: The static engine used (default: zensical).

🚀 Usage

1. Download documents

Downloads content from Docs and prepares the local structure in content/source:

uv run python3 main.py

2. Deploy to GitHub Pages

Generates the static site and pushes it to the gh-pages branch:

uv run python3 main.py --deploy

Available options:

• -f, --format: Choose the format (html, markdown, or both).
• --no-cache: Force download without using local cache.
• -b, --backend: Specify the backend (e.g., zensical).
• -d, --deploy: Deploy without re-downloading files.

🧪 Testing

To verify everything works correctly with real data:

uv run python3 test_main.py

---

🙌 Credits / Inspiration

• Inspired by the work of Sylvain Zimmer who uses a Node.js stack for a similar result.
• Developed in Python to offer a simple and accessible alternative (FALC style).