MKDocs Material Template

This is my template for a quick and basic mkdocs with Material setup.

Usage

Install required tools

These instructions should work across Windows and Linux. Alternative methods for installing are availiable, but this guide assumes you have Python installed and present in PATH.

pip install mkdocs
pip install mkdocs-material

Create new project

mkdocs new <projectname>
cd <projectname>

Config options (basic)

All config options are housed in mkdocs.yml within the project folder.

site_name: <Title to display in browser titlebar>
site_url: <final URL where site will be published>
theme:
	name: material

Customisation: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/

Start preview on localhost:8000 using mkdocs serve

Publish to GitHub

• Ensure the project is already hosted on a GitHub repo (remember to push source changes to master/main!)
• Then use mkdocs gh-deploy --force which will initially create a gh-pages branch where your site will be hosted from

Follow the prompts to deploy. If successful, you can view your docs on the web at https://github.!domain/pages/!username/!repoName/.

Where !domain is either .com or your GH Enterprise TLD; !username is your GitHub username & !repoName is the name of the GitHub repo hosting your mkdocs project.

Requires git to be installed.

Need more support?

Theme guide - https://squidfunk.github.io/mkdocs-material/getting-started/

MkDocs guide - https://www.mkdocs.org/getting-started/#adding-pages