kyopages/docs/about/mkdocs.md

mkdocs

liens

• gitlab.com/pages/mkdocs
• Les Gitlab Pages débarquent dans Framagit !
• www.mkdocs.org
• Change log à partir 0.16

install en local pour dev

** ne pas utiliser apt, paquet périmé et localisation incompatible avec les thèmes additionnels** (2017)

su
apt install python-pip
pip install mkdocs
mkdocs --version
	# mkdocs, version 0.17.3
exit

pour info

pip uninstall paquet
pip install -U paquet 
	# -U = --upgrade
pip download paquet

localisation du programme

	/usr/local/lib/python2.7/dist-packages/mkdocs
	/usr/local/lib/python2.7/dist-packages/mkdocs/assets/search/mkdocs
	/usr/local/lib/python2.7/dist-packages/mkdocs/themes/mkdocs
	/usr/local/bin/mkdocs
	/usr/share/mkdocs

récup thème du paquet:

cp -r /usr/local/lib/python2.7/dist-packages/mkdocs/themes/mkdocs/ ../

installation d'un thème

pip install mkdocs-material
	#localisation: /usr/local/lib/python2.7/dist-packages/material

création d'un nouveau site

mkdocs new kyopages
cd kyopages

• toutes la configuation et la déclaration des pages dans:

mkdocs.yml

organisation pages

mkdocs.yml
docs/
	autreDirectory/
		autre.md
	index.md
	...
sites/
	# pages html générées

développement, build auto

• démarrer un serveur local, build et rafraîchissement automatique du navigateur

mkdocs serve

on peut utiliser

mkdocs serve  --dirtyreload

mais le build sera sur la page uniquement, sans rechargement profond du navigateur (css notamment?). réserver au dev donc.

• lancer firefox sur http://localhost:8000

build manuel

dans ce cas, un répertoire de pages html (site/) est créé à côté du répertoire des pages markdown (docs/ par défaut). ce répertoire site est à poussé une site de pages statiques, à la différence de docs où les pages doivent être générées en ligne.
dans le même ordre d'idée, on peut utiliser:

mkdocs build --dirty

incidences à voir

thème mkdocs

• allègement hightlight.js avec seulement les langages:
  bash css diff html/xml http ini json javascript makefile markdown python shell(-session)
text désactive la coloration syntaxique
• manuel