# 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

```markdown
# 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`:

```yaml
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](https://squidfunk.github.io/mkdocs-material/)
- [MkDocs Documentation](https://www.mkdocs.org/)
- [Markdown Guide](https://www.markdownguide.org/)