Merge branch 'release-v1.0.3'

066f222f · Romain Deville · 3d28e8ba · e26353ba · 066f222f · 066f222f
Verified Commit 066f222f authored 4 years ago by Romain Deville
--- a/README.md
+++ b/README.md
@@ -12,8 +12,8 @@
 --------------------------------------------------------------------------------
-Template to easily setup and managed [mkdocs][mkdocs] documentation in folder
+Mkdocs Templates scaffolding project to host documentation configuration
-to have homogenous documentation.
+and themes to manage homogenous documentation accros multiple projects.
 --------------------------------------------------------------------------------
@@ -49,13 +49,13 @@ 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.
+project 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
+I had to go to each project 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
+This project aim is to ease the management of documentation configuration by
 allowing to create a template and easily setup or upgrade it to a newer
 version.
@@ -78,7 +78,7 @@ chmod +x /tmp/setup_mkdocs.sh
 ```
 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:
+repo, previous commands can be done in one line:
 ```
 # ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
@@ -169,4 +169,4 @@ You can now browse the full documentation by visiting
 <!-- END MKDOCS TEMPLATE -->
-[online_doc]: https://docs.romaindeville.fr/rdeville.public/my_programs/mkdocs_template/index.html
+[online_doc]: https://docs.romaindeville.fr/my_programs/mkdocs_template/index.html
--- a/docs/_data/extra.yaml
+++ b/docs/_data/extra.yaml
@@ -2,7 +2,7 @@
 example:
  my_repo_slug:
    name: My Main Repo Name
-    desc: Description of my [Main Repo](#)
+    desc: Description of my [Main Repo]()
  subrepo:
    roles:
      nav_entry: "Roles"

--- a/docs/_data/plugins.py
+++ b/docs/_data/plugins.py
@@ -153,6 +153,10 @@ def add_external_to_nav(
                        repo_parent,
                        nav_parent[1:],
                    )
+    elif repo_dict["online_url"].startswith('/'):
+        nav.append({
+            repo_dict["nav_entry"]: repo_dict["online_url"].replace('/','../',1)
+        })
    else:
        nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})
@@ -833,10 +837,8 @@ def update_version(env: dict) -> None:
            if last_major >= 0:
                mike_version.append(
                    {
-                        "version": "{}.{}".format(last_major, last_minor),
+                        "version": f"{last_major}.{last_minor}",
-                        "title": "{}.{}.{}".format(
+                        "title": f"{last_major}.{last_minor}.{last_patch}",
-                            last_major, last_minor, last_patch
-                        ),
                        "aliases": [],
                    }
                )
@@ -846,10 +848,8 @@ def update_version(env: dict) -> None:
            if last_minor >= 0:
                mike_version.append(
                    {
-                        "version": "{}.{}".format(last_major, last_minor),
+                        "version": f"{last_major}.{last_minor}",
-                        "title": "{}.{}.{}".format(
+                        "title": f"{last_major}.{last_minor}.{last_patch}",
-                            last_major, last_minor, last_patch
-                        ),
                        "aliases": [],
                    }
                )
@@ -859,8 +859,8 @@ def update_version(env: dict) -> None:
            last_patch = patch
    mike_version.append(
        {
-            "version": "{}.{}".format(last_major, last_minor),
+            "version": f"{last_major}.{last_minor}",
-            "title": "{}.{}.{}".format(last_major, last_minor, last_patch),
+            "title": f"{last_major}.{last_minor}.{last_patch}",
            "aliases": ["latest"],
        }
    )
@@ -914,9 +914,11 @@ def define_env(env: dict) -> None:
            var: Key in env.variables to return.
        Returns:
