Skip to content

Quickstart guide

This page provides a guide on how to configure the MkDocs Tech Docs Template. In a few simple steps, you can begin building your documentation site.

Before you begin

In order to use the MkDocs Tech Docs Template, you require the following:

  • a device with permissions to install new packages
  • Python 3 and Pip installed on your device
  • a remote repository to store your documentation, for example on GitHub

You should also be comfortable writing content in Markdown, and using the Git workflow to push your changes to a repository.

Install MkDocs TDT

The MkDocs TDT is a Python package so you use pip to install it. In your terminal, navigate to the directory you want to install the template in and run the following:

pip install mkdocs-tech-docs-template

Next, bootstrap your project documentation:

mkdocs new .

This creates the following structure in the directory:

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

Update mkdocs.yml

So that the template displays properly, copy the following into mkdocs.yml:

repo_url: <your-website-url>
repo_name: <your-repo-name>
theme:
    name: tech_docs_template
plugins:
    - material/search

This sets the theme to use the MkDocs Tech Docs Template and enables the search bar plugin. After copying, insert the relevant values for site_name, repo_url and repo_name.

Preview your documentation

MkDocs includes a live preview server that automatically rebuilds when you save a file, so you can preview your changes as you write. To start the server, in your terminal run:

mkdocs serve

To stop the server, in your terminal press Ctrl+C. If the page stops loading, check your terminal: an error may have occurred you need to fix before you can restart the server.

Build your documentation

If you are using GitHub, you can use GitHub Actions to automate the deployment of your documentation to GitHub Pages whenever someone pushes a commit to the master or main branch. See the Material for MKDocs documentation for more details and alternatives.

Configure page layout

This template is flexible. For examples of how you can structure navigation and table of contents, as well as other customisation options, see Customise.

Last update: September 13, 2023
Created: September 13, 2023