From 2375e1c7f05de64252ea1a51731aacc9d00169bc Mon Sep 17 00:00:00 2001
From: TGITS <thegeekintheshell@gmail.com>
Date: Thu, 4 Jan 2024 19:07:56 +0100
Subject: [PATCH] feat(wip_for_article)

Work in progress as an example for the post on medium
---
 README.md     | 35 +++++++++++++++++++++++++++++++++++
 docs/index.md | 17 +++++++++++++++++
 mkdocs.yml    |  3 +++
 3 files changed, 55 insertions(+)
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

diff --git a/README.md b/README.md
index b6bad8e..6f15fe8 100644
--- a/README.md
+++ b/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`
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..000ea34
--- /dev/null
+++ b/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.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..3d40ce6
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,3 @@
+site_name: Fun with Mkdocs !
+theme:
+  name: material
\ No newline at end of file