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:

2.6 KiB Raw Blame History