---
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
