126 lines
4.9 KiB
Markdown
126 lines
4.9 KiB
Markdown
---
|
|
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
|