feat(wip_for_article)

Work in progress as an example for the post on medium

README.md

@@ -1,2 +1,37 @@
 # fun-with-mkdocs
+
 Example project that demonstrate the use of mkdocs and material for mkdocs
+
+## Using with Python
+
+If you already have Python installed on yoyr system or you prefer use mkdocs withuout using Docker, the recommended steps are the following :
+
+* Create a virtual environment with `venv` (it is bundled with Python) before installing **MkDocs** :
+  * In a shell, at the root of the directory in which you want to install mkdocs, type : `python -m venv venv --prompt="mkdocs"`
+  * A `venv` directory should be created : add this directory to the `.gitignore`
+* Activate the virtual environnement : `venv\Scripts\activate`
+* Install **MkDocs (with Material)** with `pip`
+  * `pip install mkdocs-material`
+  * Now **MkDocs** is installed in your virtual environment
+* When you have finished your work session in the shell, remember to deactivate your virtual environment : `venv\Scripts\deactivate`
+
+When the installation is done, the following commands are available :
+
+* Initialization : `mkdocs new <documentation-project-name>`
+  * Only to initialize the MkDocs project, you should execute this command only once.
+* Previsualization : `mkdocs serve` or `mkdocs serve --dirtyreload` if you only want to update the current page (incomplete but faster build of the site).
+* Building of the site : `mkdocs build`
+  * The HTML files of the site are generated in the directory `site/fun-with-mkdocs`
+  * They can be open directly with your browser.
+
+Remember to activate your virtual environment before running the **MkDocs** commands : `venv\Scripts\activate`
+And remember to activate it when you have finished your work session (if you forgot it is the end of the world, particularly if you close your shell) : `venv\Scripts\deactivate`.
+
+## Using with Docker
+
+[MkDocs](https://www.mkdocs.org/) can be used without installation with [Docker](https://www.docker.com/).
+
+* To initialize the site, in the directory in which you want to create if : `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .`
+* Previzualisation on `localhost:8000` : `docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material`
+* Building of the site : `docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build`
+  * The HTML files of the site are generated in the directory `site/fun-with-mkdocs`

docs/index.md

@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

mkdocs.yml

@@ -0,0 +1,3 @@
+site_name: Fun with Mkdocs !
+theme:
+  name: material