MkDocs

Quick Start

Use Astral uv to handle dependencies:

uv add --dev mkdocs mkdocs-material

Create a mkdocs.yml configuration file:

uv run mkdocs new .

Edit the mkdocs.yml configuration file to customize your site. Use my example as a starting point.

Test the installation:

uv run mkdocs --version

Serve the documentation on localhost:

uv run mkdocs serve --livereload

How to publish in gh-pages?

Manually deploy the site to GitHub Pages:

uv run mkdocs gh-deploy --force

Custom Page

Create folder for override html files:

mkdir -p overrides

Create custom page:

touch overrides/home.html
touch overrides/project.html

Templates

Wiki template

---
sidebar_position: 1
title: Git Fundamentals
id: git-how-to
created: 2025-06-19
updated: 2026-06-19
tags:
  - git
---

<!-- TOC -->

add the content here

<!-- /TOC -->

TODO: overrides

Check the basic example in the my portfolio repo: https://github.com/Cyber-Syntax/cyber-syntax.github.io

Check the advanced example in binbashar's repo: https://github.com/binbashar/le-ref-architecture-doc/blob/master/material/overrides/main.html

Configure mkdocs.yml:

theme:
  custom_dir: overrides

Create md files for each custom page to be able to use custom html templates:

touch index.md
touch portfolio/projects.md
touch portfolio/education.md
touch dev/index.md

Add yaml front matter to each md file to show their own templates:

---
template: education.html
title: Education
---

---
template: projects.html
title: Projects
---

Add nav to mkdocs.yml to define the navigation structure:

nav:
  - Home: "index.md"
  - Projects: "portfolio/projects.md"
  - Education: "portfolio/education.md"
  - Dev: "dev/index.md"