112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
---
|
|
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
|