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,111 @@
+---
+title: ProperDocs
+created: 2026-06-07
+updated: 2026-06-07
+type: app
+tags: [catalogue, static-site, documentation, markdown, properdocs, mkdocs, python, docs]
+confidence: high
+contested: false
+sources: [https://selfh.st/apps/?tag=Static-Site, https://properdocs.org/getting-started/, https://github.com/ProperDocs/properdocs]
+---
+
+# 🧾 ProperDocs
+
+> **Le fork de MkDocs pensé comme remplacement direct**, pour continuer à produire de la documentation statique en Markdown avec thèmes, plugins et workflow familiers.
+
+## 📋 Informations Générales
+
+| Champ | Valeur |
+| :--- | :--- |
+| **Site web** | [properdocs.org](https://properdocs.org/) |
+| **GitHub** | [ProperDocs/properdocs](https://github.com/ProperDocs/properdocs) |
+| **Licence** | BSD-2-Clause |
+| **Langage** | Python |
+| **Étoiles GitHub** | 230 ⭐ |
+| **Dernière MAJ** | 2026-04-07 |
+| **Catégorie** | [[cat-static-site|Static Site]] |
+
+## 📝 Description
+
+**ProperDocs** est un **fork de MkDocs** qui se présente comme un **drop-in replacement**. Le dépôt explique que l'objectif est de conserver la compatibilité générale de l'écosystème MkDocs tout en se concentrant sur des **correctifs**, des **évolutions incrémentales** et une continuité de maintenance.
+
+Comme MkDocs, ProperDocs sert à construire des **sites statiques de documentation** à partir de fichiers **Markdown** et d'un fichier de configuration **YAML** (`properdocs.yml`). Il propose un serveur de développement, un système de thèmes, des plugins, des extensions Markdown et une génération de sortie totalement statique, publiable sur n'importe quel hébergement HTTP.
+
+Il sera surtout pertinent pour :
+
+- les équipes déjà habituées à **MkDocs** ;
+- les projets qui veulent une **migration douce** ;
+- les documentations techniques qui privilégient **Markdown + YAML**.
+
+## 🚀 Installation
+
+### Option recommandée : installation Python + thème
+
+```bash
+pip install properdocs properdocs-theme-mkdocs
+```
+
+### Création d'un nouveau projet
+
+```bash
+properdocs new mon-projet
+cd mon-projet
+properdocs serve
+```
+
+### Build statique
+
+```bash
+properdocs build
+```
+
+Le contenu généré est ensuite placé dans le répertoire `site/`.
+
+## ⚙️ Configuration Initiale
+
+1. **Installer ProperDocs** et au moins un thème.
+2. **Créer un projet** avec `properdocs new`.
+3. **Éditer `properdocs.yml`**, où `site_name` est le paramètre minimal requis.
+4. **Ajouter vos fichiers Markdown** dans `docs/`.
+5. **Lancer `properdocs serve`** pour prévisualiser le rendu en local.
+6. **Construire le site** avec `properdocs build`.
+7. **Publier le contenu de `site/`** sur l'hébergement de votre choix.
+
+Si vous migrez depuis MkDocs, vérifiez la compatibilité de vos thèmes, plugins et extensions les moins courants.
+
+## 🔄 Alternatives
+
+### Open Source
+- **MkDocs** — Le projet d'origine et le point de référence historique
+- **Zensical** — Générateur docs moderne par l'équipe Material for MkDocs
+- **Docusaurus** — Approche docs plus orientée React
+- **Hugo** — Très performant, plus généraliste
+- **Sphinx** — Très utilisé dans l'écosystème Python
+
+### Propriétaires
+- **GitBook**
+- **Read the Docs for Business**
+- **Confluence**
+- **Notion Sites**
+
+## 🔐 Sécurité
+
+- ✅ Le site généré est **statique**, donc simple à exposer
+- ⚠️ Les **plugins tiers** et extensions Markdown restent le principal point de vigilance
+- ✅ Isolez l'environnement Python du build
+- ✅ Évitez de publier par erreur le dossier source avec secrets, brouillons ou fichiers internes
+- ✅ Activez **HTTPS** sur l'hébergement final
+- ⚠️ Vérifiez la compatibilité et la maintenance des thèmes tiers avant usage en production
+
+## 📚 Ressources
+
+- [Site officiel](https://properdocs.org/)
+- [Guide de démarrage](https://properdocs.org/getting-started/)
+- [GitHub ProperDocs/properdocs](https://github.com/ProperDocs/properdocs)
+- [Catalog des thèmes et plugins](https://github.com/ProperDocs/catalog)
+
+## Pages Liées
+
+- [[cat-static-site]] — Vue d'ensemble de la catégorie Static Site
+- [[app-zensical]] — Autre générateur orienté documentation
+- [[app-tinyfeed]] — Génération statique plus minimaliste