Skip to content
Login Changemaker Archive. Learn more

# 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