Template repository for provisioning a document repository with the happiness combo: MkDocs + Github Actions + GitHub Pages.
Each commit on the main
branch triggers a GitHub Action Pipeline that transpiles Markdown files to modern web static files with MkDocs and provides them via GitHub Pages.
Check the web content that your page will reach when you use this template:
The directory structure outlined below serves as the blueprint for organizing Markdown files, which are utilized in the configuration of the mkdocs.yml file to construct documentation comprising distinct sections and subsections.
โโโ docs # Directory containing Mkdocs content files
โ โโโ index.md # Main page of the site
โ โโโ <SECTION>.md # Markdown files representing individual sections and subsections
โ โโโ img # Directory for image assets
โ โโโ <SECTION-NUMBER-PREFIX>-<IMAGE-NAME>.* # Naming convention for images
โโโ Makefile # Script for setting up a local Mkdocs web server
โโโ mkdocs.yml # Manifest file for MkDocs configuration
โโโ requirements.txt # File listing Python requirements necessary for installing MkDocs and its plugins
This structure ensures systematic organization of documentation files, facilitating easy navigation and maintenance. Additionally, it provides clarity on the purpose and location of each file within the project.
Use the Makefile shortcuts to install the MkDocs dependencies and provide local web server with hot reload feature.
$ make setup # create python3 virtualenv and install requirements (MkDocs and MkDocs plugins)
$ make run # run local web server with hot reload feature
Note
If the commands above were run successfully, the web content will be accessible: http://127.0.0.1:8000/
Replace all variables under >>> REPLACE THE VALUE
in the ./mkdocs.yml with values based on your repository properties (project URL, site name, author, etc).
The .github/workflows/deploy-contents-to-github-pages.yml pipeline use the special variable ${{ secrets.GITHUB_TOKEN }}
to allow push action in the gh-pages
branch. To achieve this, you need to configure the Read Write permission in the Repository settings. This is necessary for the GitHub Action to create a branch and publish the built files. Check the following image for the configuration steps.
![]() |
Now, it is necessary to configure GitHub Pages. The GitHub Action .github/workflows/deploy-contents-to-github-pages.yml pipeline creates a gh-pages
branch with the static files transpiled by MkDocs. Thus, you need to configure GitHub Pages to use the gh-pages
branch as a source to render the web files.
![]() |
If you have correctly configured your repo, the link will be available in the following pattern:
https://<GITHUB-USERNAME>.github.io/<GITHUB-REPO>/
Note
<GITHUB-USERNAME>
and <GITHUB-REPO>
are placeholders. Replace with your properties.