Setup a template
The installation of a mkdocs documentation from a template is done using the
setup.sh at the root of the repo.
./setup.sh [-u|--upgrade] [-s|--subrepo] [-h|--help] -r|--repo-url REPO_URL
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.
-r|--repo-url REPO_URL, then an error will be prompt and
the script will exit.
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.
Installation of the template
Assuming you want to use the really basic template provided at Framagit - My Programs / Mkdocs Template. In a repo in which you want to create a documentation, type the following commands:
# ASSUMING YOU ARE IN THE REPO FOR WHICH YOU WANT TO WRITE A DOCUMENTATION # First download the setup script into a temporary folder wget https://framagit.org/rdeville.public/my_programs/mkdocs_template/-/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 https://framagit.org/rdeville.public/my_programs/mkdocs_template
Or if you already read the content of the script
setup.sh at the root of this
repo, previous commands can be done in one line:
# 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 \ https://framagit.org/rdeville.public/my_programs/mkdocs_template/-/raw/master/setup.sh \ | bash -s -- \ -r https://framagit.org/rdeville.public/my_programs/mkdocs_template
This will automatically copy the content of folder
templates of the Mkdocs
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:
# Title Sample content of a page
Will be copied with the following tags:
<!-- 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 them, any 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 update.
In other words, you might do the following:
# 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 on the extension of the file copied:
*LICENSE, will have following tags:
<!-- BEGIN MKDOCS TEMPLATE --> <!-- WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! --> <!-- Modified content will be overwritten when updating --> […] <!-- END MKDOCS TEMPLATE -->
*.js, will have following tags:
/* BEGIN MKDOCS TEMPLATE */ /* WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! */ /* Modified content will be overwritten when updating */ […] /* END MKDOCS TEMPLATE */
*.txt, will have
### BEGIN MKDOCS TEMPLATE ## ### WARNING, DO NOT UPDATE CONTENT BETWEEN MKDOCS TEMPLATE TAG ! ### ### Modified content will be overwritten when updating ### ### […] ### END MKDOCS TEMPLATE ###
Files with other extension will not have comment tags, this is mainly for source code file or svg images for instance.
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.
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
now have some configuration to do.