От хаоса в 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.

1. Создаем виртуальное окружение в папке нашего проекта:

   python3 -m venv venv_docs

   Мы назвали его venv_docs, чтобы не путать с venv от основного приложения.

2. Активируем его (для интерактивной работы):

   source venv_docs/bin/activate

   После этого в начале строки терминала появится (venv_docs).

3. Устанавливаем пакеты уже в "чистое" окружение:

   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