Skip to content

MkDocs Material

Modern documentation site generator with live preview.

Overview

MkDocs Material is a powerful documentation framework built on top of MkDocs, providing a beautiful Material Design theme and advanced features for creating professional documentation sites.

Features

  • Material Design theme
  • Live preview during development
  • Search functionality
  • Navigation and organization
  • Code syntax highlighting
  • Mathematical expressions support
  • Responsive design
  • Customizable themes and colors

Access

  • Development Port: 4000
  • Development URL: http://localhost:4000
  • Live Reload: Automatically refreshes on file changes

Configuration

Main Configuration

Configuration is managed through mkdocs.yml in the project root.

Volumes

  • ./mkdocs: Documentation source files
  • ./assets/images: Shared images directory

Environment Variables

  • SITE_URL: Base domain for the site
  • USER_ID: User ID for file permissions
  • GROUP_ID: Group ID for file permissions

Directory Structure

mkdocs/
├── mkdocs.yml          # Configuration file
├── docs/               # Documentation source
│   ├── index.md       # Homepage
│   ├── services/      # Service documentation
│   ├── blog/          # Blog posts
│   └── overrides/     # Template overrides
└── site/              # Built static site

Writing Documentation

Markdown Basics

  • Use standard Markdown syntax
  • Support for tables, code blocks, and links
  • Mathematical expressions with MathJax
  • Admonitions for notes and warnings

Example Page

# Page Title

This is a sample documentation page.

## Section

Content goes here with **bold** and *italic* text.

### Code Example

```python
def hello_world():
    print("Hello, World!")

Note

This is an informational note.

## Building and Deployment

### Development

The development server runs automatically with live reload.

### Building Static Site

```bash
docker exec mkdocs-changemaker mkdocs build

The built site will be available in the mkdocs/site/ directory.

Customization

Themes and Colors

Customize appearance in mkdocs.yml:

theme:
  name: material
  palette:
    primary: blue
    accent: indigo

Custom CSS

Add custom styles in docs/stylesheets/extra.css.

Official Documentation

For comprehensive MkDocs Material documentation: - MkDocs Material - MkDocs Documentation - Markdown Guide