Skip to content

MkDocs Starter Kit#

This starter kit is based on the Material theme for MkDocs, a static site generator built for documentation.

Install#

If you are using Docker, you only need to run npm install to install the Markdownlint dependencies. We specify the Docker image and build command in the package.json file.

Manual#

  1. Ensure that you're running Node >= 8.11.2

  2. Run npm install to install the Markdownlint dependencies

  3. Install MkDocs with Material theme if you wish to build and serve your doc locally

Or use this snippet to set up mkdocs:

1
2
3
4
sudo apt install python python-pip
pip install mkdocs
sudo mv ~/.local/bin/mkdocs /usr/local/bin/mkdocs
mkdocs --version

Commands#

  • npm run lint: Runs Markdownlint-cli and outputs linting errors to the console.
  • npm start: Builds and serves the MkDocs site to localhost:8000, auto-refreshes on file change.
  • npm build: Builds the MkDocs site to site/ folder. There's no need to build the site before committing though -- we handle this in the CI defined in the .gitlab-ci.yml file.

Linting rules

We've configured Markdownlint to use the "Relaxed Rules" by default. Refer to the full list of rules if you wish to add or modify your linting rules.

To save time, we recommend that you add Markdownlint to your IDE: Sublime | VSCode.

Extras#

Extensions#

We've enabled several extensions in the mkdocs.yml file, notably:

  • Admonition for styled blocks (e.g. info, warning, bug, etc)
  • CodeHilite for highlighting syntax in code blocks
  • Permalinks for linking to subsections of the doc

If you wish to add an extension, head to the Extensions section in the Material for MkDocs documentation to see which are available.

Plugins#

We've also enabled some plugins in the mkdocs.yml file, notably:

  • Search for searching through your doc using lunr.js
  • Revision date for outputting the git revision date of the corresponding markdown file at the bottom of the page (have a peek below to see it in action)

If you wish to add a plugin, head to the Plugins section in the Material for MkDocs documentation to see which are available.