# MkDocs: генератор документации из Markdown

Индекс LLMS: [llms.txt](/llms.txt)

---

Документация в репозитории устаревает быстрее, чем её читают: ссылки в README ведут в никуда, разделы разбросаны по `docs/`, `wiki/` и confluence, а поиск по сайту не работает. MkDocs решает это предсказуемо — берёт папку с `.md` файлами и собирает статический сайт. Один конфиг, одна команда для прода, привычный Markdown.

## Что такое MkDocs

MkDocs — статический генератор сайта документации на Python. На входе: каталог с Markdown-файлами и YAML-конфиг. На выходе: готовый `site/` с HTML, который отдаётся любым веб-сервером или хостится на GitHub Pages, GitLab Pages, S3. Сам MkDocs ядро рендеринга, а внешний вид и фичи задаёт тема. Стандарт де-факто — [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).

> [!NOTE]
> MkDocs не использует Jinja-шаблоны и не требует базы данных. Это статика, которая собирается локально или в CI за пару секунд.

## Установка

Минимальные требования — Python 3.8+. Ставить лучше в виртуальное окружение, чтобы не засорять системный pip.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install mkdocs
```

Проверка:

```bash
mkdocs --version
```

Типичный вывод — `mkdocs, version 1.6.x`. Версия важна, потому что темы и плагины часто требуют конкретный диапазон.

Полезные пакеты, которые ставятся вместе с базой или отдельно:

| Пакет | Зачем |
| --- | --- |
| `mkdocs-material` | Тема Material, навигация, поиск, tabs |
| `mkdocstrings` | Генерация документации из docstring Python-кода |
| `pymdown-extensions` | Дополнительные расширения Markdown для Material |
| `mkdocs-minify-plugin` | Минификация HTML/CSS/JS в `site/` |

```bash
pip install mkdocs-material mkdocstrings[pymdownx]
```

> [!TIP]
> В `requirements.txt` фиксируйте версии тем и плагинов. Material ломает совместимость между минорными релизами, как и `mkdocstrings`.

## Создание проекта

Команда `mkdocs new` создаёт скелет:

```bash
mkdocs new my-docs
cd my-docs
```

Появится каталог `docs/` с `index.md` и пустой `mkdocs.yml`. Это и есть рабочий минимум — больше ничего обязательного нет.

```bash
tree my-docs
```

```
my-docs
├── docs
│   └── index.md
└── mkdocs.yml
```

## Структура каталогов

`docs/` — единственный источник Markdown. Иерархия каталогов напрямую превращается в URL. Файл `docs/guide/install.md` становится `/guide/install/`. Файл `index.md` в корне `docs/` — главная страница.

```
docs/
├── index.md
├── guide/
│   ├── install.md
│   └── config.md
├── reference/
│   └── cli.md
└── about.md
```

Сайт собирается в каталог `site/` рядом с `mkdocs.yml`. Этот каталог — артефакт сборки, его коммитят только при ручном деплое, обычно его собирает CI.

## Конфигурация mkdocs.yml

Минимальный рабочий конфиг:

```yaml
site_name: My Project Docs
site_url: https://example.com/docs/
docs_dir: docs
site_dir: site

theme:
  name: material
```

Полный набор ключей, которые реально используются в продакшене:

| Ключ | Назначение |
| --- | --- |
| `site_name` | Заголовок сайта и `<title>` по умолчанию |
| `site_url` | Канонический URL, нужен для `sitemap.xml` и `robots.txt` |
| `site_description` | Описание, попадает в мета-теги |
| `docs_dir` | Каталог с Markdown, по умолчанию `docs` |
| `site_dir` | Куда собирать HTML, по умолчанию `site` |
| `theme` | Тема и её параметры |
| `nav` | Явная навигация, перекрывает авто-сборку |
| `plugins` | Плагины в порядке загрузки |
| `markdown_extensions` | Включённые расширения Markdown |
| `extra` | Произвольные переменные, читаются темой |

Пример с навигацией, расширениями и плагинами:

```yaml
site_name: Service Docs
site_url: https://docs.example.com/
repo_url: https://github.com/example/service

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight
    - content.code.copy
  palette:
    - scheme: default
      toggle:
        icon: material/brightness-7
        name: Тёмная тема
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Светлая тема

nav:
  - Главная: index.md
  - Руководство:
      - Установка: guide/install.md
      - Настройка: guide/config.md
  - Справка:
      - CLI: reference/cli.md

markdown_extensions:
  - admonition
  - tables
  - toc:
      permalink: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

plugins:
  - search
```

> [!WARNING]
> Включайте `search` явно, если используете список `plugins`. В новых версиях Material он не подтягивается автоматически из темы.

## Наполнение контентом

Markdown-файлы — обычный CommonMark с расширениями. Полезные конструкции, которые работают «из коробки» при включённых расширениях из примера выше.

Admonitions:

```markdown
> [!NOTE]
> Краткое пояснение для читателя.

