MkDocs

MkDocs est un générateur de sites statiques rapide, simple et élégant,conçu pour la création de documentation de projet. Les fichiers sources de documentation sont écrits en Markdown et configurés à l'aide d'un unique fichier YAML.

Caractéristiques

De superbes thèmes disponibles.
Facile à personaliser.
Previsualiser votre site pendant que vous travaillez.
Hébergé n'importe ou.

Installation

Pour installer Mkdocs, exécuter la commande suivante depuis la ligne de commande :

> pip install mkdocs

Attention

Si mkdocs n'est pas disponible alors il faut passer par python :

> python -m pip install mkdocs        # installe la commande
> python -m mkdocs                    # préface de chaque commande mkdocs

Pour vérifier la version :

> python -m mkdocs --version

Création d'un nouveau projet

Pour créer un nouveau projet, exécuter la commande suivante :

> mkdocs new my-project

Mkdocs intègre un serveur de développement qui permet de prévisualiser votre documentation pendant que vous travaillez dessus. Pour ce faire, assurez-vous d'étre dans le meme repertoire que le fichier mkdocs.yml (qui est le fichier de configuration).

> python -m mkdocs serve
> mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.22 seconds
INFO    -  [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [15:50:43] Serving on http://127.0.0.1:8000/

Pour le chargement automatique :

python -m mkdocs serve --livereload

Commandes

mkdocs new [nom-dossier] - Créez un nouveau projet.
mkdocs serve - Démarrez le serveur de documentation avec rechargement en direct.
mkdocs build - Générez le site de documentation.
mkdocs -h - Affichez le message d'aide et quittez.

> mkdocs serve --dev-addr=127.0.0.1:8001    # Lance le serveur.
> mkdocs build                              # Génére le site de documentation.

Structure du projet

    mkdocs.yml    # Le fichier de configuration.
    docs/
        index.md  # La page d'accueil de la documentation.
        ...       # Autres pages markdown, images et autres fichiers.

Voici la liste des thèmes disponibles par défaut avec MkDocs :

    mkdocs (thème par défaut)
    readthedocs
    material (nécessite une installation supplémentaire)
    windmill
    bootstrap
    slate
    cyborg
    simplex
    superhero
    united
    cosmo
    yeti
    cerulean
    flatly
    journal
    lumen
    paper
    sandstone
    spacelab

Pour installer un théme :

pip install mkdocs-material     #instale le theme material

Crée un dossier overrides/ à la racine de ton projet

mkdir overrides

Dans ce dossier, crée le chemin

overrides/main.html

Ajoute ce contenu dans overrides/main.html

{% extends "base.html" %}

{% block footer %}
<!-- Footer désactivé -->
{% endblock %}

Dans ton mkdocs.yml, indique l’override

theme:
  name: mkdocs  # ou readthedocs
  custom_dir: overrides

Note

Texte de la note.

Astuce

Texte de l'astuce.

Attention

Texte d'avertissement.

Danger

Texte de danger.

Information

Texte informatif.

Titre du bloc

Contenu caché par défaut.

Titre du bloc

Contenu visible par défaut.