MKDocs Material Template
This is my template for a quick and basic mkdocs with Material setup.
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
Start preview on localhost:8000 using
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 --forcewhich 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.
git to be installed.
Need more support?
MkDocs guide - https://www.mkdocs.org/getting-started/#adding-pages