Setting Up a MkDocs Project from Scratch¶

This guide walks you through installing MkDocs and its dependencies, creating a new project, and building your documentation.

1. Install Required Packages¶

Ensure Python3, pip, and the virtual environment module are installed:

sudo apt install python3 python3-pip python3-venv -y

Install MkDocs, the Material theme, and required extensions:

pip install mkdocs mkdocs-material pymdown-extensions mkdocs-material-extensions

Note: Some systems also offer MkDocs via apt:

sudo apt install mkdocs -y

2. Create a New MkDocs Project¶

Create a new project directory (replace my-mkdocs-project with your project name).
If you run into permission issues, ensure the directory is writable or run as a user with proper privileges.

mkdocs new my-mkdocs-project

This creates a mkdocs.yml file and a default docs/ directory with an index.md.

3. Customize Your MkDocs Configuration¶

Edit mkdocs.yml to suit your needs. For example, you might use the Material theme:

site_name: BT Docs

theme:
  name: material
  custom_dir: overrides
  logo: BT-PROUD-face.png
  favicon: BT-PROUD-face.png

plugins:
  - search:
      indexing: 'full'

extra:
  generator: false

You can further adjust navigation, markdown extensions, and plugins as needed.

4. Build Your Documentation¶

To build your site:

mkdocs build

This generates a static site in the site/ directory.

5. Run Your Documentation¶

To make it available on all devices on your network then you can run

mkdocs serve -a 0.0.0.0:8000

Then open http://<host-ip>:8000 in your browser.

(Less likely to be applicable) To preview locally (given that you are using the internet on that machine or on a browser on the host machine):

mkdocs serve

Then open http://127.0.0.1:8000 in your browser.