Création d’un premier site

Pour créer votre premier site, créez un nouveau dossier et ouvrez une console dans ce répertoire.

Astuce

Si vous utilisez Visual Studio Code, vous pouvez ouvrir une console en tapant Ctrl+Shift+` ou en cliquant sur le menu Terminal et en choisissant New Terminal.

Si votre éditeur n’a pas de terminal intégré, nous vous recommandons d’utiliser Windows Terminal pour Windows, iTerm2 pour macOS, ou le terminal par défaut de votre distribution Linux.

Créez maintenant un nouveau projet Poetry.

Astuce

Poetry crée un environnement virtuel Python dans le dossier .venv du projet.

Cette configuration est définie dans le fichier poetry.toml. Quand elle n’est pas définie, Poetry crée un environnement virtuel dans un répertoire de votre système. A vous de voir si vous préférez cette option ou non.

Tapez la commande poetry init et répondez aux questions. N’ajoutez pas encore les dépendances. Par exemple :

This command will guide you through creating your pyproject.toml config.

Package name [mkdocs-edu-howto]:
Version [0.1.0]:
Description []:  Demo Web Site
Author [Jacques Supcik <jacques.supcik@hefr.ch>, n to skip]:
License []:  Apache-2
Compatible Python versions [>=3.10,<3.12]:

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Generated file
...
Do you confirm generation? (yes/no) [yes]

Attention

Lors de la rédaction de cette page, la dernière version de Python était la 3.11.4. Python 3.12 était en pre-release et Python 3.13 n’existait pas encore.

La plupart des paquets demandent au moins la version 3.7 de Python, certains demandent la version 3.8 et quelques-uns demandent la version 3.10. Afin de couvrir tous les cas, nous allons demander une version 3.10 ou 3.11. On peut éventuellement laisser la version 3.12, mais il faut exclure les versions supérieures à 3.12 car certains paquets sont prudents et ne peuvent pas s’installer si on autorise une version supérieure à 3.12.

Pour la configuration de la version de python (Compatible Python versions), assurez-vous donc de mettre >=3.10,<3.12 ou >=3.10,<3.13.

Il se peut que poetry vous propose quelque chose comme ^3.11. Dans ce cas, modifiez la proposition par >=3.10,<3.12 (ou >=3.10,<3.13).

Si vous avez déjà créé le fichier pyproject.toml, vous pouvez le modifier directement avec votre éditeur de texte préféré. Vous devriez avoir quelque chose comme :

[tool.poetry.dependencies]
python = ">=3.10,<3.12"
...

Pour utiliser une version précise de Python indépendante de celle de votre OS, vous pouvez utiliser pyenv. Une fois pyenv installé, installer la version recommandée et l’utiliser via les commandes suivantes:

# Installe la version configurée dans `.python-version`
pyenv install

# Force explicitement Poetry à utiliser la version mise en place par pyenv
poetry env use $(which python)
poetry install

Ajoutez maintenant les dépendances :

poetry add mkdocs mkdocs-material

Vous pouvez maintenant créer votre premier site mkdocs avec la commande suivante :

poetry run mkdocs new .

puis

poetry run mkdocs serve

Mkdocs écrira ces quelques lignes dans la console :

INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.03 seconds
INFO     -  [21:33:52] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO     -  [21:33:52] Serving on http://127.0.0.1:8000/
WARNING  -  [21:33:52] "GET /mkdocs-edu-howto/first-site/ HTTP/1.1" code 404
INFO     -  [21:33:57] Browser connected: http://127.0.0.1:8000/

et en ouvrant votre navigateur à l’adresse http://127.0.0.1:8000/, vous devriez voir le résultat suivant :

Félicitations! Vous venez de créer un site web avec mkdocs.