-            The value of `env.variables[var]`.
+            The value of `env.variables[var]` if it exists, else return None.
        """
-        return env.variables[var]
+        if var in env.variables:
+            return env.variables[var]
+        return None
    @env.macro
    # pylint: disable=W0612

--- a/docs/_data/template/repo.tpl.yaml
+++ b/docs/_data/template/repo.tpl.yaml
 ### BEGIN MKDOCS TEMPLATE ###
 ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
 ### Modified content will be overwritten when updating.###
@@ -29,11 +30,13 @@ repo_name:
  # (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`
+  # `assets/img/meta/repo_name_logo.png`
-  #logo: "assets/img/meta/repo_template_logo.png"
+  #logo: "assets/img/meta/repo_name_logo.png"
  # Description of the repo, will be used to setup the mkdocs description.
  desc: >-
-    Repo description with markdown support
+    An explicit description to explain what my repo do. Can be a multiline
+    description with **markdown** support such as
+    [link](https://url.domain.tld) and more.
  # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python
  # source code, you will need to provide the path where your source files
@@ -47,3 +50,4 @@ repo_name:
    - name: "Firstname Lastname"
      mail: "mail@domain.tld"
 ### END MKDOCS TEMPLATE ###
--- a/docs/_data/template/subrepo.tpl.yaml
+++ b/docs/_data/template/subrepo.tpl.yaml
 ### BEGIN MKDOCS TEMPLATE ###
 ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
 ### Modified content will be overwritten when updating.###
@@ -25,6 +26,10 @@ subrepo:
  #     - name: subrepo_1
  #       # SSH or HTTP link to the online subrepo_1
  #       git_url: git@domain.tld:namesapce/subrepo_1
+  #       # Key `subpath` is a str pointing to the path in the subrepo where
+  #       # there is a file `mkdocs.yaml` and folder `docs` if not the root
+  #       # of the subrepo
+  #       subpath: sub/dir/
  #   # List of subdirectory from `dir_name` which are repos with
  #   # mkdocs documentation which will be included in the documentation.
  #   external:
@@ -34,6 +39,10 @@ subrepo:
  #     - name: subrepo_2
  #       # SSH or HTTP link to the online subrepo_2
  #       git_url: git@domain.tld:namesapce/subrepo_2
+  #       # Key `subpath` is a str pointing to the path in the subrepo where
+  #       # there is a file `mkdocs.yaml` and folder `docs` if not the root
+  #       # of the subrepo
+  #       subpath: sub/dir/
  #   # Another sub dir_name which also old subrepos
  #   subdir_name:
  #     nav_entry: "Sub Nav Entry"
@@ -75,3 +84,4 @@ subrepo:
  #     - Mkdocs Template: /my_program/mkdocs_template/
  # ```
 ### END MKDOCS TEMPLATE ###
--- a/docs/about/contributing.md
+++ b/docs/about/contributing.md
 {% set curr_repo=subs("mkdocs_template") %}
 <!-- BEGIN MKDOCS TEMPLATE -->
 <!--
 WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !
@@ -40,9 +41,9 @@ my projects. There you will find:
  * [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
+[developers_guides]: {{ site_base_url }}/latest/dev_guides/index.html
-[syntax_guide]: {{ site_base_url }}/dev_guides/style_guides/index.html
+[syntax_guide]: {{ site_base_url }}/latest/dev_guides/style_guides/index.html
-[contributing_workflow]: {{ site_base_url }}/dev_guides/contributing_workflow.html
+[contributing_workflow]: {{ site_base_url }}/latest/dev_guides/developer_guidelines.html
 ## Community
@@ -52,3 +53,4 @@ conduct][code_of_conduct].
 [code_of_conduct]: code_of_conduct.md
 <!-- END MKDOCS TEMPLATE -->
--- a/docs/about/release_notes.md
+++ b/docs/about/release_notes.md
@@ -10,6 +10,18 @@ Modified content will be overwritten when updating
 ## 🔖 v1.0
+### 🔖 v1.0.3 <small>(13/05/2021)</small>
+- 📝 Update documentation content.
+- 🔧 Update extra content through yaml `_data·` files
+ - Add new content
+ - Add documentation in template files
+- ✨ Improve `plugins.py` behaviour
+  - Convert `.format()` string into `f""` string
+  - Fix configuration management
+- ⬆📌 Upgrade pinned python dependencies
 ### 🔖 v1.0.2 <small>(29/04/2021)</small>
 - 📝📄 Update copyright in license content

--- a/docs/personal_template/create.md
+++ b/docs/personal_template/create.md
@@ -15,7 +15,8 @@ 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:
+Then, choose where you want to store your fork in one of your accessible
+namespaces:
 ![!Fork Mkdocs Template Destination][fork_mkdocs_template_dest]
@@ -44,20 +45,21 @@ git clone git@gitdomain.tld:namespace/mkdocs_template.git.
 ## Add the content of your template
-Now, to setup your own template, you just have to write it in the empty folder
+Now, to setup your own template, you just have to write it in the empty, but
-but track `user_config` folder. If you happen to add a file with the same path
+tracked, folder `user_config`. If you happen to add a file with the same
-from `template`, the your file will override the one in `template`.
+path from `template`, then 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.
+customized command once `setup.sh` finish. The script `post_setup.sh` will be
+automatically included at the end of the execution of the script `setup.sh`.
-Below are some examples such as a possible structure of `user_config` folder as
+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
+well as some content examples. Note that every files, hidden or not, within
-`user_config` are copied when installed, which can be usefull to provide
+folder `user_config` are copied when installed, which can be usefull to provide
-configuration workflow files, such as `.editorconfig`, `.gitignore`, etc. files.
+configuration workflow files, such as `.editorconfig`, `.gitignore`, etc.
 === "Folder `user_config`"
@@ -398,7 +400,7 @@ git remote -v
 > origin <URL_TO_YOUR_ORIGIN_REMOTE> (push)
 ```
-If there is not upstream, add the `upstream` remote:
+If there is no `upstream`, add the `upstream` remote:
 ```bash
 git remote add upstream {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}.git

--- a/docs/personal_template/example.md
+++ b/docs/personal_template/example.md
 {% set curr_repo=subs("mkdocs_template") %}
 # Example
-This current documentation you are reading is actually using the custom template
+The 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 :
@@ -22,12 +22,10 @@ This custom template add a lots of things such as :
 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]

--- a/docs/personal_template/index.md
+++ b/docs/personal_template/index.md
@@ -4,9 +4,10 @@ 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
+But, you may want to use extra plugins such as
-provide a basic README.md as well as licenses or a default file
+[mkdocs-mermaid2-plugin][mkdocs_mermaid2_plugin] or provide a basic `README.md`
-`docs/_data/vars.yml` for all your documentation.
+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:

--- a/docs/references/preview.md
+++ b/docs/references/preview.md
@@ -10,36 +10,31 @@ Setup a temporary documentation folder to preview the rendering of the template
 This script will build the final list of folder that will be installed in
 the folder that will host the documenation and render a preview of such
-basic documenation based from template.
+basic documentation based from template.
 This will be done by creating symlinks from `templates` and `user_config`
 folders into `preview` folder.
 Available options are:
-  `-c,--clean`      : Remove every existing symlinks before rendering the
+  * `-c,--clean`      : Remove every existing symlinks before rendering the
-                      preview.
+                        preview.
-  `-r,--very-clean` : Remove every existing symlinks without rendering the
+  * `-r,--very-clean` : Remove every existing symlinks without rendering the
-                      preview.
+                        preview.
-  `-h,--help`       : Print this help.
+  * `-h,--help`       : Print this help.
 ## main()
- **Setup folder to be able to use directory environment mechanism**
+ **Setup preview folder to be able to see the rendering of the documentation template.**
- Check if git is installed. Then check that folder is not already using
+ Build the list of the file that will be installed if using the mkdocs
- mkdocs documentation.
+ documentation template, make a symlinks of all these files into `preview`
+ folder and, depending on the options provided, render the documentation
- If directory already set to use directory environment, then check if user
+ preview.
- explicitly tell to upgrade and upgrade, otherwise, print a warning and exit.
- If directory not already set to use directory environment, clone
- user provided repo to a temporary folder, copy relevant scripts, files and
- folders to initiliaze a documentation rendered using mkdocs.
 **Globals**
@@ -54,9 +49,9 @@ Available options are:
 | Arguments | Description |
 | :-------- | :---------- |
- | `-u,--upgrade` | -u,--upgrade |
+ | `-c,--clean`      |  Remove every existing symlinks before rendering the preview. |
- | `-r,--repo-url REPO_URL` | -r,--repo-url REPO_URL |
+ | `-r,--very-clean` |  Remove every existing symlinks without rendering the preview. |
- | `-s,--subrepo` | -s,--subrepo |
+ | `-h,--help`       |  Print this help. |
 **Output**
@@ -64,13 +59,13 @@ Available options are:
 **Returns**
- - 0 if directory is correctly configure to start writing documentation
+ - 0, if rendering of the preview documentation went right.
- - 1 if something when wrong during the setup of documentation
+ - 1, if rendering of the preview documentation went wrong.
 ### manpage()
-> **Extract the script documentation from header and print it on stdout**
+> **Extract the script documentation from header and print it on stdout.**
-> 
+>
 > Simply extract the docstring from the header of the script, format it with
 > some output enhancement (such as bold) and print it to stdout.
 >
@@ -86,16 +81,16 @@ Available options are:
 ### mkdocs_log()
-> **Print debug message in colors depending on message severity on stderr**
+> **Print debug message in colors depending on message severity on stderr.**
-> 
+>
 > Echo colored log depending on user provided message severity. Message
 > severity are associated to following color output:
-> 
+>
 >   - `DEBUG` print in the fifth colors of the terminal (usually magenta)
 >   - `INFO` print in the second colors of the terminal (usually green)
 >   - `WARNING` print in the third colors of the terminal (usually yellow)
 >   - `ERROR` print in the third colors of the terminal (usually red)
-> 
+>
 > If no message severity is provided, severity will automatically be set to
 > INFO.
 >
@@ -119,7 +114,7 @@ Available options are:
 ### build_file_list()
 > **Recursively build a list of file from provided folder**
-> 
+>
 > Recursively build a list of file from provided folder and store such list
 > in a temporary bash array that must be set in parent method.
 >
@@ -128,18 +123,19 @@ Available options are:
 >
 > | Arguments | Description |
 > | :-------- | :---------- |
-> | `$1, string, absolute path to the folder which will be parsed` | $1, string, absolute path to the folder which will be parsed |
+> | `$1` |  string, absolute path to the folder which will be parsed |
 >
 >
 ### build_final_file_list()
-> **Replate templates file by user configured files**
+> **Build the merged list from `templates` and `user_config` folder.**
-> 
+>
 > If there is the same file in `user_config` and `templates` folder, then
 > replace the file to be installed from `templates` by the one in
 > `user_config`. Finally, add remaining `user_config` files not in
-> `templates` to the list of files to install or upgrade in a bash array.
+> `templates` to the list of files to install or upgrade in a bash array set
+> in parent method.
 >
 > **Globals**
 >
@@ -150,7 +146,8 @@ Available options are:
 ### clean_preview()
 > **Recursively clean the preview folder by removing all symlinks**
-> 
+>
+> Simply remove recursively all symlinks from folder `preview`.
 >
 > **Globals**
 >
@@ -165,11 +162,11 @@ Available options are:
 ### setup_mkdocs()
-> **Recursively install base folder and script to write mkdocs documentation.**
+> **Recursively install base folder and script to render a preview of the documentation template.**
-> 
+>
-> Build the list of files and folders, recursively copy all files to
+> Build the list of files and folders, recursively create a symlink of all
-> their right location from the temporary clone repo to the folder which
+> files to their right location from the temporary clone repo to the folder
-> will host the mkdocs documentation.
+> `preview`.
 >
 > **Globals**
 >

--- a/docs/usage/configure.md
+++ b/docs/usage/configure.md
 # Configuration of the documentation
-Once you have install files using the script `setup.sh`, and before starting to
+Once you have installed files using the script `setup.sh`, and before starting
-render your documentation you will need some configuration to do:
+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,
+Normally, most configuration of `mkdocs` is done in `mkdocs.yml` file, but to be
-but to be able to use a templated `mkdocs.yml`, most of the configuration is
+able to use a templated `mkdocs.yml`, most of the configuration is handled
-handled differently.
+differently.
 Now, it is the file `templates/docs/_data/plugins.py` which will handle the
 configuration. This file is automatically called with the
@@ -25,7 +25,8 @@ 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.
+automatically set based on the git repo information (git remote **origin**) and
+[repo variables](#repo-variables).
 [mkdocs_macros_plugins]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/
@@ -33,10 +34,10 @@ automatically set based on the repo information.
 !!! important "Ensure a git remote **origin** exists"
-    Before continuing, your documentation MUST be a git repository with a
+    Before continuing, your documentation **MUST** be a git repository with a
-    remote **origin**. Indeed, the script `docs/_data/plugins.py` will get remote
+    remote **origin**. Indeed, the script `docs/_data/plugins.py` will get
-    information to have the `repo_slug` to know which file in `docs/_data/` hold the
+    remote information to have the `repo_slug` to know which file in
-    repository information.
+    `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).
@@ -50,8 +51,9 @@ cp docs/_data/template/repo.tpl.yaml docs/_data/my_repo_slug.yaml
 vim docs/_data/my_repo_slug.yaml
 ```
-You will need to update some key of the repo which will be used to automatically
+You will need to update some keys in the repo file which will be used to
-set `mkdocs.yml` configuration if not set in `docs/_data/vars.yaml`.
+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`.
@@ -87,13 +89,14 @@ my_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`
+  # `assets/img/meta/repo_name_logo.png`
-  #logo: "assets/img/meta/repo_template_logo.png"
+  #logo: "assets/img/meta/repo_name_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)
+    description with **markdown** support such as
+    [link](https://url.domain.tld) and more.
  # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python
  # source code, you will need to provide the path where your source files
@@ -111,16 +114,17 @@ my_repo_slug:
 ## 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
+want to split the documentation such as each project hold its own but render all
-repository.
+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
+composed of a master repository holding specific files 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.
+repository (like git submodules) and each of the role holds its own
-But you want the final rendered documentation to include these repos.
+documentation. But you want the final rendered documentation to include these
+repos.
-This can be done via a file describing such subrepo, i.e.
+This can be done via a file describing such subrepo, i.e. the file
 `docs/_data/subrepo.yaml`. To do so, copy the template provided in
 `docs/_data/template/subrepo.tpl.yml`.
@@ -158,13 +162,14 @@ subrepo:
          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
+If you want to add link to external documentation, i.e. a link to the home page
-the `nav` of the main repo but their own `nav` will not be include, this can
+will be included in the `nav` of the main repo but their own `nav` will not be
-also be done with the file `docs/_data/subrepo.yaml`.
+included, 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
+An example could be a main repo simply providing entry point to other repos,
-as repo holding base content of [docs.romaindeville.fr][docs.romaindeville.fr].
+such as repo holding base content of
-Below is an example of the content of such `subrepo.yaml` file:
+[docs.romaindeville.fr][docs.romaindeville.fr]. Below is an example of the
+content of such `subrepo.yaml` file:
 ```yaml
@@ -196,7 +201,7 @@ subrepo:
          online_url: https://domain.tld/full/external/link/
 ```
-Of course, both `internal` and `external` can be used as show below (click to
+Of course, both `internal` and `external` can be used as shown below (click to
 reveal).
 ??? Example
@@ -256,22 +261,22 @@ reveal).
    ```
 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
+check if folders `roles/{role_name_1,role_name_2}` exists. If they exists and
-repo, script will pull them to get the last version. If they do not exists, the
+are git repo, script will pull them to get the last version. If they do not
-will be cloned.
+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.
+of each repo allowing to access to the repo informations.
 ## Extra variables
-All of the above file will create variables which can be use in your
+All of the above files will create variables which can be used 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
+`docs/_data/extra.yaml`. Indeed, previously mentionned filed will be checked
 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
@@ -281,11 +286,11 @@ without schema control.
 ## Variable usage
-Finally, as describe above some variables are used during the rendering of the
+Finally, as describe above some variables are used for the configuration to
-documentation. But they can also be use in your markdown documentation files using
+render documentation. But they can also be use in your markdown documentation
-jinja. For instance, below is a basic content of a markdown file showing the
+files using jinja template. For instance, below is a basic content of a markdown
-name of the repo, its description and a list of roles and programs with their
+file showing the name of the main repo, its description and a list of roles and
-description.
+programs with their description.
 === "Markdown"

--- a/docs/usage/setup.md
+++ b/docs/usage/setup.md
@@ -25,7 +25,7 @@ chmod +x /tmp/setup_mkdocs.sh
 ```
 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:
+repo, previous commands can be done in one line:
 ```bash
 # ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION
@@ -36,8 +36,8 @@ curl -sfL \
    -r {{ git_platform.url }}{{ curr_repo.git_slug_with_namespace }}
 ```
-This will automatically copy the content of folder `templates` of the project in
+This will automatically copy the content of folder `templates` of the Mkdocs
-the folder where you are located.
+Template 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:
@@ -48,7 +48,7 @@ are not present. For instance, following example content:
 Sample content of a page
 ```
-Wille be copied with the following tags:
+Will be copied with the following tags:
 ```md
 <!-- BEGIN MKDOCS TEMPLATE -->
@@ -61,15 +61,15 @@ Sample content of a page
 <!-- END MKDOCS TEMPLATE -->
 ```
-These tags serve as delimiter of the template content, without theme, any
+These tags serve as delimiter of the template content, without them, any
-modification you may have done on copied file will be overwritten when you will
+modification you may have done on copied files 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.
+tags might be updated if latest version contain update.
-In other words, you might do the following update:
+In other words, you might do the following:
 ```md
 # Previous title
@@ -92,7 +92,7 @@ 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:
+The tag comment depends on the extension of the file copied:
  - `*.md`, `*.html` or `*LICENSE`, will have following tags:
    ```html
@@ -100,7 +100,7 @@ The tag comment depends of the extension of the file copied:
    <!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! -->
    <!-- Modified content will be overwritten when updating -->
-    [...]
+    […]
    <!-- END MKDOCS TEMPLATE -->
    ```
@@ -111,7 +111,7 @@ The tag comment depends of the extension of the file copied:
    /* WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! */
    /* Modified content will be overwritten when updating */
-    [...]
+    […]
    /* END MKDOCS TEMPLATE */
    ```
@@ -123,16 +123,16 @@ The tag comment depends of the extension of the file copied:
    ### Modified content will be overwritten when updating ###
    ###
-    [...]
+    […]
    ### END MKDOCS TEMPLATE ###
    ```
-  - Other extension files will not have comment tags, this is mainly for source
+  - Files with other extension will not have comment tags, this is mainly for
-    code file or svg images for instance.
+    source code file or svg images for instance.
-Moreover, is there is already mkdocs tag in the file, the complete file will be
+Moreover, if there is already mkdocs tags in the file, the complete file will be
 copied during setup but only content between tags will be overwritten when
 upgrading.
@@ -142,6 +142,6 @@ 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.
+now have some [configuration][configuration] to do.
 [configuration]: configure.md
--- a/docs/usage/upgrade.md
+++ b/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,
+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.
+you might want to get them. To do 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
@@ -10,11 +10,10 @@ of the usage of the script
 ## 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
+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
+they have changed, backup the old version, to avoid losing content in case of
-and then upgrade the files to the latest version.
+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

--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -80,6 +80,7 @@ extra_css:
  # From: https://github.com/g-provost/lightgallery-markdown
  - theme/css/lightgallery.css
  # Define personal extra css
+  - theme/css/extra.css
  # Define colors (all materials colors RGB code)
  - theme/css/colors.css
  # Define fonts

--- a/requirements.dev.txt
+++ b/requirements.dev.txt
 ### BEGIN MKDOCS TEMPLATE ###
 ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
 ### Modified content will be overwritten when updating.###
@@ -12,11 +11,11 @@ appdirs==1.4.4
    # via
    #   black
    #   virtualenv
-astroid==2.5.3
+astroid==2.5.6
    # via pylint
-attrs==20.3.0
+attrs==21.2.0
    # via pytest
-black==20.8b1
+black==21.5b0
    # via -r requirements.dev.in
 click==7.1.2
    # via black
@@ -64,11 +63,11 @@ pydocstyle==6.0.0
    # via -r requirements.dev.in
 pyflakes==2.2.0
    # via flake9
-pylint==2.7.4
+pylint==2.8.2
    # via -r requirements.dev.in
 pyparsing==2.4.7
    # via packaging
-pytest==6.2.3
+pytest==6.2.4
    # via -r requirements.dev.in
 pyyaml==5.4.1
    # via yamllint
@@ -76,7 +75,7 @@ regex==2021.4.4
    # via black
 shellcheck-py==0.7.2.1
    # via -r requirements.dev.in
-six==1.15.0
+six==1.16.0
    # via
    #   tox
    #   virtualenv
@@ -88,17 +87,12 @@ toml==0.10.2
    #   pylint
    #   pytest
    #   tox
-tox==3.23.0
+tox==3.23.1
    # via -r requirements.dev.in
-typed-ast==1.4.3
+virtualenv==20.4.6
-    # via black
-typing-extensions==3.7.4.3
-    # via black
-virtualenv==20.4.4
    # via tox
 wrapt==1.12.1
    # via astroid
 yamllint==1.26.1
    # via -r requirements.dev.in
 ### END MKDOCS TEMPLATE ###
--- a/requirements.docs.in
+++ b/requirements.docs.in
@@ -56,4 +56,8 @@ git+https://github.com/g-provost/lightgallery-markdown
 # A Mermaid graphs plugin for mkdocs
 # https://github.com/fralau/mkdocs-mermaid2-plugin#declaring-the-superfences-extension
 mkdocs-mermaid2-plugin
+# A MkDocs plugin for dynamic page redirects to prevent broken links.
+# https://pypi.org/project/mkdocs-redirects/
+mkdocs-redirects
 ### END MKDOCS TEMPLATE ###
--- a/requirements.docs.txt
+++ b/requirements.docs.txt
 ### BEGIN MKDOCS TEMPLATE ###
 ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG !###
 ### Modified content will be overwritten when updating.###
@@ -9,7 +10,7 @@
 #
 astunparse==1.6.3
    # via pytkdocs
-babel==2.9.0
+babel==2.9.1
    # via mkdocs-git-revision-date-localized-plugin
 beautifulsoup4==4.9.3
    # via mkdocs-mermaid2-plugin
@@ -67,13 +68,13 @@ mkdocs-autorefs==0.1.1
    # via mkdocstrings
 mkdocs-exclude==1.0.2
    # via -r requirements.docs.in
-mkdocs-git-revision-date-localized-plugin==0.9
+mkdocs-git-revision-date-localized-plugin==0.9.2
    # via -r requirements.docs.in
 mkdocs-macros-plugin==0.5.5
    # via -r requirements.docs.in
 mkdocs-material-extensions==1.0.1
    # via mkdocs-material
-mkdocs-material==7.1.1
+mkdocs-material==7.1.4
    # via
    #   -r requirements.docs.in
    #   mkdocs-macros-plugin
@@ -83,7 +84,9 @@ mkdocs-mermaid2-plugin==0.5.1
    # via -r requirements.docs.in
 mkdocs-monorepo-plugin==0.4.14
    # via -r requirements.docs.in
-mkdocs-section-index==0.2.3
+mkdocs-redirects==1.0.3
+    # via -r requirements.docs.in
+mkdocs-section-index==0.3.0
    # via -r requirements.docs.in
 mkdocs==1.1.2
    # via
@@ -95,13 +98,14 @@ mkdocs==1.1.2
    #   mkdocs-material
    #   mkdocs-mermaid2-plugin
    #   mkdocs-monorepo-plugin
+    #   mkdocs-redirects
    #   mkdocs-section-index
    #   mkdocstrings
 mkdocstrings==0.15.0
    # via -r requirements.docs.in
-nltk==3.6.1
+nltk==3.6.2
    # via lunr
-pygments==2.8.1
+pygments==2.9.0
    # via mkdocs-material
 pykwalify==1.8.0
    # via -r requirements.docs.in
@@ -131,12 +135,13 @@ ruamel.yaml.clib==0.2.2
    # via ruamel.yaml
 ruamel.yaml==0.17.4
    # via pykwalify
-six==1.15.0
+six==1.16.0
    # via
    #   astunparse
    #   jsbeautifier
    #   livereload
    #   lunr
+    #   mkdocs-redirects
    #   python-dateutil
 smmap==4.0.0
    # via gitdb
@@ -158,3 +163,4 @@ wheel==0.36.2
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools
 ### END MKDOCS TEMPLATE ###
--- a/templates/docs/_data/plugins.py
+++ b/templates/docs/_data/plugins.py
@@ -153,6 +153,10 @@ def add_external_to_nav(
                        repo_parent,
                        nav_parent[1:],
                    )
+    elif repo_dict["online_url"].startswith('/'):
+        nav.append({
+            repo_dict["nav_entry"]: repo_dict["online_url"].replace('/','../',1)
+        })
    else:
        nav.append({repo_dict["nav_entry"]: repo_dict["online_url"]})
@@ -833,10 +837,8 @@ def update_version(env: dict) -> None:
            if last_major >= 0:
                mike_version.append(
                    {
-                        "version": "{}.{}".format(last_major, last_minor),
+                        "version": f"{last_major}.{last_minor}",
-                        "title": "{}.{}.{}".format(
+                        "title": f"{last_major}.{last_minor}.{last_patch}",
-                            last_major, last_minor, last_patch
-                        ),
                        "aliases": [],
                    }
                )
@@ -846,10 +848,8 @@ def update_version(env: dict) -> None:
            if last_minor >= 0:
                mike_version.append(
                    {
-                        "version": "{}.{}".format(last_major, last_minor),
+                        "version": f"{last_major}.{last_minor}",
-                        "title": "{}.{}.{}".format(
+                        "title": f"{last_major}.{last_minor}.{last_patch}",
-                            last_major, last_minor, last_patch
-                        ),
                        "aliases": [],
                    }
                )
@@ -859,8 +859,8 @@ def update_version(env: dict) -> None:
            last_patch = patch
    mike_version.append(
        {
-            "version": "{}.{}".format(last_major, last_minor),
+            "version": f"{last_major}.{last_minor}",
-            "title": "{}.{}.{}".format(last_major, last_minor, last_patch),
+            "title": f"{last_major}.{last_minor}.{last_patch}",
            "aliases": ["latest"],
        }
    )
@@ -914,9 +914,11 @@ def define_env(env: dict) -> None:
            var: Key in env.variables to return.
        Returns:
-            The value of `env.variables[var]`.
+            The value of `env.variables[var]` if it exists, else return None.
        """
-        return env.variables[var]
+        if var in env.variables:
+            return env.variables[var]
+        return None
    @env.macro
    # pylint: disable=W0612

--- a/templates/docs/_data/template/repo.tpl.yaml
+++ b/templates/docs/_data/template/repo.tpl.yaml
@@ -26,11 +26,13 @@ repo_name:
  # (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`
+  # `assets/img/meta/repo_name_logo.png`
-  #logo: "assets/img/meta/repo_template_logo.png"
+  #logo: "assets/img/meta/repo_name_logo.png"
  # Description of the repo, will be used to setup the mkdocs description.
  desc: >-
-    Repo description with markdown support
+    An explicit description to explain what my repo do. Can be a multiline
+    description with **markdown** support such as
+    [link](https://url.domain.tld) and more.
  # (OPTIONAL) If you plan to use `mkdocstring` plugins to render python
  # source code, you will need to provide the path where your source files