Skip to content

MkDocs Documentation Site Setup

This template includes a MkDocs documentation site that automatically deploys to GitHub Pages.

Enable GitHub Pages

After your first push to main:

  1. Wait for workflow to complete:

    gh run list --workflow=deploy-docs.yml --limit 1

  2. Configure Pages:

  3. Go to Settings → Pages
  4. Source: "Deploy from a branch"
  5. Branch: gh-pages, Folder: / (root)

  6. Save

  7. Access your site:

  8. https://<username>.github.io/<repo-name>/

Note

GitHub Pages is free for public repos. Private repos require GitHub Pro, Team, or Enterprise.

Customize Your Site

Update Branding

Site name (mkdocs.yml):

site_name: Your Project Name Docs

Logo icon (mkdocs.yml):

theme:
  icon:
    logo: material/robot  # Browse: https://pictogrammers.com/library/mdi/

Colors (docs/stylesheets/extra.css):

:root {
  --md-primary-fg-color:        #5517c0;  /* Main */
  --md-primary-fg-color--light: #8e5ee8;  /* Hover */
  --md-primary-fg-color--dark:  #2d0a70;  /* Active */
  --md-accent-fg-color:         #5517c0;  /* Accent */
}

Add Your Documentation

  1. Create markdown files in docs/

  2. Add to navigation in mkdocs.yml:

    nav:
  - Your Section:
    - Your Doc: your-doc.md

  3. Preview locally:

    uv sync --group docs
uv run mkdocs serve  # http://127.0.0.1:8000

File Structure

docs/
├── README.md              # Home page
├── *.md                   # Guide docs
├── stylesheets/
│   └── extra.css         # Custom theme
└── references/           # Reference docs

GitHub-style alerts work automatically:

Note

Informational callout example

Resources