MkDocs est un outil de génération de documentation statique.
Les pages sont rédigées au format Markdown, et la configuration au format YAML.
La phase de création des pages peut se faire en mode live, et la génération se build très rapidement en une ligne de commande.
La documentation générée possède un menu, une barre de recherche, et plusieurs thèmes disponibles.
Installation
sudo apt install mkdocs
Initialisation d’une documentation
mkdocs new my-app
Visualisation de la documentation en mode live
mkdocs serve
Exemple simple de configuration du fichier mkdocs.yml
site_name: MyApp
pages:
- Home: index.md
- About: about.md
theme: readthedocs
Génération de la doc au format HTML
mkdocs build
Résultat
D’autres thèmes sont disponibles sur le repository GitHub MkDocs-Themes
Exemple avec une configuration plus poussée
site_name: MyApp
copyright: 'Copyright © 2017 - 2018 Louis'
pages:
- Accueil: index.md
- About: about.md
theme:
language: fr
name: material
palette:
primary: indigo
accent: indigo
markdown_extensions:
- admonition
- footnotes
- codehilite:
guess_lang: false
- toc:
permalink: true
Bonjour
Quand je fait un mkdocs build pour générer mon site, le dossier site est crée avec un index.html et quand je vais sur mon url j’ai http://mon_site/site.
Y a t’il moyen de réécrire en http://mon_site ?
cdt
Bonjour Mickael,
Tu peux déplacer le contenu du dossier site/ directement à la racine de ton hébergement web.
Les fichiers .yml en amont sont utiles seulement pour la génération, ils n’ont pas vocation à être envoyer sur ton espace web.