Skip to content

Numtide Material for MkDocs base repo

For full documentation visit mkdocs-material.

here are the base steps:

1. Clone the repo you want to add mcDocs to.

2. Install material for mkDocs on your machine (using Python3 pip)

python3 -m pip install mkdocs-material

(This is a global installation - only needs doing first time or if you want to run mkdocs locally)

3. initiate mkDocs

This step only needs doing if you don't already have a docs folder. If you have docs already jump to step 4.

Go to the root directory of your cloned project and run mkdocs. This will set up docs folder, index.md and mkdocs.yaml file (note the fullstop)

`mkdocs new .`

This will create the following structure:

├─ docs/
        └─ index.md
        └─ ** add your .md files here !
└─ mkdocs.yml

** make sure your .md files are all in the docs folder

4. customize the mkdocs.yaml file for Urls and Navigation

Copy the custom mkdocs.yaml file into the root and edit the following for your repo:

site_name: - This will be the name displayed in docs header

site_description: - change this according to the relevant Numtide repo description

site_url: - change this according to the relevant Numtide repo docs location - eg https://numtide.github.io/treefmt/

repo_url: - change this according to the relevant Numtide repo url

Set the navigation structure:

nav: - About the project: index.md

This will determine which .md files in the docs folder are shown and where they appear in the header and sidebar navigation This example is taken from the active treefmt docs:

See the nav section in the treefmt example.

5. Copy custom Assets and stylesheets folders

Copy custom Assets and stylesheets folders and contents into the docs folder

6. Edit index.md file to be the landing docs page

mkDocs needs an index.md page so it needs to be included and should be your landing page

7. build your site locally to test

from terminal in root local repo folder run : mkdocs serve

Point your browser to localhost:8000 and you should see the documentation

8. setup github workflow for docs deployment

Copy the deployMkDocs.yaml file to your .github/workflows folder

9. setup github repo pages in settings

Goto repo settings/Pages and set the following:

Build and Deployment - Source =  Deploy from branch

Branch = gh-pages and folder = /(root)

10. final project layout

mkdocs.yml          # The configuration file.
docs/
    index.md        # The documentation homepage.
    ...             # Other markdown pages, images and other files.
    Assets          # folder containing custom fonts, favicon and logo
    stylesheets     # folder containing custom css file

mkDocs Commands

  • mkdocs new [dir-name] - Create a new project.
  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.