2018-03-21 03:44:25 +01:00
|
|
|
# mkdocs
|
2017-06-01 09:50:15 +02:00
|
|
|
|
|
|
|
## liens
|
2017-06-13 12:01:10 +02:00
|
|
|
|
2017-06-01 09:50:15 +02:00
|
|
|
* [gitlab.com/pages/mkdocs](https://gitlab.com/pages/mkdocs)
|
|
|
|
* [Les Gitlab Pages débarquent dans Framagit !](https://framablog.org/2017/03/20/les-gitlab-pages-debarquent-dans-framagit/)
|
|
|
|
* [www.mkdocs.org](http://www.mkdocs.org/)
|
2017-06-13 12:01:10 +02:00
|
|
|
* [Change log à partir 0.16](http://www.mkdocs.org/about/release-notes/#version-016-2016-11-04)
|
2017-06-01 11:21:03 +02:00
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
|
2017-06-01 11:21:03 +02:00
|
|
|
## install en local pour dev
|
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
** ne pas utiliser apt, paquet périmé et localisation incompatible avec les thèmes additionnels** (2017)
|
2017-06-01 11:21:03 +02:00
|
|
|
```shell
|
|
|
|
su
|
2017-08-02 01:16:04 +02:00
|
|
|
apt install python-pip
|
2017-06-01 11:21:03 +02:00
|
|
|
pip install mkdocs
|
|
|
|
mkdocs --version
|
2018-03-21 03:44:25 +01:00
|
|
|
# mkdocs, version 0.17.3
|
2017-06-01 11:21:03 +02:00
|
|
|
exit
|
|
|
|
```
|
2017-06-13 12:01:10 +02:00
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
## pour info
|
|
|
|
|
|
|
|
|
|
|
|
```shell
|
|
|
|
pip uninstall paquet
|
|
|
|
pip install -U paquet
|
|
|
|
# -U = --upgrade
|
|
|
|
pip download paquet
|
|
|
|
```
|
|
|
|
|
2017-06-13 12:01:10 +02:00
|
|
|
## localisation du programme
|
|
|
|
|
2017-06-01 11:21:03 +02:00
|
|
|
```text
|
|
|
|
/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
|
|
|
|
```
|
2017-06-13 12:01:10 +02:00
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
récup thème du paquet:
|
|
|
|
```shell
|
|
|
|
cp -r /usr/local/lib/python2.7/dist-packages/mkdocs/themes/mkdocs/ ../
|
|
|
|
```
|
|
|
|
|
2017-06-13 12:01:10 +02:00
|
|
|
## installation d'un thème
|
|
|
|
|
2017-06-01 11:21:03 +02:00
|
|
|
```shell
|
|
|
|
pip install mkdocs-material
|
|
|
|
#localisation: /usr/local/lib/python2.7/dist-packages/material
|
|
|
|
```
|
2017-06-13 12:01:10 +02:00
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
|
|
|
|
## création d'un nouveau site
|
2017-06-13 12:01:10 +02:00
|
|
|
|
2017-06-01 11:21:03 +02:00
|
|
|
```shell
|
|
|
|
mkdocs new kyopages
|
|
|
|
cd kyopages
|
|
|
|
```
|
2017-06-13 12:01:10 +02:00
|
|
|
|
|
|
|
* toutes la configuation et la déclaration des pages dans:
|
|
|
|
```text
|
|
|
|
mkdocs.yml
|
2017-06-01 11:21:03 +02:00
|
|
|
```
|
2017-06-13 12:01:10 +02:00
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
|
2017-06-13 12:01:10 +02:00
|
|
|
## organisation pages
|
|
|
|
|
2017-06-01 11:21:03 +02:00
|
|
|
```text
|
|
|
|
mkdocs.yml
|
|
|
|
docs/
|
|
|
|
autreDirectory/
|
|
|
|
autre.md
|
|
|
|
index.md
|
|
|
|
...
|
2017-06-13 12:01:10 +02:00
|
|
|
sites/
|
|
|
|
# pages html générées
|
2017-06-01 11:21:03 +02:00
|
|
|
```
|
2017-06-13 12:01:10 +02:00
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
|
2017-06-13 16:12:28 +02:00
|
|
|
## développement, build auto
|
2017-06-13 12:01:10 +02:00
|
|
|
|
|
|
|
* démarrer un serveur local, build et rafraîchissement automatique du navigateur
|
2017-06-01 11:21:03 +02:00
|
|
|
```shell
|
|
|
|
mkdocs serve
|
|
|
|
```
|
2017-06-13 12:01:10 +02:00
|
|
|
on peut utiliser
|
|
|
|
```shell
|
|
|
|
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
|
2017-06-01 11:21:03 +02:00
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
|
2017-06-13 16:12:28 +02:00
|
|
|
## build manuel
|
2017-06-13 12:01:10 +02:00
|
|
|
|
|
|
|
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:
|
|
|
|
```shell
|
|
|
|
mkdocs build --dirty
|
|
|
|
```
|
|
|
|
incidences à voir
|
2017-06-13 16:12:28 +02:00
|
|
|
|
2018-03-21 03:44:25 +01:00
|
|
|
|
2017-06-13 16:12:28 +02:00
|
|
|
## thème mkdocs
|
2018-03-21 03:44:25 +01:00
|
|
|
* [allègement hightlight.js](https://highlightjs.org/download/) avec seulement les langages:
|
2017-06-13 16:12:28 +02:00
|
|
|
`bash css diff html/xml http ini json javascript makefile markdown python shell(-session)`
|
|
|
|
`text` désactive la coloration syntaxique
|
|
|
|
* [manuel](https://highlightjs.org/usage/)
|