Aller au contenu

Welcome to MkDocs

For full documentation visit mkdocs.org.

Installation:

$ pip install mkdocs

Commandes:

  • mkdocs new [dir-name] - Create a new project.
  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs help - Print this help message.
  • gh-deploy - Deploy your documentation to GitHub Pages.

Project layout:

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

Créer un nouveau projet de docs:

bruno@SilverBook:~$ mkdocs new project

INFO    -  Creating project directory: project

INFO    -  Writing config file: project/mkdocs.yml

INFO    -  Writing initial docs: project/docs/index.md

bruno@SilverBook:~$ cd project

total 8
drwxr-xr-x   4 bruno  staff   128 16 déc 20:48 .
drwxr-xr-x@ 70 bruno  staff  2240 16 déc 20:48 ..
drwxr-xr-x   3 bruno  staff    96 16 déc 20:48 docs
-rw-r--r--   1 bruno  staff    19 16 déc 20:48 mkdocs.yml

Servir le projet:

bruno@SilverBook:~/project$ mkdocs serve

INFO    -  Building documentation...

INFO    -  Cleaning site directory

[I 171216 20:54:40 server:283] Serving on http://127.0.0.1:8000
[I 171216 20:54:40 handlers:60] Start watching changes
[I 171216 20:54:40 handlers:62] Start detecting changes
[I 171216 20:55:00 handlers:133] Browser Connected: http://127.0.0.1:8000/
[I 171216 20:55:41 handlers:133] Browser Connected: http://127.0.0.1:8000/

Copier les docs sur le serveur:

$ cd /Users/bruno/project

$ ./build_and_upload.sh

/build_and_upload.sh

# !/bin/bash

cd /Users/bruno/project
mkdocs build
scp -P42666 -r ./central_docs bruno@192.168.xxx.xxx:/volume1/web

Admonitions:

Note:

Note simple:

!!! note ""
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
    Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo 
  purus auctor massa, nec semper lorem quam in massa.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Note avec titre:

!!! note "Phasellus posuere in sem ut cursus"

Phasellus posuere in sem ut cursus

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Note sans titre:

!!! note ""

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Note avec contenu:

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. python def bubble_sort(items): for i in range(len(items)): for j in range(len(items) - 1 - i): if items[j] > items[j + 1]: items[j], items[j + 1] = items[j + 1], items[j] Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.

Note collapsible ouverte:

??? note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Note collapsible fermée:

???+ note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.
Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Type:

abstract, summary, tldr

!!! abstract "Résumé"

Résumé

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

info, todo

!!! info "Info"

Info

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

tip, hint, important

!!! tip "Tip"

Tip

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

success, check, done

!!! success "Succès"

Succès

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

question, help, faq

!!! help "Aide"

Aide

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

warning, caution, attention

!!! warning "Attention"

Attention

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

failure, fail, missing

!!! fail "Echec"

Echec

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

danger, error

!!! danger "Erreur"

Erreur

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

bug

!!! bug "Bug"

Bug

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

example

!!! example "Exemple"

Exemple

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

quote, cite

!!! quote "Citation"

Citation

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

https://squidfunk.github.io/mkdocs-material/reference/abbreviations/

Font Awesome icons:

:fa-link: http://bwmarrin.github.io/MkDocsPlus/

:fa-link: http://fontawesome.io/icons/

:fa-link:

:fa-link:

<i class="fa fa-link fa-lg"></i>


<i class="fa fa-link fa-2x"></i>


<i class="fa fa-link fa-5x"></i>

Themes:

Installer un thème:

$ pip install mkdocs-cinder

Mettre à jour un thème:

$ pip install --upgrade mkdocs-material

:octicons-link: MkDocs-Themes

:octicons-link: Material for MkDocs

:octicons-link: MkDocs+

https://github.com/otsuarez/mkdocs_auth

Plugins:

  • mkdocs-material-extensions
  • mkdocs-git-revision-date-localized-plugin
  • mkdocs-minify-plugin
  • fontawesome_markdown
  • mkdocs-pdf-export-plugin
  • markdown
  • pymdown-extensions
$ pip install --upgrade mkdocs-material-extensions mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin fontawesome_markdown mkdocs-pdf-export-plugin markdown pymdown-extensions

Structures:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
├── central_docs (*)
│   ├── Distributions
│   │   ├── Mint
├── docs
│   ├── Distributions
│   │   ├── Mint
│   │       ├── Mint.md
│   │       ├── applications.md
│   │       ├── backup.md
│   │       ├── grub.md
│   │       ├── index.md
│   │       ├── samba.md
│   │       ├── systemctl.md
│   │       ├── vsftpd.md
│   │       └── webserver.md
│   ├── NBResources
│   │   └── Misc
│   │       └── RecentItems.txt
│   ├── assets (*)
│   │   └── icons
│   │       ├── icon-128x128.png
│   │       ├── icon-144x144.png
│   │       ├── icon-152x152.png
│   │       ├── icon-192x192.png
│   │       ├── icon-384x384.png
│   │       ├── icon-512x512.png
│   │       ├── icon-72x72.png
│   │       └── icon-96x96.png
│   ├── index.md
│   ├── javascripts (*)
│   │   └── extra.js
│   ├── macos
│   │   ├── Divers
│   │   │   ├── Divers.md
│   │   │   ├── Hackintosh.md
│   │   │   └── weasyprint.md
│   │   └── webserver
│   │       ├── apache_M1.md
│   │       ├── index.md
│   │       ├── install_mysql.md
│   │       ├── mysql.md
│   │       ├── php.md
│   │       └── php80.md
│   ├── manifest.json (*)
│   ├── overrides (*)
│   │   └── partials
│   ├── stylesheets (*)
│   │   ├── extra.css
│   │   ├── fontawesome-all.css
│   │   └── second_extra.css
│   └── webfonts (*)
│       ├── fa-brands-400.eot
│       ├── fa-brands-400.svg
│       ├── fa-brands-400.ttf
│       ├── fa-brands-400.woff
│       ├── fa-brands-400.woff2
│       ├── fa-regular-400.eot
│       ├── fa-regular-400.svg
│       ├── fa-regular-400.ttf
│       ├── fa-regular-400.woff
│       ├── fa-regular-400.woff2
│       ├── fa-solid-900.eot
│       ├── fa-solid-900.svg
│       ├── fa-solid-900.ttf
│       ├── fa-solid-900.woff
│       └── fa-solid-900.woff2
├── includes (*)
│   └── abbreviations.md
├── mkdocs.yml (*)
└── src
    └── mkdocs-pdf-export-plugin

  • assets/

    • icons
      • icon-128x128.png
      • icon-96x96.png

  • javascripts/

    • extra.js

  • Manifest.json

  • stylesheets/

    • extra.css
    • fontawesome-all.css
    • second_extra.css

  • webfonts/

    • fa-brands-400.eot
    • fa-regular-400.eot
    • fa-solid-900.eot

  • Includes/

    • abbreviations.md

  • mkdocs.yml

  • overrides/

    • partials/

  • central_docs/ : le site crée par mkdocs build

suite...:material-arrow-right-top:

Dernière mise à jour: March 4, 2022