Besoin d'un site statique rapide et efficace pour documenter votre travail de développement ? nous avons vu qu'avec Hugo ou un Wiki du type Dokuwiki cela pouvait être très facile, cependant il existe une alternative intéressante avec le projet Mkdocs. Ce générateur de site web statique spécialisé dans la documentation en ligne est conçu en Python et s'avère vraiment trés simple à utiliser et à déployer. Nous allons donc nous amuser à tenter un déploiement en utilisant les services d'hébergement statique, Github Pages ou Amazon S3.

mm

Installation

On commence par ouvrir le terminal de son Mac ou son Linux et :

sudo easyinstall pip

On crée un nouveau projet, puis on s'y positionne

mkdocs new my-project

cd my-project

initial-layout

On démarre alors le serveur de développement qui ouvre le port 8000

Capture-d-e-cran-2018-03-10-a--17.09.40

mkdocs serve

Capture-d-e-cran-2018-03-10-a--17.03.13

Pour créer de nouvelles pages dans sa documentation :

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

On modifie ensuite le fichier de configuration principal, mkdocs.yml

Capture-d-e-cran-2018-03-10-a--17.22.01

Ce qui nous fait apparaître les élèments suivants (next, previous) sur la capture suivante au reload du serveur de développemnt :

Capture-d-e-cran-2018-03-11-a--14.52.04

Vous avez également dû noter une différence dans le style de la page, j'ai en effet modifié le thème en passant par ici via :

sudo pip install mkdocs-material

Ce qui va nous permettre de modifier le thème de notre site depuis le fichier mkdocs.yml

Capture-d-e-cran-2018-03-10-a--17.22.01-1

Déployer notre site sur Github Pages

Le lien vers mon repo : https://github.com/gabrielsagnard/docs.github.io

et voici en live le déploiement :

Capture-d-e-cran-2018-03-11-a--17.55.29

Et voici le lien du site :

https://gabrielsagnard.github.io/docs.github.io/

Comment j'ai déployé le site ?

mkdocs gh-deploy

Cette commande va créer un sous-répertoire site qui est le repertoire à importer dans Github Pages pour en assurer le déploiement, tout simplement.