> [!WARNING]
> Действие может привести к потере данных.
```

Табы с `pymdownx.tabbed`:

````markdown
=== "Linux"

    ```bash
    sudo apt install foo
    ```

=== "macOS"

    ```bash
    brew install foo
    ```
````

Подсветка кода с указанием языка:

````markdown
```python
from mkdocs import config
print(config.DEFAULT_SCHEMA.keys())
```
````

> [!TIP]
> Используйте якоря в заголовках, чтобы ссылаться между страницами. Material рендерит иконку `#` рядом с заголовком при `toc.permalink: true`.

Внутренние ссылки — относительные пути от текущего файла:

```markdown
Подробнее в [разделе про настройку](config.md).
```

Внешние ссылки по умолчанию открываются в той же вкладке. Чтобы открывать в новой:

```markdown
[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/){target=_blank}
```

## Сборка и локальный сервер

Локальная разработка — запуск live-сервера:

```bash
mkdocs serve
```

По умолчанию слушает `http://127.0.0.1:8000`. Полезные флаги:

| Флаг | Эффект |
| --- | --- |
| `--dev-addr 0.0.0.0:9000` | Сменить адрес и порт, удобно в контейнере |
| `--strict` | Сборка падает на любом warning, включая битые ссылки |
| `--livereload` | Перезагрузка страницы в браузере без F5 (по умолчанию включён) |
| `--no-livereload` | Отключить автообновление |
| `--clean` | Удалить `site/` перед сборкой |

Сборка артефакта для деплоя:

```bash
mkdocs build --clean --strict
```

`--strict` — обязателен в CI, иначе опечатки в ссылках и отсутствующие файлы в `nav` будут молча собираться. Код возврата при warning — ноль, поэтому без `--strict` пайплайн пройдёт зелёным с битой документацией.

> [!WARNING]
> Не запускайте `mkdocs serve` в проде. Это dev-сервер без аутентификации и с включённой перезагрузкой файлов.

Типовые ошибки при первом запуске:

- `WARNING - A relative path to '...' is included in the 'nav' config`. Файл указан в `nav`, но отсутствует в `docs/`. Проверьте регистр и путь.
- `WARNING - Documentation file 'x.md' is not included in the 'nav' configuration`. Файл есть, но в навигацию не добавлен. Либо добавьте в `nav`, либо положитесь на авто-навигацию, убрав секцию `nav` целиком.
- `ERROR - Config value 'theme': The theme 'mkdocs' is not installed`. Не установлен пакет темы, либо опечатка в имени.

## Material for MkDocs: навигация, поиск, tabs

Material расширяет базовый MkDocs тремя вещами, которые нужны почти всегда.

**Навигация.** Включается через `features` в секции `theme`:

```yaml
theme:
  name: material
  features:
    - navigation.tabs          # верхние табы первого уровня
    - navigation.sections      # табы приклеиваются при скролле
    - navigation.top           # кнопка «наверх»
    - navigation.indexes       # index.md превращается в секцию
    - navigation.tracking      # якорь в URL при переходе
    - toc.follow               # правое оглавление скроллится за текстом
```

> [!TIP]
> Связка `navigation.tabs` + `navigation.sections` даёт привычное «приклеенное» меню. Без `sections` табы уезжают вверх вместе с контентом.

**Поиск.** Плагин `search` идёт в составе Material, но регистрируется отдельно:

```yaml
plugins:
  - search:
      separator: '[\s\-\.\_]+'
```

Для русской документации важно включить стемминг — `search.lang: ru` в конфиге `theme`. Список поддерживаемых языков Material публикует в документации, новые добавляются регулярно.

**Tabs внутри страницы.** Делаются расширением `pymdownx.tabbed`, которое уже подключено выше. Альтернативный синтаксис через `!!! example` блоки в некоторых темах не работает — это частая причина «почему табы не отрисовываются».

**Подсветка кода и копирование.** Кнопка «скопировать» включается фичей `content.code.copy`. Номера строк — расширением `pymdownx.highlight` с `linenums: true` либо глобально через `markdown_extensions`:

```yaml
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
```

> [!WARNING]
> `pymdownx.superfences` нужен для подсветки внутри admonitions и tabbed-блоков. Без него код рендерится как обычный блок без подсветки.

Тёмная тема — обязательная опция для документации, которую читают ночью по алертам. В примере конфига выше переключатель настроен через `palette` с двумя схемами: `default` и `slate`. Чтобы Material отдавал правильную схему при первом заходе, добавьте в `<head>` пользовательский скрипт или используйте `theme.palette.toggle` с `media` — это работает без JS и учитывает системные настройки пользователя.