Mkdocs Templates scaffolding project to host documentation configuration and themes to manage homogenous documentation accros multiple projects.
Main repo is on Framagit - My Programs / Mkdocs Template.
On other online git platforms, they are just mirrors of the main repo.
Any issues, pull/merge requests, etc., might not be considered on those other platforms.
Since some times now, I use mkdocs to write documentation of my projects.
While 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.
Below is a really basic usage example of this repo, more complete documentation is provided at section Use Template and if you want to create your own template from this repo, you can refer to the section 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:
# 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//-/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/
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:
# 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//-/raw/master/setup.sh \ | bash -s -- -r https://framagit.org/
This will automatically create the folder
docs with basic pages and the
What you will now have to do is :
- Copy the provided template file
repo_nameis the slug of your repo (for instance slug of
mkdocs_templateand slug of
- Edit this new file
docs/_data/repo_name.yml, especially, do not forget to change the key
repo_namein the file accordingly to your repo slug.
You are ready now to render you documentation: