release-1.0.0 into master

 v1.0.0 (29/04/2021)

First initial release of MkDocs Template

-  Add bunch of features:
    - `setup.sh` script to automatically install template,
    - `template` folder holding basic template files, script
      `docs/_data/plugins.py` to dynamically setup `mkdocs.yml` configuration
      and schema and template for files read by the script
-  Add bunch of configuration files:
    - Syntax and workflow configuration files such as `.editorconfig`,
      `.yamllint`, `pyproject.toml`
-  Add CI which test the scripts (bash and python), build the
  documentation and deploy it
-  Add the documentation describing the usage of the template with needed
  assets.
-  Add licenses, MIT and Beer-Ware.

docs/_data/extra.yaml

+# 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

docs/about/release_notes.md

@@ -8,3 +8,21 @@ Modified content will be overwritten when updating
 
 <!-- END MKDOCS TEMPLATE -->
 
+## 🔖 v1.0.0 <small>(29/04/2021)</small>
+
+First initial release of MkDocs Template
+
+- ✨ Add bunch of features:
+    - `setup.sh` script to automatically install template,
+    - `template` folder holding basic template files, script
+      `docs/_data/plugins.py` to dynamically setup `mkdocs.yml` configuration
+      and schema and template for files read by the script
+- 🔧 Add bunch of configuration files:
+    - Syntax and workflow configuration files such as `.editorconfig`,
+      `.yamllint`, `pyproject.toml`
+- 👷 Add CI which test the scripts (bash and python), build the
+  documentation and deploy it
+- 📝🍱 Add the documentation describing the usage of the template with needed
+  assets.
+- 📄 Add licenses, MIT and Beer-Ware.
+

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/

docs/personal_template/create.md

+{% 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 }}

docs/personal_template/example.md

+{% set curr_repo=subs("mkdocs_template") %}
+# Example
+
+This current documentation you are reading is actually using the custom template
+[Mkdocs Template R.Deville][mkdocs_template_rdeville].
+
+This custom template add a lots of things such as :
+
+  - `.gitlab-ci.yaml` with basic CI file at the root of the repo to later be
+    extended and another CI file to only test and build the documentation,
+  - Workflow files definining some syntax rules such as `.editorconfig`,
+    `.yamllint`, `pyproject.toml` (which also define basic test using `tox`),
+  - `README.md`, a template of README which is automatically updated with the
+    script `post_setup.sh`,
+  - `mkdocs.yml` with more plugins and more configuration than the basic file.
+  - A default `docs/_data/vars.yaml` file,
+  - A complete theme using new plugins defined in `mkdocs.yml` with custom CSS,
+    javascript, images, etc.,
+  - A predefined basic `docs` content,
+  - And many more things.
+
+Below is an example of the rendering of the preview of the basic template and
+the custom template.
+
+
+=== "Basic Template"
+
+    ![!Basic Template Preview][basic_template_preview]
+
+
+=== "Custom Template"
+
+    ![!Custom Template Preview][custom_template_preview]
+
+[mkdocs_template_rdeville]: {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}_rdeville
+[basic_template_preview]: ../assets/img/basic_template_preview.png
+[custom_template_preview]: ../assets/img/custom_template_preview.png
+

docs/personal_template/index.md

+# 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

docs/personal_template/usage.md

+{% 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
+```

docs/usage/configure.md

+# 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

docs/usage/index.md

+# 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

docs/usage/setup.md

+{% 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

docs/usage/setup.sh.md

+## 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.
+
+

docs/usage/upgrade.md

+{% 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.
+

mkdocs.yml

@@ -295,6 +295,16 @@ plugins:
 # ---------------------------------------------------------------------------
 nav:
   - Home: index.md
+  - Use Template:
+    - usage/index.md
+    - Setup Template: usage/setup.md
+    - Configure Installed Template: usage/configure.md
+    - Upgrade Template: usage/upgrade.md
+  - Setup Your Own Template:
+    - personal_template/index.md
+    - Create Your Template: personal_template/create.md
+    - Use Your Template: personal_template/usage.md
+    - Example: personal_template/example.md
   - Code References:
     - setup.sh: references/setup.md
     - preview.sh: references/preview.md

templates/docs/_data/plugins.py

@@ -810,9 +810,9 @@ def update_version(env: dict) -> None:
         return
     git_repo = git.Repo(search_parent_directories=True)
     mike_version = list()
-    last_major = 0
-    last_minor = 0
-    last_patch = 0
+    last_major = -1
+    last_minor = -1
+    last_patch = -1
     for i_tag in git_repo.tags:
         i_tag = yaml.dump(i_tag.path)
         i_tag = re.sub(".*v", "", i_tag).split(".")
@@ -820,29 +820,31 @@ def update_version(env: dict) -> None:
         minor = int(i_tag[1])
         patch = int(i_tag[2])
         if major > last_major:
-            mike_version.append(
-                {
-                    "version": "{}.{}".format(last_major, last_minor),
-                    "title": "{}.{}.{}".format(
-                        last_major, last_minor, last_patch
-                    ),
-                    "aliases": [],
-                }
-            )
+            if last_major >= 0:
+                mike_version.append(
+                    {
+                        "version": "{}.{}".format(last_major, last_minor),
+                        "title": "{}.{}.{}".format(
+                            last_major, last_minor, last_patch
+                        ),
+                        "aliases": [],
+                    }
+                )
             last_major = major
-            last_minor = 0
+            last_minor = -1
         if minor > last_minor:
-            mike_version.append(
-                {
-                    "version": "{}.{}".format(last_major, last_minor),
-                    "title": "{}.{}.{}".format(
-                        last_major, last_minor, last_patch
-                    ),
-                    "aliases": [],
-                }
-            )
+            if last_minor >= 0:
+                mike_version.append(
+                    {
+                        "version": "{}.{}".format(last_major, last_minor),
+                        "title": "{}.{}.{}".format(
+                            last_major, last_minor, last_patch
+                        ),
+                        "aliases": [],
+                    }
+                )
             last_minor = minor
-            last_patch = 0
+            last_patch = -1
         if patch > last_patch:
             last_patch = patch
     mike_version.append(