Bases

Installation, premiers pas et structure d'un projet ProperDocs (fork de MkDocs 1.x).

Installation

pip install properdocs

Alternative

Si la commande n'est pas reconnue :

python -m pip install properdocs
python -m properdocs --version

Créer un projet

properdocs new mon-projet
cd mon-projet

Cela génère la structure suivante :

mon-projet/
├── properdocs.yml    # Fichier de configuration
└── docs/
    └── index.md      # Page d'accueil

Commandes essentielles

Commande	Description
`properdocs new [dossier]`	Créer un nouveau projet
`properdocs serve`	Lancer le serveur de dev (hot-reload)
`properdocs build`	Générer le site statique
`properdocs build --strict`	Build avec erreurs fatales (liens cassés, etc.)
`properdocs gh-deploy`	Déployer sur GitHub Pages

# Serveur local avec port personnalisé
properdocs serve --dev-addr=127.0.0.1:8001

# Build optimisé
properdocs build --strict

Fichier de configuration

Le fichier properdocs.yml est le cœur du projet. Il contient :

site_name: MonSite
site_url: https://exemple.github.io/mon-site/

theme:
  name: material
  language: fr

nav:
  - Accueil: index.md
  - Guide: guide.md

plugins:
  - search

markdown_extensions:
  - admonition
  - pymdownx.highlight

Migration depuis MkDocs

Si vous veniez de MkDocs, remplacez simplement : - pip install mkdocs → pip install properdocs - mkdocs build → properdocs build - mkdocs.yml → properdocs.yml - Le reste est identique (mêmes plugins, thèmes et extensions).

Structure recommandée

mon-projet/
├── properdocs.yml
├── docs/
│   ├── index.md
│   ├── css/
│   │   └── custom.css
│   ├── images/
│   └── ...
└── site/              # Généré automatiquement (à gitignorer)

Ne pas commit le dossier site/

Ajoutez site/ à votre .gitignore - c'est le build généré.