Как мы подняли современный портал документации из россыпи .md файлов: пошаговое руководство по MkDocs + Material
От хаоса в Markdown-файлах до стильного, быстрого сайта с поиском, темами и мультиязычностью за один вечер.
В жизни почти каждого IT-проекта наступает момент, когда количество файлов README.md
, GUIDE.md
, docs.txt
и заметок в Confluence достигает критической массы. Документация становится фрагментированной, поиск нужной информации превращается в квест, а новые члены команды тратят часы на то, чтобы просто понять, «что где лежит».
Мы в проекте Peakline (наш сервис для продвинутой аналитики тренировок на Strava) столкнулись ровно с такой же проблемой. Решением, которое превзошло все наши ожидания по скорости и качеству результата, стала связка MkDocs и темы Material for MkDocs.

В этой статье мы не будем пересказывать официальную документацию. Вместо этого мы покажем вам весь наш путь от А до Я: от установки на «голый» сервер до финального развертывания. Мы честно расскажем о всех граблях, на которые наступили, и поделимся готовыми конфигами, которые вы сможете адаптировать для своих проектов.
1. Почему именно MkDocs, а не Docusaurus или VitePress?
Наш стек в основном на Python, поэтому выбор инструмента, написанного на том же языке, был для нас естественным. Но даже если вы не пишете на Python, у MkDocs есть несколько неоспоримых преимуществ:
-
Феноменальная простота: Вы просто пишете текст в формате Markdown. Никаких JSX-компонентов, сложных структур или долгой компиляции. Это позволяет сосредоточиться на контенте, а не на инструменте.
-
Скорость: MkDocs генерирует набор статических HTML, CSS и JS файлов. Такой сайт не требует сложного бэкенда, летает даже на самом простом хостинге и отлично кэшируется.
-
Мощнейшая тема «из коробки»: Честно говоря, основной причиной выбора стала тема Material for MkDocs. Это не просто «скин», а целый фреймворк поверх MkDocs, который дает:
-
Современный, чистый дизайн (абсолютно в трендах 2025 года).
-
Идеальную адаптивность для мобильных устройств.
-
Встроенный поиск, который просто работает.
-
Переключение между светлой и темной темой.
-
Простую настройку мультиязычности.
-
Огромное количество готовых UI-компонентов: блоки с подсказками, табы, красивые таблицы, подсветка синтаксиса и многое другое.
-
2. Установка: Первые грабли и боль с venv
Казалось бы, что может быть проще, чем pip install
? Но тут нас ждал первый сюрприз.
Попытка №1 (неудачная):
Мы, как и многие, начали с простой команды: pip install mkdocs mkdocs-material pymdown-extensions
. И тут же получили ошибку error: externally-managed-environment
.
Что это значит? Современные дистрибутивы Linux (в нашем случае Debian) защищают системный Python от изменений через pip
. Это сделано для того, чтобы вы случайно не сломали системные утилиты, которые зависят от определенных версий пакетов.
Правильное решение — виртуальное окружение:
Изоляция зависимостей — это святое правило хорошего тона в Python.
-
Создаем виртуальное окружение в папке нашего проекта:
python3 -m venv venv_docs
Мы назвали его
venv_docs
, чтобы не путать сvenv
от основного приложения. -
Активируем его (для интерактивной работы):
source venv_docs/bin/activate
После этого в начале строки терминала появится
(venv_docs)
. -
Устанавливаем пакеты уже в «чистое» окружение:
pip install mkdocs mkdocs-material pymdown-extensions
Теперь все пакеты установлены в папку
venv_docs
и не затрагивают систему.
Лайфхак для скриптов: При запуске команд в скриптах или CI/CD активация окружения не всегда удобна. Можно вызывать исполняемые файлы напрямую: ./venv_docs/bin/python
или ./venv_docs/bin/mkdocs
.
3. Создание и настройка проекта
-
Инициализация: Одна простая команда создает всю базовую структуру.
# Убедитесь, что вы находитесь в корне проекта, а не в venv_docs! ./venv_docs/bin/mkdocs new docs
Она создаст папку
docs
с конфигомmkdocs.yml
и одним файломindex.md
. -
Сердце проекта:
mkdocs.yml
: Это главный файл, где происходит вся магия. Вот наш финальный конфиг с комментариями:# Название сайта, отображается в шапке site_name: Peakline Docs # Описание для мета-тегов SEO site_description: 'Документация для проекта Peakline' # Настройка темы theme: name: material # Указываем, что используем Material # Включаем крутые фичи темы features: - navigation.tabs # Навигация в виде табов - navigation.sections # Секции в навигации - toc.integrate # Интегрировать оглавление страницы в навигацию - search.suggest # Подсказки при поиске - content.code.copy # Кнопка "копировать" для блоков кода # Настраиваем палитру и переключатель тем palette: - scheme: default # Светлая тема primary: 'indigo' accent: 'indigo' toggle: icon: material/brightness-7 name: Переключиться на темную тему - scheme: slate # Темная тема primary: 'indigo' accent: 'indigo' toggle: icon: material/brightness-4 name: Переключиться на светлую тему # Секция для мультиязычности extra: alternate: - name: English # Название в переключателе link: /en/ # Ссылка на английскую версию lang: en # Код языка - name: Русский link: ./ # Ссылка на текущую (русскую) версию lang: ru # Наша навигация по сайту nav: - 'Главная': 'index.md' - 'Начало работы': - 'Первые шаги': 'getting-started/first-steps.md' - 'Наша философия данных': 'getting-started/data-philosophy.md' - 'Ключевые возможности': - 'Анализ сегментов': 'core-features/segment-analysis.md' # ... и так далее # Расширения для Markdown markdown_extensions: - admonition # Блоки !!! note, !!! warning - pymdownx.details # Сворачиваемые блоки - pymdownx.superfences # Вложенные блоки кода - pymdownx.tabbed: # Табы alternate_style: true
4. Магия Material: Мультиязычность без боли
Это одна из самых крутых фич. Чтобы добавить поддержку второго языка, нам понадобилось всего лишь добавить блок extra.alternate
(показан в конфиге выше) и создать новую структуру папок.
MkDocs, видя эту конфигурацию, теперь понимает, что:
-
Контент по умолчанию (русский) лежит в
docs/
. -
Контент для языка
en
должен лежать вdocs/en/
.
Мы просто скопировали все наши .md
файлы из docs/
в docs/en/
и отдали их на перевод. Всё! Переключатель языков появился на сайте автоматически.
5. Развертывание: от локалхоста до продакшена на Nginx
Итак, у нас есть работающий сайт на локальной машине (mkdocs serve
). Как теперь выкатить его в мир?
Шаг 1: Сборка статики
Запускаем команду сборки:
./venv_docs/bin/mkdocs build --clean
Опция --clean
удаляет старые файлы перед сборкой, что помогает избежать проблем. Вся статика нашего сайта (HTML, CSS, JS, картинки) теперь лежит в папке /site
внутри нашей папки docs
.
Шаг 2: Настройка веб-сервера Nginx
На нашем сервере мы используем Nginx. Вот базовый конфиг, который мы создали в /etc/nginx/sites-available/
docs.thepeakline.com
:
server {
listen 80;
listen [::]:80;
# !!! ВАЖНО: Указываем полный путь к папке с собранной статикой
root /opt/strava-web/docs/site;
index index.html;
server_name docs.thepeakline.com;
location / {
# Стандартный блок для статических сайтов.
# Если файл не найден, Nginx вернет 404.
try_files $uri $uri/ =404;
}
}
Подводный камень №2: Ошибка 404 Not Found. Сначала мы по ошибке оставили в конфиге путь-заглушку вроде /var/www/html
. Nginx работал, но не мог найти файлы. Ключевой момент — директива root
должна указывать на папку site
, а не на docs
.
Шаг 3: HTTPS с помощью Certbot (обязательно!)
В 2025 году сайт без HTTPS — это дурной тон. К счастью, с Certbot это делается одной командой:
# Устанавливаем Certbot и плагин для Nginx
sudo apt install certbot python3-certbot-nginx -y
# Запускаем его для нашего домена
sudo certbot --nginx -d docs.thepeakline.com
Certbot сам найдет наш конфиг, получит SSL-сертификат, установит его и даже предложит настроить редирект с HTTP на HTTPS (настоятельно рекомендуем согласиться).
Ша-г 4: Финальные команды
После того как конфиг готов и сертификат получен, осталось только «включить» наш сайт и перезагрузить Nginx:
# Создаем символическую ссылку, чтобы "активировать" конфиг
sudo ln -s /etc/nginx/sites-available/docs.thepeakline.com /etc/nginx/sites-enabled/
# Проверяем, что в конфигах нет ошибок
sudo nginx -t
# Перезагружаем Nginx, чтобы применить все изменения
sudo systemctl reload nginx
Готово! Наша документация в сети.
Заключение
Переход на MkDocs стал для нас настоящим глотком свежего воздуха. Мы не только навели порядок в документации, но и получили современный, быстрый и удобный для пользователей портал, на создание которого ушло всего пара вечеров. Если вы все еще храните документацию в разрозненных файлах, очень рекомендуем попробовать этот подход.
А посмотреть, что у нас получилось в итоге, можно здесь: docs.thepeakline.com
Автор: cyberscoper