Initial vault setup

2026-06-09 18:40:21 +02:00
commit bda02d587f
3692 changed files with 402457 additions and 0 deletions
@@ -0,0 +1,125 @@
+---
+title: Zensical
+created: 2026-06-07
+updated: 2026-06-07
+type: app
+tags: [catalogue, static-site, documentation, markdown, zensical, material-for-mkdocs, python, rust]
+confidence: high
+contested: false
+sources: [https://selfh.st/apps/?tag=Static-Site, https://zensical.org/docs/get-started/, https://github.com/zensical/zensical]
+---
+
+# 📚 Zensical
+
+> **Le générateur de site statique moderne pour la documentation**, conçu par l'équipe derrière Material for MkDocs, avec une approche « batteries included » et une forte compatibilité avec les usages docs modernes.
+
+## 📋 Informations Générales
+
+| Champ | Valeur |
+| :--- | :--- |
+| **Site web** | [zensical.org/docs](https://zensical.org/docs/) |
+| **GitHub** | [zensical/zensical](https://github.com/zensical/zensical) |
+| **Licence** | MIT |
+| **Langage** | Rust, Python |
+| **Étoiles GitHub** | 4.9k ⭐ |
+| **Dernière MAJ** | 2026-06-05 |
+| **Catégorie** | [[cat-static-site|Static Site]] |
+
+## 📝 Description
+
+**Zensical** est un **générateur de site statique orienté documentation**. Le projet est développé par les créateurs de **Material for MkDocs** et vise à produire rapidement des documentations Markdown avec une expérience moderne, une recherche intégrée, des options de personnalisation avancées et un rendu propre sur desktop comme mobile.
+
+La documentation officielle insiste sur un positionnement **simple à prendre en main**, mais suffisamment riche pour couvrir des besoins plus avancés. Le dépôt indique aussi une base technique mixte **Rust + Python**, ce qui suggère un moteur orienté performance tout en restant accessible à l'écosystème Python.
+
+Zensical convient surtout à :
+
+- des **documentations de projet** ;
+- des **sites de docs open source** ;
+- des **portails techniques internes** ;
+- des équipes qui apprécient déjà l'écosystème **MkDocs / Material for MkDocs**.
+
+Points notables :
+
+- ✅ Générateur **statique** spécialisé documentation
+- ✅ Contenu en **Markdown**
+- ✅ Développé par l'équipe derrière **Material for MkDocs**
+- ✅ Distribution officielle via **PyPI**
+- ✅ Support d'un **workflow Docker** pour prévisualisation et build
+- ✅ Orienté **recherche**, personnalisation et multi-langue
+
+## 🚀 Installation
+
+### Option recommandée : installation native Python
+
+Pour **Zensical**, l'installation native est la plus logique : ce n'est pas un service à faire tourner en continu, mais un **outil de build**.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install zensical
+```
+
+### Option avec `uv`
+
+```bash
+uv init
+uv add --dev zensical
+uv run zensical
+```
+
+### Option Docker
+
+La documentation mentionne une image officielle Docker, mais **pour les builds et previews**, pas pour l'hébergement du site final.
+
+```bash
+docker run --rm -it \
+  -v "$PWD":/docs \
+  zensical/zensical
+```
+
+## ⚙️ Configuration Initiale
+
+1. **Créer ou importer** votre documentation Markdown.
+2. **Installer Zensical** dans un environnement virtuel Python.
+3. **Lancer le binaire** via `zensical` ou `uv run zensical` selon votre méthode d'installation.
+4. **Configurer le projet** selon la structure attendue par la documentation officielle.
+5. **Générer le site statique** puis publier le répertoire de sortie sur votre hébergement HTTP habituel (Nginx, Caddy, GitHub Pages, stockage objet, etc.).
+
+Si vous venez de MkDocs, surveillez particulièrement les points de compatibilité, de thèmes et d'extensions avant une migration complète.
+
+## 🔄 Alternatives
+
+### Open Source
+- **ProperDocs** — Fork de MkDocs visant une compatibilité maximale
+- **MkDocs** — Référence historique pour la documentation Markdown
+- **Hugo** — Générateur statique très rapide, plus généraliste
+- **Docusaurus** — Documentation statique orientée développeurs, écosystème React
+- **Jekyll** — Classique historique dans l'univers GitHub Pages
+
+### Propriétaires
+- **Read the Docs for Business**
+- **GitBook**
+- **Confluence**
+- **Document360**
+
+## 🔐 Sécurité
+
+- ✅ Le site généré est **statique**, donc avec une surface d'attaque runtime réduite
+- ⚠️ La sécurité dépend surtout de la **chaîne de build** et des **plugins/extensions** utilisés
+- ✅ Isolez le build dans un **venv** ou un conteneur dédié
+- ✅ Hébergez le résultat final derrière **HTTPS**
+- ⚠️ Vérifiez les secrets accidentellement committés dans la documentation source
+- ✅ Si publication CI/CD, limitez les permissions des tokens Git et des runners
+
+## 📚 Ressources
+
+- [Documentation officielle](https://zensical.org/docs/)
+- [Guide de démarrage](https://zensical.org/docs/get-started/)
+- [GitHub zensical/zensical](https://github.com/zensical/zensical)
+- [Docker Hub zensical/zensical](https://hub.docker.com/r/zensical/zensical)
+
+## Pages Liées
+
+- [[cat-static-site]] — Vue d'ensemble de la catégorie Static Site
+- [[app-properdocs]] — Alternative proche pour la documentation
+- [[app-zaneops]] — Plateforme pouvant déployer des sites statiques