Skip to content

Mkdocs Template

Mkdocs Templates scaffolding project to host documentation configuration and themes to manage homogenous documentation accros multiple projects.

IMPORTANT !
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.

Introduction

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.

Usage

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 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:

mkdocs serve
Last update: December 8, 2021
Back to top