483 lines
12 KiB
Markdown
483 lines
12 KiB
Markdown
# Welcome to MkDocs
|
||
|
||
For full documentation visit [mkdocs.org](http://mkdocs.org).
|
||
|
||
|
||
|
||
### Installation:
|
||
|
||
```bash
|
||
$ 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
$ cd /Users/bruno/project
|
||
|
||
$ ./build_and_upload.sh
|
||
```
|
||
|
||
|
||
|
||
/build_and_upload.sh
|
||
|
||
```bash
|
||
# !/bin/bash
|
||
|
||
cd /Users/bruno/project
|
||
mkdocs build
|
||
scp -P42666 -r ./central_docs bruno@192.168.xxx.xxx:/volume1/web
|
||
```
|
||
|
||
|
||
|
||
### Admonitions:
|
||
|
||
#### Note:
|
||
|
||
**Note simple:**
|
||
|
||
```markdown
|
||
!!! 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 avec titre:**
|
||
|
||
```markdown
|
||
!!! note "Phasellus posuere in sem ut cursus"
|
||
```
|
||
|
||
!!! note "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:**
|
||
|
||
```markdown
|
||
!!! note ""
|
||
```
|
||
|
||
!!! 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:**
|
||
|
||
```markdown
|
||
??? 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:**
|
||
|
||
```markdown
|
||
???+ 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`
|
||
|
||
```markdown
|
||
!!! abstract "Résumé"
|
||
```
|
||
|
||
!!! abstract "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 "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`
|
||
|
||
```markdown
|
||
!!! tip "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`
|
||
|
||
```markdown
|
||
!!! success "Succès"
|
||
```
|
||
|
||
!!! success "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`
|
||
|
||
```markdown
|
||
!!! help "Aide"
|
||
```
|
||
|
||
!!! help "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`
|
||
|
||
```markdown
|
||
!!! warning "Attention"
|
||
```
|
||
|
||
!!! warning "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`
|
||
|
||
```markdown
|
||
!!! fail "Echec"
|
||
```
|
||
|
||
!!! fail "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`
|
||
|
||
```markdown
|
||
!!! danger "Erreur"
|
||
```
|
||
|
||
!!! danger "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`
|
||
|
||
```markdown
|
||
!!! 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`
|
||
|
||
```markdown
|
||
!!! example "Exemple"
|
||
```
|
||
|
||
!!! example "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`
|
||
|
||
```markdown
|
||
!!! quote "Citation"
|
||
```
|
||
|
||
!!! quote "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/](http://bwmarrin.github.io/MkDocsPlus/)
|
||
|
||
[:fa-link: http://fontawesome.io/icons/](http://fontawesome.io/icons/)
|
||
|
||
|
||
|
||
```html
|
||
:fa-link:
|
||
```
|
||
|
||
:fa-link:
|
||
|
||
|
||
```html
|
||
<i class="fa fa-link fa-lg"></i>
|
||
```
|
||
|
||
<i class="fa fa-link fa-lg"></i>
|
||
|
||
|
||
|
||
```html
|
||
<i class="fa fa-link fa-2x"></i>
|
||
```
|
||
|
||
<i class="fa fa-link fa-2x"></i>
|
||
|
||
|
||
|
||
```html
|
||
<i class="fa fa-link fa-5x"></i>
|
||
```
|
||
|
||
<i class="fa fa-link fa-5x"></i>
|
||
|
||
|
||
|
||
### Themes:
|
||
|
||
#### Installer un thème:
|
||
|
||
```bash
|
||
$ pip install mkdocs-cinder
|
||
```
|
||
|
||
|
||
|
||
#### Mettre à jour un thème:
|
||
|
||
```bash
|
||
$ pip install --upgrade mkdocs-material
|
||
```
|
||
|
||
|
||
|
||
[:octicons-link: MkDocs-Themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
|
||
|
||
[:octicons-link: Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
|
||
|
||
[:octicons-link: MkDocs+](http://bwmarrin.github.io/MkDocsPlus/)
|
||
|
||
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
|
||
|
||
```bash
|
||
$ 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:
|
||
|
||
```bash linenums="1" hl_lines="1 19 30 44 45 47 51 67 69"
|
||
├── 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:](mkdocs-material.md)
|
||
|