diff --git a/docs/_data/extra.yaml b/docs/_data/extra.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..7cb8bd56bff0e58c81348682cc1b4960e5439491
--- /dev/null
+++ b/docs/_data/extra.yaml
@@ -0,0 +1,33 @@
+# Minimal set of variable for subrepo example in usage/configure.md
+example:
+ my_repo_slug:
+ name: My Main Repo Name
+ desc: Description of my [Main Repo](#)
+ subrepo:
+ roles:
+ nav_entry: "Roles"
+ internal:
+ - name: role_name_1
+ - name: role_name_2
+ external:
+ - name: my_first_role
+ programs:
+ nav_entry: "My Programs"
+ external:
+ - name: my_first_repo
+ - name: my_second_repo
+role_name_1:
+ name: Role Name 1
+ desc: Description of the Role Name 1
+role_name_2:
+ name: Role Name 2
+ desc: Description of the Role Name 2
+my_first_role:
+ name: My First Role
+ desc: Description of My First Role
+my_first_repo:
+ name: My First Repo
+ desc: Description of My First Repo
+my_second_repo:
+ name: My Second Repo
+ desc: Description of My Second Repo
diff --git a/docs/assets/img/fork_dest_namespace.png b/docs/assets/img/fork_dest_namespace.png
new file mode 100644
index 0000000000000000000000000000000000000000..0e6965b8ff3b0c74d35c99d88b718b596488e55d
Binary files /dev/null and b/docs/assets/img/fork_dest_namespace.png differ
diff --git a/docs/assets/img/fork_finish.png b/docs/assets/img/fork_finish.png
new file mode 100644
index 0000000000000000000000000000000000000000..c6e1e4736a1e320a953ab5920d200c697e2673e6
Binary files /dev/null and b/docs/assets/img/fork_finish.png differ
diff --git a/docs/assets/img/fork_main_repo.png b/docs/assets/img/fork_main_repo.png
new file mode 100644
index 0000000000000000000000000000000000000000..13b229dd38a20a8587f08a387b6d25b37cadfb10
Binary files /dev/null and b/docs/assets/img/fork_main_repo.png differ
diff --git a/docs/index.md b/docs/index.md
index c8ce9c6c093e0aaf30a3578b29dc45bd6fdc0088..f07cf86ad9a31705d9c25ebc75d72f86bd9fe4a9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -42,3 +42,79 @@ platforms.
--------------------------------------------------------------------------------
<!-- END MKDOCS TEMPLATE -->
+
+## Introduction
+
+Since some times now, I use [mkdocs][mkdocs] to write documentation of my
+projects.
+
+While [mkdocs][mkdocs] is a really usefull software allowing me to write clean
+and clear documentation in markdown and render it as static website, I was tired
+to always copy/paste same configuration accross all my projects documentations.
+
+Even worst, when I decide to change some minor things (such as color palettes),
+I had to go to each projects and for each project I had to replace manually
+every time the same two configuration lines.
+
+This project aims is to ease the management of documentation configuration by
+allowing to create a template and easily setup or upgrade it to a newer version.
+
+## Usage
+
+Below is a really basic usage example of this repo, more complete documentation
+is provided at section [Use Template][use_template] and if you want to create
+your own template from this repo, you can refer to the section [Setup Your Own
+Template][setup_your_own_template]
+
+Assuming you want to use this **really** basic template. In a repo in which you
+want to create a documentation, type the following commands:
+
+```bash
+# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
+# First download the setup script into a temporary folder
+wget {{ git_platform.url }}{{ curr_repo.repo_path_with_namespace }}/-/raw/master/setup.sh \
+ -O /tmp/setup_mkdocs.sh
+# Then read the content of the script with your favorite editor
+vim /tmp/setup_mkdocs.sh
+# If you are confident with what the script does, make it executable and run it
+chmod +x /tmp/setup_mkdocs.sh
+/tmp/setup_mkdocs.sh -r {{ git_platform.url }}{{ curr_repo.repo_path_with_namespace }}
+```
+
+Or if you already read the content of the script `setup.sh` at the root of this
+repo, previous commands can be done in online:
+
+```bash
+# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
+# You can get the content of the script setup.sh via curl and pipe it into bash
+curl -sfL {{ git_platform.url }}{{ curr_repo.repo_path_with_namespace }}/-/raw/master/setup.sh \
+ | bash -s -- -r {{ git_platform.url }}{{ curr_repo.repo_path_with_namespace }}
+```
+
+This will automatically create the folder `docs` with basic pages and the
+following files:
+
+- `mkdocs.yml`
+- `requirements.docs.in`
+- `requirements.docs.txt`
+
+What you will now have to do is :
+
+- Copy the provided template file `docs/_data/template/repo.tpl.yaml` into
+ `docs/_data/repo_name.yml` such as `repo_name` is the slug of your repo (for
+ instance slug of `mkdocs template` is `mkdocs_template` and slug of
+ `docs.domain.tld project` is `docs_domain_tld_project`).
+- Edit this new file `docs/_data/repo_name.yml`, especially, do not forget to
+ change the key `repo_name` in the file accordingly to your repo slug.
+
+You are ready now to render you documentation:
+
+```bash
+mkdocs serve
+```
+
+[use_template]: usage/
+[setup_your_own_template]: personal_template
+
+<!-- URL used in mulitple section -->
+[mkdocs]: https://mkdocs.org/
diff --git a/docs/personal_template/create.md b/docs/personal_template/create.md
new file mode 100644
index 0000000000000000000000000000000000000000..eb9ad644c65ab2b1079165fbdf881a62219bcbd2
--- /dev/null
+++ b/docs/personal_template/create.md
@@ -0,0 +1,465 @@
+{% set curr_repo=subs("mkdocs_template") %}
+# Create Custom Template
+
+## Fork the main repo
+
+!!! info
+
+ Only forking from [Mkdocs Template Repo][mkdocs_template_repo] on {{
+ git_platform.name }} will be described here. If you find a mirror of this
+ repo, you can still fork this mirror but documentation of such process will
+ not be presented here.
+
+First thing to do is to fork the [Mkdocs Template Repo][mkdocs_template_repo].
+To do so, click on the button ++"燎 Fork"++ as shown below:
+
+![!Fork Mkdocs Template][fork_mkdocs_template]
+
+Then, choose where you want to store your fork from your accessible namespace:
+
+![!Fork Mkdocs Template Destination][fork_mkdocs_template_dest]
+
+Wait for the fork to finish:
+
+![!Fork Mkdocs Template Finish][fork_mkdocs_template_finish]
+
+Finally, you can clone your forked.
+
+!!! note
+
+ In the rest of documentation we will assume you forked the main repo to
+ https://gitdomain.tld/namespace/mkdocs_template.git.
+
+```bash
+# Clone using https
+git clone https://gitdomain.tld/namespace/mkdocs_template.git.
+# Clone using ssh
+git clone git@gitdomain.tld:namespace/mkdocs_template.git.
+```
+
+[mkdocs_template_repo]: {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}
+[fork_mkdocs_template]: /assets/img/fork_main_repo.png
+[fork_mkdocs_template_dest]: /assets/img/fork_dest_namespace.png
+[fork_mkdocs_template_finish]: /assets/img/fork_finish.png
+
+## Add the content of your template
+
+Now, to setup your own template, you just have to write it in the empty folder
+but track `user_config` folder. If you happen to add a file with the same path
+from `template`, the your file will override the one in `template`.
+
+For instance, if you create a file `user_config/docs/index.md`, its content will
+override the content of the file `template/docs/index.md` when using template.
+
+Moreover, you can add a `post_setup.sh` script in `user_config` to handle
+customized command once `setup.sh` finish.
+
+Below are some examples such as a possible structure of `user_config` folder as
+well as some content exaple. Note that every files, hidden or not, within folder
+`user_config` are copied when installed, which can be usefull to provide
+configuration workflow files, such as `.editorconfig`, `.gitignore`, etc. files.
+
+=== "Folder `user_config`"
+
+ ```text
+ ├──  .editorconfig
+ ├──  .gitignore
+ ├──  .gitkeep
+ ├── ï’ .gitlab-ci.yml
+ ├──  .yamllint
+ ├──  docs
+ │ ├── ï’ .gitlab-ci.yml
+ │ ├──  _data
+ │ │ └── ï’ vars.yaml
+ │ ├──  about
+ │ │ ├──  code_of_conduct.md
+ │ │ ├──  contributing.md
+ │ │ ├──  data_privacy.md
+ │ │ ├──  index.md
+ │ │ ├──  license.md
+ │ │ └──  release_notes.md
+ │ ├──  index.md
+ │ └──  theme
+ │ ├──  css
+ │ │ └── î‰ theme.css
+ │ └──  js
+ │ └── îŽ extra.js
+ ├──  LICENSE.BEERWARE
+ ├──  LICENSE.MIT
+ ├── ï’ mkdocs.local.yml
+ ├──  post_setup.sh
+ ├──  pyproject.toml
+ ├──  README.md
+ ├──  requirements.dev.in
+ ├──  requirements.dev.txt
+ ├──  requirements.docs.in
+ └──  requirements.docs.txt
+ ```
+
+=== "`README.md`"
+
+ Below is the templated content of a README.md which is automatically updated
+ with the script `post_setup.sh`
+
+ ````markdown
+ <div align="center" style="text-align: center;">
+
+ <!-- Project Title -->
+ <a href="<TPL:REPO_URL>">
+ <img src="docs/assets/img/meta/<TPL:REPO_NAME>_logo.png" width="100px">
+ <h1><TPL:REPO_NAME_FIRST_UPPERCASE></h1>
+ </a>
+
+ <!-- Project Badges -->
+ [![License][license_badge]][license]
+ [![Build Status][build_status_badge]][build_status]
+
+ --------------------------------------------------------------------------------
+
+ TODO: Short description as written in `docs/_data/repo.yaml`
+
+ --------------------------------------------------------------------------------
+
+ <b>
+ IMPORTANT !
+
+ Main repo is on [ Framagit][repo_url].<br>
+ On other online git platforms, they are just mirror of the main repo.<br>
+ Any issues, pull/merge requests, etc., might not be considered on those other
+ platforms.
+ </b>
+ </div>
+
+ --------------------------------------------------------------------------------
+
+ [repo_url]: <TPL:REPO_URL>
+ [license_badge]: https://img.shields.io/badge/License-MIT%2FBeer%20Ware-blue?style=flat-square&logo=open-source-initiative
+ [license]: LICENSE
+ [build_status_badge]: <TPL:REPO_URL>/badges/master/pipeline.svg?style=flat-square&logo=appveyor
+ [build_status]: <TPL:REPO_URL>/commits/master
+
+ ## Table of Content
+
+ * [Project Documentation](#project-documentation)
+
+ <!-- BEGIN MKDOCS TEMPLATE -->
+ <!--
+ WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !
+ Modified content will be overwritten when updating
+ -->
+
+ ## Project Documentation
+
+ The complete documentation of the project can be accessed via its [Online
+ Documentation][online_doc].
+
+ If, for any reason, the link to the [Online Documentation][online_doc] is
+ broken, you can generate its documention locally on your computer (since the
+ documentation is jointly stored within the repository).
+
+ To do so, you will need the following requirements:
+
+ - Python >= 3.8
+ - Pip3 with Python >= 3.8
+
+ First setup a temporary python virtual environment and activate it:
+
+ ```bash
+ # Create the temporary virtual environment
+ python3 -m venv .temporary_venv
+ # Activate it
+ source .temporary_venv/bin/activate
+ ```
+
+ Now, install required dependencies to render the documentation using
+ [mkdocs][mkdocs] in the python virtual environment:
+
+ ```bash
+ pip3 install -r requirements.docs.txt
+ ```
+
+ Now you can easily render the documentation using [mkdocs][mkdocs] through the
+ usage of the following command (some logs will be outputed to stdout):
+
+ ```bash
+ # Assuming you are at the root of the repo
+ # If there is a `mkdocs.local.yml`
+ mkdocs serve -f mkdocs.local.yml
+ # If there is no `mkdocs.local.yml`, only `mkdocs.yml`
+ mkdocs serve
+ ```
+
+ You can now browse the full documentation by visiting
+ [http://localhost:8000][localhost].
+
+ [localhost]: https://localhost:8000
+ [mkdocs]: https://www.mkdocs.org/
+
+ <!-- END MKDOCS TEMPLATE -->
+
+ [online_doc]: <TPL:REPO_ONLINE_DOC_URL>/index.html
+ ```
+ ````
+
+=== "`docs/theme/js/extra.js`"
+
+ ```javascript
+ /*
+ * LIGHTGALLERY
+ * ----------------------------------------------------------------------------
+ * Lightgallery extra javascript
+ * From: https://github.com/g-provost/lightgallery-markdown
+ */
+
+ /*
+ * Loading lightgallery
+ */
+ var elements = document.getElementsByClassName("lightgallery");
+ for(var i=0; i<elements.length; i++) {
+ lightGallery(elements[i]);
+ }
+
+ /*
+ * Loading video plugins for lightgallery
+ */
+ lightGallery(document.getElementById('html5-videos'));
+
+ /*
+ * Loading parameter to auto-generate thumbnails for vimeo/youtube video
+ */
+ lightGallery(document.getElementById('video-thumbnails'), {
+ loadYoutubeThumbnail: true,
+ youtubeThumbSize: 'default',
+ loadVimeoThumbnail: true,
+ vimeoThumbSize: 'thumbnail_medium',
+ });
+
+ /*
+ * Table Sort
+ * ----------------------------------------------------------------------------
+ * Code snippet to allow sorting table
+ * From: https://squidfunk.github.io/mkdocs-material/reference/data-tables/#sortable-tables
+ */
+ document$.subscribe(function() {
+ var tables = document.querySelectorAll("article table")
+ tables.forEach(function(table) {
+ new Tablesort(table)
+ })
+ })
+
+
+ /*
+ * Mermaid Configuration to support dark/light switching
+ * ----------------------------------------------------------------------------
+ * Table Sort
+ * Optional config
+ * If your document is not specifying `data-md-color-scheme` for color schemes
+ * you just need to specify `default`.
+ */
+ window.mermaidConfig = {
+ "rdeville-light": {
+ startOnLoad: false,
+ theme: "default",
+ flowchart: {
+ htmlLabels: false
+ },
+ er: {
+ useMaxWidth: false
+ },
+ sequence: {
+ useMaxWidth: false,
+ /*
+ * Mermaid handles Firefox a little different. For some reason, it
+ * doesn't attach font sizes to the labels in Firefox. If we specify the
+ * documented defaults, font sizes are written to the labels in Firefox.
+ */
+ noteFontWeight: "14px",
+ actorFontSize: "14px",
+ messageFontSize: "16px"
+ }
+ },
+ "rdeville-dark": {
+ startOnLoad: false,
+ theme: "dark",
+ flowchart: {
+ htmlLabels: false
+ },
+ er: {
+ useMaxWidth: false
+ },
+ sequence: {
+ useMaxWidth: false,
+ noteFontWeight: "14px",
+ actorFontSize: "14px",
+ messageFontSize: "16px"
+ }
+ }
+ }
+ ```
+
+=== "`docs/about/contributing.md`"
+
+ ```markdown
+ {% raw %}
+ {% set curr_repo=subs("TODO") %}
+
+ <!-- BEGIN MKDOCS TEMPLATE -->
+ <!--
+ WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !
+ Modified content will be overwritten when updating
+ -->
+
+ # Contributing
+
+ This project welcomes contributions from developers and users in the open source
+ community. Contributions can be made in a number of ways, a few examples are :
+
+ * Code patch via pull requests
+ * Documentation improvements
+ * Bug reports and patch reviews
+ * Proposition of new features
+ * etc.
+
+ ## Reporting an Issue
+
+ Please include as much details as you can when reporting an issue in the [issue
+ trackers][issue_tracker]. If the problem is visual (for instance, wrong
+ documentation rendering) please add a screenshot.
+
+ [issue_tracker]: {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/issues
+
+ ## Submitting Pull Requests
+
+ Once you are happy with your changes or you are ready for some feedback, push it
+ to your fork and send a pull request. For a change to be accepted it will most
+ likely need to have tests and documentation if it is a new feature.
+
+ For more information, you can refers to the main [developers
+ guides][developers_guides] which is the common resources I use for all
+ my projects. There you will find:
+
+ * [Syntax Guide][syntax_guide], which describe syntax guidelines per language
+ to follow if you want to contribute.
+ * [Contributing workflow][contributing_workflow], which provide an example
+ of the workflow I used for the development.
+
+ [developers_guides]: {{ site_base_url }}/dev_guides/index.html
+ [syntax_guide]: {{ site_base_url }}/dev_guides/style_guides/index.html
+ [contributing_workflow]: {{ site_base_url }}/dev_guides/contributing_workflow.html
+
+ ## Community
+
+ Finally, every member of the community should follow this [Code of
+ conduct][code_of_conduct].
+
+ [code_of_conduct]: code_of_conduct.md
+
+ <!-- END MKDOCS TEMPLATE -->
+ {% endraw %}
+ ```
+
+
+## Preview your template
+
+When working on your custom template you might want to see a preview of your
+template. To do so, simply call the script `preview.sh`
+
+```bash
+# Assuming you are at the root of the mkdocs template repo
+./preview.sh
+```
+
+!!! note
+
+ You might need to do so more command, such as copying repo file do
+ `preview/docs/_data/mkdocs_template.yaml` or more. This will be prompted as
+ error or warning when rendering preview.
+
+This will compute the final list of files that will be installed, i.e. the union
+of content of `template` and `user_config` folder, such that content of
+`user_config` override content of `template`. Then create a symlink to each
+final file in `preview` folder. Finally, render the documentation to
+[http://localhost:8000][localhost]
+
+[localhost]: http://localhost:8000
+
+## Keep track with the main repo
+
+If you want to update your fork to have the last version of the main repo, you
+will first need to add a remote pointing to the main repo on
+[{{ git_platform.name }}][repo_url].
+
+First, list the current remote to ensure that remote `upstream` does not exists
+yet:
+
+```bash
+git remote -v
+> origin <URL_TO_YOUR_ORIGIN_REMOTE> (fetch)
+> origin <URL_TO_YOUR_ORIGIN_REMOTE> (push)
+```
+
+If there is not upstream, add the `upstream` remote:
+
+```bash
+git remote add upstream {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git
+```
+
+Ensure that the remote upstream is well sets:
+
+```bash
+git remote -v
+> origin <URL_TO_YOUR_ORIGIN_REMOTE> (fetch)
+> origin <URL_TO_YOUR_ORIGIN_REMOTE> (push)
+> upstream {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git (fetch)
+> upstream {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git (push)
+```
+
+Once done, fetch branches from this `upstream` remote, commit to `master` of
+the main repo will be stored in local branch `upstream/master`:
+
+```text
+git fetch upstream
+> remote: Counting objects: 75, done.
+> remote: Compressing objects: 100% (53/53), done.
+> remote: Total 62 (delta 27), reused 44 (delta 9)
+> Unpacking objects: 100% (62/62), done.
+> From {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git
+> * [new branch] master -> upstream/master*
+```
+
+Check out your fork's local `master` branch.
+
+```text
+git checkout master
+> Switched to branch 'master'
+```
+
+Merge the changes from `upstream/master` into your local `master` branch. This
+brings your fork's `master` branch into sync with the `upstream` repository,
+without losing your local changes.
+
+```text
+git merge upstream/master
+> Updating a422352..5fdff0f
+> Fast-forward
+> README | 9 -------
+> index.md | 7 ++++++
+> 2 files changed, 7 insertions(+), 9 deletions(-)
+> delete mode 100644 README
+> create mode 100644 index.md
+```
+
+If your local branch didn't have any unique commits, Git will instead perform a
+"fast-forward":
+
+```text
+git merge upstream/master
+> Updating 34e91da..16c56ad
+> Fast-forward
+> index.md | 5 +++--
+> 1 file changed, 3 insertions(+), 2 deletions(-)
+```
+
+Here you are up-to-date with the main repo :wink:.
+
+[repo_url]: {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}
diff --git a/docs/personal_template/example.md b/docs/personal_template/example.md
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/docs/personal_template/index.md b/docs/personal_template/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..40b4591ba8b273a673eefa198def969071e89239
--- /dev/null
+++ b/docs/personal_template/index.md
@@ -0,0 +1,24 @@
+# Setup Your Own Template
+
+As you may have seen, the usage of this repo install a **really** basic
+template, with little to no configuration, neither extra content such as extra
+JS nor CSS.
+
+But, you may want to use extra plugins such as [mkdocs-mermaid2-plugin] or
+provide a basic README.md as well as licenses or a default file
+`docs/_data/vars.yml` for all your documentation.
+
+To do so, you will need to create your own template and use it. To learn how to
+do, see:
+
+- [Create your own template][create_custom_template]
+- [Use your own template][use_custom_template]
+
+Finally, you can see the [Example custom template][example_custom_template] to
+give you hint about what can be done.
+
+
+[mkdocs_mermaid2_plugin]: https://github.com/fralau/mkdocs-mermaid2-plugin
+[create_custom_template]: create.md
+[use_custom_template]: usage.md
+[example_custom_template]: example.md
diff --git a/docs/personal_template/usage.md b/docs/personal_template/usage.md
new file mode 100644
index 0000000000000000000000000000000000000000..5337cbf75302db3fe0c8080662352561f924eb9c
--- /dev/null
+++ b/docs/personal_template/usage.md
@@ -0,0 +1,90 @@
+{% set curr_repo=subs("mkdocs_template") %}
+# Use Your Custom Template
+
+!!! note
+
+ In the rest of documentation we will assume you forked the main repo to
+ https://gitdomain.tld/namespace/mkdocs_template.git.
+
+Now you have created your custom template you might want to use it. Well it is
+as simple as installing the mkdocs template from the main repo. This is done
+using the script the `setup.sh`. Below is a recall of the script usage.
+
+{% include "docs/usage/setup.sh.md" %}
+
+## Installing your own template
+
+Similarly to the installation of the main template, to install your custom
+template, you will need to download the `setup.sh` script. Note that you can
+download it either from your fork (not recommended) or from the main repo, which
+is the recommended way to ensure having the latest `setup.sh`.
+
+The main difference with the installation of your own template compared to the
+installation of the basic main template is the url of the repo to use.
+
+```bash
+# Assuming you are in the repo for which you want to write a documentation
+# First download the setup script into a temporary folder
+wget {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \
+ -O /tmp/setup_mkdocs.sh
+# Then read the content of the script with your favorite editor
+vim /tmp/setup_mkdocs.sh
+# If you are confident with what the script does, make it executable and run it
+chmod +x /tmp/setup_mkdocs.sh
+# Note the URL of the repo specified with option `-r`
+/tmp/setup_mkdocs.sh -r https://gitdomain.tld/namespace/mkdocs_template.git
+```
+
+Or if you already read the content of the script `setup.sh` at the root of this
+repo, previous commands can be done in online:
+
+```bash
+# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
+# You can get the content of the script setup.sh via curl and pipe it into bash
+curl -sfL \
+ {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \
+ | bash -s -- \
+ -r https://gitdomain.tld/namespace/mkdocs_template.git
+```
+
+This will automatically compute the union of the content of the folder
+`templates` and the folder `user_config` and copy them in the folder where you
+are located.
+
+## Upgrade from your template
+
+Later, you may change some configuration in your template, such as adding or
+removing files, updating CSS, etc. Once this modification done, you will need to
+upgrade your already installed documentation from your new template.
+
+This is done by using the option `-u` of the script `setup.sh`. Using this
+option, the script will compare last version with old version of each files, if
+they have changed, backup the old version, to avoid losing content in case of error
+and then upgrade the files to the latest version.
+
+```bash
+# Assuming you are in the repo for which you want to write a documentation
+# First download the setup script into a temporary folder
+wget {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \
+ -O /tmp/setup_mkdocs.sh
+# Then read the content of the script with your favorite editor
+vim /tmp/setup_mkdocs.sh
+# If you are confident with what the script does, make it executable and run it
+chmod +x /tmp/setup_mkdocs.sh
+# Note the URL of the repo specified with option `-r`
+# NOTE THE USAGE OF THE `-u` OPTION
+/tmp/setup_mkdocs.sh -u -r https://gitdomain.tld/namespace/mkdocs_template.git
+```
+
+Or if you already read the content of the script `setup.sh` at the root of this
+repo, previous commands can be done in online:
+
+```bash
+# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
+# You can get the content of the script setup.sh via curl and pipe it into bash
+# NOTE THE USAGE OF THE `-u` OPTION
+curl -sfL \
+ {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \
+ | bash -s -- \
+ -u -r https://gitdomain.tld/namespace/mkdocs_template.git
+```
diff --git a/docs/usage/configure.md b/docs/usage/configure.md
new file mode 100644
index 0000000000000000000000000000000000000000..81d79e973bc68efe54070ab819af2036d49d669d
--- /dev/null
+++ b/docs/usage/configure.md
@@ -0,0 +1,358 @@
+# Configuration of the documentation
+
+Once you have install files using the script `setup.sh`, and before starting to
+render your documentation you will need some configuration to do:
+
+## Base mkdocs configuration
+
+Normally, most configuration of `mkdocs` is normally done in `mkdocs.yml` file,
+but to be able to use a templated `mkdocs.yml`, most of the configuration is
+handled differently.
+
+Now, it is the file `templates/docs/_data/plugins.py` which will handle the
+configuration. This file is automatically called with the
+[`mkdocs-macros-plugins`][mkdocs_macros_plugins]. So, if you want to overload
+mkdocs configuration value, this is done through the file
+`docs/_data/vars.yaml`. An example of such content is provided in
+`docs/_data/template/vars.tpl.yaml`.
+
+```bash
+# Assuming you are at the root of the folder where you installed the documentation
+cp docs/_data/template/vars.tpl.yaml docs/_data/vars.yaml
+# Now edit the content of the copied file with your favorite editor
+vim docs/_data/vars.yaml
+```
+
+The file is heavily commented allowing you to know what you are updating. Note
+that this part is optional, as most of the `mkdocs.yml` configuration is
+automatically set based on the repo information.
+
+[mkdocs_macros_plugins]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/
+
+## Repo variables
+
+!!! important "Ensure a git remote **origin** exists"
+
+ Before continuing, your documentation MUST be a git repository with a
+ remote **origin**. Indeed, the script `docs/_data/plugins.py` will get remote
+ information to have the `repo_slug` to know which file in `docs/_data/` hold the
+ repository information.
+
+So assuming that your remote **origin** is
+`https://mygit.tld/namespace/my_repo_slug.git` (this work also for ssh remote).
+You will need to copy the template provided in `docs/_data/template/repo.tpl.yaml`
+in `docs/_data/my_repo_slug` and then update its content:
+
+```bash
+# Assuming you are at the root of the repo holding the documentation
+cp docs/_data/template/repo.tpl.yaml docs/_data/my_repo_slug.yaml
+# Then edit the content of the file with your favorite editor
+vim docs/_data/my_repo_slug.yaml
+```
+
+You will need to update some key of the repo which will be used to automatically
+set `mkdocs.yml` configuration if not set in `docs/_data/vars.yaml`.
+
+For instance key `my_repo_slug['name']` will be used to dynamically set
+`site_name` key of the `mkdocs.yml`.
+
+Below is an example of such file:
+
+```yaml
+# Repo information
+# ===========================================================================
+# First key MUST be the "slug" of the repo based on the remote, i.e. if remote
+# is git@git.domain.tld:username/repo_name.git, then the key will be
+# `repo_name`.
+my_repo_slug:
+
+ # An explicit name for the repo that will be shown on the documentation
+ # page.
+ name: "The Best Repo Name in the World"
+
+ # (OPTIONATL) An extension of the explicit name with the namespace in which
+ # the repo is. For instance, using above remote, the entry will be
+ # `Username / Repo Name`.
+ # This entry is not used in the configuration of mkdocs.
+ #git_name_with_namespace: "Namespace / My Repo Name"
+
+ # The complete path of the repo from the git_platform["url"]. For instance,
+ # using, above remote, the entry will be `username/repo_name.git`
+ git_slug_with_namespace: "namespace/my_repo_slug.git"
+
+ # If the repo documentation is part of a bigger repo, then provide the
+ # path of the rendered documentation. If the documentation is not part of
+ # another repo, leave it empty.
+ #url_slug_with_namespace: "subpath_for_url_renderin/repo_slug"
+
+ # (OPTIONAL) Path, relative to `docs_dir` mkdocs config, to the logo of the
+ # repo. If not specified, path will automatically be set to
+ # `assets/img/meta/reop_name_logo.png`
+ #logo: "assets/img/meta/repo_template_logo.png"
+
+ # Description of the repo, will be used to setup the mkdocs description.
+ desc: >-
+ An explicit description to explain what my repo do. Can be a multiline
+ description with **markdown** support such as [link](https://url.domain.tld)
+
+ # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python
+ # source code, you will need to provide the path where your source files
+ # are relative to the root of the repo.
+ #src_path:
+ # - "src"
+
+ # List of informations about the main maintainers that will be automatically
+ # added to the license file in `docs/about/license.md`
+ maintainers:
+ - name: "Firstname Lastname"
+ mail: "mail@domain.tld"
+```
+
+## Subrepo Variables
+
+If you are working on a big project, with multiple subrepo you might have or
+want to split a documentation per project but render all of them from a master
+repository.
+
+An example could be an [ansible collection][ansible_collection] which can be
+composed of a master repository holding specific file and folders holdings
+things like roles, etc. In this case, you might want to keep roles in other git
+repository (like git submodules) and each of the role holds its own collection.
+But you want the final rendered documentation to include these repos.
+
+This can be done via a file describing such subrepo, i.e.
+`docs/_data/subrepo.yaml`. To do so, copy the template provided in
+`docs/_data/template/subrepo.tpl.yml`.
+
+```bash
+# Assuming you are at the root of the folder where you installed the documentation
+cp docs/_data/template/subrepo.tpl.yaml docs/_data/subrepo.yaml
+# Edit the content of the file with your favorite editor
+vim docs/_data/subrepo.yaml
+```
+
+Below is an example of file `docs/_data/subrepo.yml` for an ansible collection
+which roles are in folder `roles` at the root of the repo and such that roles
+documentation are include in the final documentation.
+
+```yaml
+subrepo:
+ # Folder where there are subrepo
+ roles:
+ # Nav entry in mkdocs.yml from where the roles documentations will be
+ # include. If the entry does not exists, it will be automatically added at
+ # the end of the `nav`
+ nav_entry: "Roles"
+ # Specify that the role will be include to the final documentation
+ internal:
+ # Provide a list of repo information
+ - name: role_name_1
+ nav_entry: My Role 1
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ git_url: https://gitdomain.tld/namespace/subnamespace/my_role_name_1
+ - name: role_name_2
+ nav_entry: My Role 2
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ git_url: https://gitdomain.tld/namespace/subnamespace/my_role_name_2
+```
+
+If you want to add link to external documentation, i.e. they will be included in
+the `nav` of the main repo but their own `nav` will not be include, this can
+also be done with the file `docs/_data/subrepo.yaml`.
+
+An example could be a main repo simply providing entry point to other repo, such
+as repo holding base content of [docs.romaindeville.fr][docs.romaindeville.fr].
+Below is an example of the content of such `subrepo.yaml` file:
+
+
+```yaml
+subrepo:
+ # Folder where there are subrepo
+ programs:
+ # Nav entry in mkdocs.yml from where the roles documentations will be
+ # include. If the entry does not exists, it will be automatically added at
+ # the end of the `nav`
+ nav_entry: "My Programs"
+ # Specify repos which documentation will be external
+ external:
+ # Provide a list of repo information
+ - name: my_first_repo
+ nav_entry: Example of First External repo
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ git_url: https://gitdomain.tld/namespace/subnamespace/my_first_repo.git
+ # Link to the external documentation, can be relative to the root of
+ #the documentation of a full https link.
+ online_url: /relative/to/root/documentation/
+ - name: my_second_repo
+ nav_entry: Example of Second External repo
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ git_url: https://gitdomain.tld/namespace/subnamespace/my_second_repo.git
+ # Link to the external documentation, can be relative to the root of
+ #the documentation of a full https link.
+ online_url: https://domain.tld/full/external/link/
+```
+
+Of course, both `internal` and `external` can be used as show below (click to
+reveal).
+
+??? Example
+
+ ```yaml
+ subrepo:
+ # Folder where there are subrepo
+ roles:
+ # Nav entry in mkdocs.yml from where the roles documentations will be
+ # include. If the entry does not exists, it will be automatically added at
+ # the end of the `nav`
+ nav_entry: "Roles"
+ # Specify that the role will be include to the final documentation
+ internal:
+ # Provide a list of repo information
+ - name: role_name_1
+ nav_entry: My Role 1
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ git_url: https://gitdomain.tld/namespace/subnamespace/my_role_name_1
+ - name: role_name_2
+ nav_entry: My Role 2
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ # Specify repos which documentation will be external
+ external:
+ # Provide a list of repo information
+ - name: my_first_role
+ nav_entry: Example of First External Role
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ git_url: https://gitdomain.tld/namespace/subnamespace/my_first_role.git
+ # Link to the external documentation, can be relative to the root of
+ #the documentation of a full https link.
+ online_url: /relative/to/root/documentation/
+ programs:
+ nav_entry: "My Programs"
+ # Specify repos which documentation will be external
+ external:
+ # Provide a list of repo information
+ - name: my_first_repo
+ nav_entry: Example of First External repo
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ git_url: https://gitdomain.tld/namespace/subnamespace/my_first_repo.git
+ # Link to the external documentation, can be relative to the root of
+ #the documentation of a full https link.
+ online_url: /relative/to/root/documentation/
+ - name: my_second_repo
+ nav_entry: Example of Second External repo
+ # You can provided both https or ssh url, but https is prefered for CI
+ # to better work
+ git_url: https://gitdomain.tld/namespace/subnamespace/my_second_repo.git
+ # Link to the external documentation, can be relative to the root of
+ #the documentation of a full https link.
+ online_url: https://domain.tld/full/external/link/
+ ```
+
+Thus, when rendering the documentation, the script `docs/_data/plugins.py` will
+check if folders `roles/{role_name_1,role_name_2}`, if they exists and are git
+repo, script will pull them to get the last version. If they do not exists, the
+will be cloned.
+
+Finally, the script `docs/_data/plugins.py` will update the `nav` of the
+documentation with these repos and will load file `docs/_data/repo.yaml`
+allowing to access to the repo informations.
+
+
+## Extra variables
+
+All of the above file will create variables which can be use in your
+documentation using [mkdocs-macros-plugin][mkdocs-macros-plugin]. If you want to
+add extra variables which are not in `vars.yaml`, nor `repo.yaml`, neither in
+`subrepo.yaml`, you can do it by settings them in a file
+`docs/_data/extra.yaml`. Indeed, previously mentionned filed will be check
+against a schema (provided in `docs/_data/{repo,subrepo,vars}.schema.yaml`),
+thus do not allow extra variables to ensure stability of script
+`docs/_data/plugins.py` while file `docs/_data/extra.yaml` is loaded as it is
+without schema control.
+
+[mkdocs-macros-plugin]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/
+
+## Variable usage
+
+Finally, as describe above some variables are used during the rendering of the
+documentation. But they can also be use in your markdown documentation files using
+jinja. For instance, below is a basic content of a markdown file showing the
+name of the repo, its description and a list of roles and programs with their
+description.
+
+=== "Markdown"
+
+ ```jinja
+ {% raw %}
+ <!-- Print the name of the repo -->
+ # {{ my_repo_slug.name }}
+
+ <!-- Print the desc of the repo -->
+ {{ my_repo_slug.desc }}
+
+ <!-- Print a section and a table with repo information from subrepo -->
+ {%- for i_key in subrepo %}
+ <!-- Print the title of the section from `nav_entry` in subrepo -->
+ # {{ subrepo[i_key].nav_entry }}
+
+ <!-- Start the table with repo information -->
+ | Name | Description |
+ | ---- | ----------- |
+ {%- for i_repo_type in subrepo[i_key] %}
+ {%- if i_repo_type in ("external","internal") %}
+ {%- for i_repo in subrepo[i_key][i_repo_type] %}
+ {# Get the content of the dictionary #}
+ {%- set curr_repo = subs(i_repo.name) %}
+ | {{ curr_repo.name }} | {{ curr_repo.desc }}
+ {%- endfor %}
+ {%- endif %}
+ {%- endfor %}
+ {%- endfor %}
+ {% endraw %}
+ ```
+=== "Rendered HTML"
+
+ # {{ example.my_repo_slug.name }}
+
+ {{ example.my_repo_slug.desc }}
+
+ {%- for i_key in example.subrepo %}
+
+ ## {{ example.subrepo[i_key].nav_entry }}
+
+ | Name | Description |
+ | ---- | ----------- |
+ {%- for i_repo_type in example.subrepo[i_key] %}
+ {%- if i_repo_type in ("external","internal") %}
+ {%- for i_repo in example.subrepo[i_key][i_repo_type] %}
+ {#- Get the content of the dictionary #}
+ {%- set curr_repo = subs(i_repo.name) %}
+ | {{ curr_repo.name }} | {{ curr_repo.desc }} |
+ {%- endfor %}
+ {%- endif %}
+ {%- endfor %}
+ {%- endfor %}
+
+
+You are now ready to write your documentation. Juste remember **to not update**
+content between markdown tags.
+
+Moreover, later the main template may get upgraded (like adding new feature or
+providing new template content), to automatically apply this upgrade to your
+documentation see [Upgrade][upgrade].
+
+And finally, you may want to provide your own template, with custom CSS for
+instance, or pre-fill index documentation page, to do so, set [Setup Your Own
+Template][setup_your_own_template]
+
+[ansible_collection]: https://docs.ansible.com/ansible/latest/dev_guide/developing_collections.html#collection-structure
+[docs.romaindeville.fr]: {{ site_base_url }}
+[upgrade]: upgrade.md
+[setup_your_own_template]: ../personal_template/index.md
diff --git a/docs/usage/index.md b/docs/usage/index.md
new file mode 100644
index 0000000000000000000000000000000000000000..78cf69d80e8f0f4062ecabcf68c3c5076e321472
--- /dev/null
+++ b/docs/usage/index.md
@@ -0,0 +1,11 @@
+# Usage of this repo
+
+In this section of the documentation, you will see how to :
+
+ - [Setup a MKDocs Template][setup]
+ - [Configure Installed Template][configure]
+ - [Upgrade Template to latest version][upgrade]
+
+[setup]: setup.md
+[configure]: configure.md
+[upgrade]: upgrade.md
diff --git a/docs/usage/setup.md b/docs/usage/setup.md
new file mode 100644
index 0000000000000000000000000000000000000000..7baf73d6e06e40f639c8147697f33fd3a2e19be1
--- /dev/null
+++ b/docs/usage/setup.md
@@ -0,0 +1,147 @@
+{% set curr_repo=subs("mkdocs_template") %}
+# Setup a template
+
+The installation of a mkdocs documentation from a template is done using the
+script `setup.sh` at the root of the repo.
+
+{% include "docs/usage/setup.sh.md" %}
+
+## Installation of the template
+
+Assuming you want to use the **really** basic template provided at [{{
+git_platform.name }} - {{ curr_repo.git_name_with_namespace }}]({{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}). In a repo in which you
+want to create a documentation, type the following commands:
+
+```bash
+# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
+# First download the setup script into a temporary folder
+wget {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \
+ -O /tmp/setup_mkdocs.sh
+# Then read the content of the script with your favorite editor
+vim /tmp/setup_mkdocs.sh
+# If you are confident with what the script does, make it executable and run it
+chmod +x /tmp/setup_mkdocs.sh
+/tmp/setup_mkdocs.sh -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}
+```
+
+Or if you already read the content of the script `setup.sh` at the root of this
+repo, previous commands can be done in online:
+
+```bash
+# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
+# You can get the content of the script setup.sh via curl and pipe it into bash
+curl -sfL \
+ {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \
+ | bash -s -- \
+ -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}
+```
+
+This will automatically copy the content of folder `templates` of the project in
+the folder where you are located.
+
+Note that some copied files will have comment tag automatically added if they
+are not present. For instance, following example content:
+
+```markdown
+# Title
+
+Sample content of a page
+```
+
+Wille be copied with the following tags:
+
+```md
+<!-- BEGIN MKDOCS TEMPLATE -->
+<!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! -->
+<!-- Modified content will be overwritten when updating -->
+# Title
+
+Sample content of a page
+
+<!-- END MKDOCS TEMPLATE -->
+```
+
+These tags serve as delimiter of the template content, without theme, any
+modification you may have done on copied file will be overwritten when you will
+upgrade to a latest template version.
+
+So this allow you to add content before and after these tags, content you will
+add before and after will not be modified when upgrading while content between
+tags might be updated if latest version contain updte.
+
+In other words, you might do the following update:
+
+```md
+# Previous title
+
+Content added by the user, which will not be updated in case of upgrade of the
+template.
+
+<!-- BEGIN MKDOCS TEMPLATE -->
+<!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! -->
+<!-- Modified content will be overwritten when updating -->
+# Title
+
+Sample content of a page
+
+<!-- END MKDOCS TEMPLATE -->
+
+# Next title
+
+Content added by the user, which will not be updated in case of upgrade of the
+template.
+```
+
+The tag comment depends of the extension of the file copied:
+
+ - `*.md`, `*.html` or `*LICENSE`, will have following tags:
+ ```html
+ <!-- BEGIN MKDOCS TEMPLATE -->
+ <!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! -->
+ <!-- Modified content will be overwritten when updating -->
+
+ [...]
+
+ <!-- END MKDOCS TEMPLATE -->
+ ```
+
+ - `*.css`, `*.js`, will have following tags:
+ ```css
+ /* BEGIN MKDOCS TEMPLATE */
+ /* WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! */
+ /* Modified content will be overwritten when updating */
+
+ [...]
+
+ /* END MKDOCS TEMPLATE */
+ ```
+
+ - `*.yaml`, `*.yml`, `*.gitignore`, `*.toml`, `*.in`, `*.txt`, will have
+ ```yaml
+ ### BEGIN MKDOCS TEMPLATE ##
+ ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! ###
+ ### Modified content will be overwritten when updating ###
+ ###
+
+ [...]
+
+ ### END MKDOCS TEMPLATE ###
+ ```
+
+ - Other extension files will not have comment tags, this is mainly for source
+ code file or svg images for instance.
+
+
+Moreover, is there is already mkdocs tag in the file, the complete file will be
+copied during setup but only content between tags will be overwritten when
+upgrading.
+
+For instance, the file `mkdocs.yml` has most of its content between tags, only
+the end is not between tags. So when installing the template for the first time,
+all of the file will be installed while when upgrading only content between tag
+will be overwritten.
+
+Once you have install the mkdocs template files using the script `setup.sh` you
+know have some [configuration][configuration] to do.
+
+[configuration]: configure.md
diff --git a/docs/usage/setup.sh.md b/docs/usage/setup.sh.md
new file mode 100644
index 0000000000000000000000000000000000000000..683f59ac2c512580acebd87db3e9a5293a55218c
--- /dev/null
+++ b/docs/usage/setup.sh.md
@@ -0,0 +1,33 @@
+## Synopsis of `setup.sh`
+
+`./setup.sh [-u|--upgrade] [-s|--subrepo] [-h|--help] -r|--repo-url REPO_URL`
+
+## Description
+
+This script will install/upgrade set of scripts and files to create and
+manage documentation rendered using mkdocs.
+
+If directory is already using mkdocs and user does not provide
+`-u|--upgrade` options, an error will be shown and nothing will be done.
+
+If user does not provide REPO_URL from which download the template, i.e.
+using option `-r|--repo-url REPO_URL`, then an error will be prompt and
+the script will exit.
+
+## Options
+
+Available options are:
+
+ * `-u,--upgrade` : Upgrade the current mkdocs documentation to the latest
+ template version.
+
+ * `-s,--subrepo` : Specify the current repo is a subrepo that will be
+ merge into another main project using mkdocs-monorepo
+ plugin.
+
+ * `-r,--repo-url` : URL of the repo from which the template will be
+ downloaded.
+
+ * `-h,--help` : Print the help.
+
+
diff --git a/docs/usage/upgrade.md b/docs/usage/upgrade.md
new file mode 100644
index 0000000000000000000000000000000000000000..a8b07dab75c0ee64e9b7a94252973355cce97bc9
--- /dev/null
+++ b/docs/usage/upgrade.md
@@ -0,0 +1,47 @@
+{% set curr_repo=subs("mkdocs_template") %}
+# Upgrade to latest template
+
+If the source template get new features, like improving `plugins.py·` script,
+you might want to get them. To to so is as easy as installing the documentation.
+This is done using the script `setup.sh` with the option `-u`. Below is a recall
+of the usage of the script
+
+{% include "docs/usage/setup.sh.md" %}
+
+## How to upgrade
+
+
+This is done by using the option `-u` of the script `setup.sh`. Using this
+option, the script will compare last version with old version of each files, if
+they have changed, backup the old version, to avoid losing content in case of error
+and then upgrade the files to the latest version.
+
+```bash
+# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
+# First download the setup script into a temporary folder
+wget {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \
+ -O /tmp/setup_mkdocs.sh
+# Then read the content of the script with your favorite editor
+vim /tmp/setup_mkdocs.sh
+# If you are confident with what the script does, make it executable and run it
+chmod +x /tmp/setup_mkdocs.sh
+# NOTE THE USAGE OF THE `-u` OPTION
+/tmp/setup_mkdocs.sh -u -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}
+```
+
+Or if you already read the content of the script `setup.sh` at the root of this
+repo, previous commands can be done in online:
+
+```bash
+# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
+# You can get the content of the script setup.sh via curl and pipe it into bash
+# NOTE THE USAGE OF THE `-u` OPTION
+curl -sfL \
+ {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}/-/raw/master/setup.sh \
+ | bash -s -- \
+ -u -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}
+```
+
+This will automatically upgrade the content of your documentation from the
+template to its latest version.
+