Skip to content
Permalink
master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

mkdocs-template/readme.md

Go to file
 
 
Cannot retrieve contributors at this time
MKDocs Material Template Usage Install required tools Create new project Config options (basic) Publish to GitHub Need more support?
43 lines (33 sloc) 1.55 KB
Raw Blame
Open in GitHub Desktop

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