Автоматизация документации: MkDocs Material + GitLab CI/CD + Битрикс / forpes.ru

Главная
Автоматизация документации: MkDocs Material + GitLab CI/CD + Битрикс

Автоматизация документации: MkDocs Material + GitLab CI/CD + Битрикс +3

07.07.2025 05:15

Olga-Gazizova 0 693 Источник

Всем привет! В процессе обновления инфраструктуры сопровождения наших программных решений мы получили интересный опыт, которым хотим поделиться. Эта статья не просто пошаговая инструкция, а практический разбор того, как мы выстроили процесс подготовки технической документации на основе MkDocs Material, автоматизировали его через GitLab CI/CD и встроили полученный результат в сайт на Битрикс. Наш опыт окажется полезным тем, кто хочет навести порядок в документации и сделать её частью полноценного dev-процесса.

Предисловие

Наша компания сопровождает несколько интернет‑магазинов на платформе Битрикс, каждый из которых включает собственную линейку программных решений. По всем продуктам необходимо составлять и публиковать актуальную документацию. Ситуация усложнилась после того, как мы перевели наши продукты в OpenSource и выложили их в публичные репозитории GitLab. Теперь документация должна быть актуальна и синхронизирована как на сайте магазина, так и в репозиториях.

Перед нами возникла проблема: как автоматизировать работу с документацией?

Мы начали с определения ключевых требований:

Адаптивный веб‑сайт, автоматически генерируемый из текстовых файлов;
Версионный и открытый исходный код в репозитории GitLab;
Возможность публиковать контент разного формата: от статей о продуктах до постов в блоге и справочных руководств;
Развертывание и размещение, желательно бесплатное, с возможностью непрерывного обновления в автоматическом режиме через CI/CD;
Динамический контент во время сборки для оперативного изменения дизайна статического сайта;
Возможность встраивания цифровых ассистентов с использованием технологий искусственного интеллекта;
Перспектива автоматизированного тестирования.

После анализа доступных решений, остановились на MkDocs — генераторе статических сайтов, разработанном специально для документации и использующем разметку Markdown.

Конечно, не обошлось без рассмотрения альтернатив:

Sphinx — это популярный инструмент для создания документации, особенно для проектов на Python. Однако, как и любое другое решение, он имеет свои недостатки. Sphinx использует язык reStructuredText, который является менее интуитивным по сравнению с Markdown. Sphinx не предоставляет встроенных функций для редактирования документации в реальном времени, что затрудняет совместную работу. И он требует больше настроек, что сопровождается большей сложностью в переопределении шаблонов.
Docusaurus — это статический генератор сайтов, предназначенный для упрощения создания, развертывания и ведения документации и веб‑сайтов. Docusaurus показался избыточным для наших задач. Он требует больше усилий для первоначальной настройки, особенно если вы не знакомы с React. Конфигурация может быть более сложной из‑за множества доступных опций.

Еще нам довелось поработать с Gatsby, но на момент его использования этот генератор статических сайтов выдавал слишком упрощенный сайт по сравнению с возможностями MkDocs.

MkDocs показался лучшим вариантом: прост в настройке и использовании, поддерживает адаптивный дизайн и имеет множество тем, интегрируется с GitLab CI/CD для автоматической сборки и публикации документации, а также позволяет расширять функциональность с помощью плагинов. Кроме того, шаблон MkDocs Material предоставляет массу возможностей быстрой организации сайта документации.

Как установить и настроить MkDocs

Следует отметить, что MkDocs написан на Python и в нем используется язык шаблонов Jinja2, который позволяет создавать динамически генерируемые HTML‑страницы с простой и понятной разметкой. В MkDocs шаблоны Jinja2 используются для генерации HTML‑страниц из файлов Markdown. Когда запускается команда mkdocs build, MkDocs обрабатывает Markdown‑файлы, применяет к ним шаблоны Jinja2 и создает статические HTML‑страницы, которые затем можно развернуть на веб‑сервере.

Для тех, кто знаком с Python и менеджерами пакетов, установка MkDocs не представляет сложностей. Вот основные шаги для запуска сервера и генерации статического сайта:

Шаг 1: Подготовка окружения

Для MkDocs требуется последняя версия Python и менеджер пакетов PIP. Убедимся, что у нас есть все необходимое. Откройте командную строку (терминал) и введите:

python --version

Должна отобразиться версия Python. Если команда не работает, потребуется установить Python. Скачайте его с официального сайта. Во время установки не забудьте установить флажок «Add python.exe to PATH» (обычно по умолчанию он не активен). Если у вас установлен Python, убедитесь, что PIP обновлен до последней версии. Для его обновления воспользуйтесь командой:

pip install --upgrade pip

Шаг 2: Установка MkDocs

Для установки MkDocs выполните команду:

pip install mkdocs

После этого проверьте успешность установки с помощью команды:

mkdocs --version

Шаг 3: Создание нового проекта

Для создания нового проекта MkDocs выполните команду:

mkdocs new my-project

где my-project — это имя директории проекта.

Эта команда создаст следующую структуру файлов:

.
├─ docs/
│  └─ index.md # Домашняя страница по умолчанию
└─ mkdocs.yml # Основные настройки вашего проекта

Перейдите в созданную директорию с помощью команды:

cd my-project

Шаг 4: Запуск локального сервера

MkDocs содержит встроенный сервер разработки. С помощью этого сервера можно просматривать документацию во время работы над ней.

Запустите сервер по команде:

mkdocs serve

Теперь можно открыть http://127.0.0.1:8000 в браузере и увидеть заготовку документации:

Шаг 5: Минимальная конфигурация

Файл mkdocs.yml содержит основные настройки вашего проекта.

Откройте файл в редакторе:

site_name: Документация

Пока что в файле есть только один параметр site_name, который задает название сайта. Задайте свое название и сохраните файл. После сохранения страница в браузере перезагрузится и отобразится новое название.

Пример со структурой нашего конфигурационного файла

site_name: Документация # Отображаемое название сайта (в шапке и title)
site_url: https://trusted.ru/documentation/ # Базовый URL сайта
site_author: digtlab.ru  # Имя автора сайта (добавляется в метатег <meta name="author">)
theme:
  name: material # Используется тема MkDocs Material
  custom_dir: overrides # Кастомные шаблоны/стили в папке `overrides`
  features: # Активированные фичи темы:
    - announce.dismiss  # Закрываемые уведомления
    - content.code.annotate  # Аннотации к коду
    - content.code.copy  # Кнопка копирования кода
    - navigation.tracking  # Отслеживание активного раздела
    - navigation.indexes  # Индексирование навигации
    - navigation.sections  # Группировка разделов
    - search.highlight  # Подсветка результатов поиска
    - search.share  # Кнопка поделиться поиском
    - search.suggest  # Подсказки при поиске
    - toc.follow  # Автопрокрутка оглавления
    - toc.integrate  # Интеграция с навигацией
  font:  # Шрифты
    text: PT sans # Основной шрифт
    code: PT Mono # Моноширинный для кода
  logo: assets/crypto.png # Логотип в шапке
  favicon: assets/crypto.png # Иконка вкладки браузера
  language: ru # Локализация интерфейса
plugins: # Установленные плагины MkDocs
  - search:  # Встроенный поиск
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'  # Правила разбиения слов
  - minify:  # Минификация HTML
      minify_html: true  # Включено
hooks: # Хуки
  - overrides/hooks/translations.py
extra: # Дополнительная конфигурация
  generator: false
  status:  # Кастомные статусы для страниц
    new: Recently added
    deprecated: Deprecated
extra_css:
  - stylesheets/extra.css  # Дополнительные CSS-стили
watch:  # Папки для отслеживания изменений при `mkdocs serve`
  - docs
  - overrides
  - mkdocs.yml
markdown_extensions: # Список расширений для парсера Markdown, которые добавляют новые возможности к стандартному синтаксису Markdown
  - abbr  # Сокращения (HTML <abbr>)
  - admonition  # Блоки-уведомления (!!! note)
  - attr_list  # Атрибуты HTML ({: .class })
  - def_list  # Списки определений (<dl>)
  - footnotes  # Сноски ([^1])
  - md_in_html  # Markdown внутри HTML-блоков
  - toc:  # Оглавление
      toc_depth: "1-1"  # Уровни заголовков (только h1)
      permalink: true  # Якорные ссылки
      slugify: !!python/name:pymdownx.slugs.uslugify # Алгоритм генерации якорей для заголовков
  - pymdownx.arithmatex:  # Поддержка LaTeX
      generic: true  # Совместимость с MathJax/Katex
  - pymdownx.betterem:  # Умное выделение (**bold**, _italic_)
      smart_enable: all
  - pymdownx.caret # Вставка символов (^sup^)
  - pymdownx.details  # Сворачиваемые блоки (<details>)
  - pymdownx.emoji:  # Эмодзи
      emoji_generator: !!python/name:material.extensions.emoji.to_svg  # SVG-генератор
      emoji_index: !!python/name:material.extensions.emoji.twemoji  # Библиотека Twemoji
  - pymdownx.highlight:  # Подсветка кода
      anchor_linenums: true  # Якоря для строк
      line_spans: __span  # CSS-классы для строк
      pygments_lang_class: true  # Классы языков
  - pymdownx.inlinehilite  # Подсветка в строке (`code`)
  - pymdownx.keys  # Клавиши (++ctrl+alt+del++)
  - pymdownx.mark  #==Выделение текста==
  - pymdownx.smartsymbols  # Поддержка (c) → ©, (tm) → ™
  - pymdownx.snippets:  # Вставка указанных файлов в конец каждой страницы
      auto_append:
        - includes/mkdocs.md  # Путь относительно папки `docs/`
  - pymdownx.superfences:  # Расширенные блоки кода
      custom_fences:
        - name: mermaid  # Диаграммы Mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:  # Вкладки
      alternate_style: true  # Альтернативный стиль
      combine_header_slug: true  # Генерация slug для заголовков
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:  # Чекбоксы
      custom_checkbox: true  # Кастомные CSS-классы
  - pymdownx.tilde  # ~~Зачеркивание~~
nav: # Структура сайта
…

Подробнее про конфигурацию файла mkdocs.yml читайте на сайте разработчика.

Шаг 6: Добавление контента

Содержимое документации размещается в директории docs/.

По умолчанию папка docs/ содержит один файл с домашней страницей index.md. Добавьте свои файлы в формате markdown (.md) в эту директорию.

.
├─ docs/
│  └─ index.md
│  └─instructions.md
│  └─setup.md
└─ mkdocs.yml

Откройте браузер и убедитесь, что добавленные файлы отобразились на сайте.

По умолчанию MkDocs автоматически формирует структуру сайта из всех файлов каталога docs в алфавитном порядке. Порядок сортировки можно настроить в mkdocs.yml с помощью параметра nav:

site_name: Документация
nav:
  - index.md
  - setup.md
  - instructions.md

Теперь на сайте изменилась очередность страниц:

Стоит отметить, что MkDocs поддерживает переопределение заголовков, а также многоуровневую навигацию.

Например:

site_name: Документация
nav:
  - Главная: index.md
  - Установка и настройка:
    - Установка: setup/setup.md
    - Настройка: setup/settings.md
  - Инструкции: instructions.md

Как это выглядит на сайте:

Шаг 7: Построение статического сайта

Когда вы будете готовы к публикации, постройте статический сайт, выполнив команду:

mkdocs build

Результат сохранится в папке site. Эти файлы можно разместить на любом веб-сервере.

Шаблон MkDocs Material и его особенности

MkDocs включает несколько встроенных тем mkdocs и readthedocs, помимо которых существуют сторонние темы, разработанные независимыми командами. Вот полный список тем, которые можно установить с помощью pip.

Пожалуй, самым известной и популярной является тема MkDocs Material, именно ее мы и взяли за основу своего портала документации.

Тема включает адаптивный дизайн, множество функций, таких как навигация по страницам, встроенные поисковые функции и возможность добавления пользовательских элементов. Полный список плагинов и расширений темы, которые мы используем, приведен в примере со структурой нашего конфигурационного файла.

Для установки темы MkDocs Material выполните команду:

pip install mkdocs-material

Чтобы применить тему, добавьте в конфигурационный файл mkdocs.yml:

theme: material

Инфраструктура создания и размещения документации (GitLab→MkDocs→Битрикс)

Процесс подготовки и публикации документации выстроен как единая цепочка и охватывает все этапы: от создания текста до его размещения на сайте Битрикс.

Как выглядит схема процесса:

Cхема создания и размещения документации

Для каждого продукта мы разрабатываем документацию в формате Markdown, а затем размещаем ее в ветке docs/ репозитория продукта. После прохождения всех проверок и согласований, изменения вливаются в основную ветку, откуда и начинается процесс автоматической сборки.

Примеры документации:

После публикации изменений в GitLab запускается процесс переноса документации в репозиторий с предварительно настроенной платформой MkDocs Material. Под «преднастройкой» понимается то, что платформа уже нацелена на генерацию статического сайта под определенный информационный ресурс, там имеются все необходимые доработки по стартовым страницам и стилям. Остается только разместить документацию в каталог docs/ и обновить структуру навигации в файле mkdocs.yml. На выходе получается единый статический сайт со всей документацией, готовой к публикации.

Собранные HTML-страницы проходят обработку, при которой автоматически оборачиваются в PHP-шаблоны с хедерами и футерами сайта Битрикс. После преобразования готовые файлы публикуются на тестовом (dev) или рабочем (prod) сервере в зависимости от ветки GitLab. Подробнее о механизме преобразования и настройке шаблонов расскажем ниже.

Проблемы и решения

1. Кастомизация шаблона MkDocs Material

Создавая собственный сайт, вы неизбежно столкнетесь с необходимостью кастомизации MkDocs Material. Например, вы захотите разместить собственное меню в шапке или сделать футер более информативным. Такая возможность есть и это не так сложно, как может показаться. Давайте разберемся, как это сделать на примере изменения шаблонов header и main.

На портале с документацией нам требовалось перенести строку поиска из заголовка страницы в левую часть над меню с навигацией. Поскольку в правом верхнем углу уже находился стандартный поиск сайта от Битрикс, который мы решили оставить.

Для этого в структуре каталогов шаблона MkDocs Material мы создали каталог overrides. В этом каталоге разместили скрипт main.html и подкаталог partials со скриптом header.html.

.
├── docs/                       # Основная директория с документацией
├── overrides/                  # Кастомные шаблоны и стили
│   ├── partials/               # Переопределенные части шаблонов
│   │   └── header.html         # Кастомный header
│   └── main.html               # Основной шаблон
...

Как написать код для скриптов?

Все очень просто. Мы скачали cкрипты из репозитория c исходными кодами темы, а затем внесли правки.

Вот изменения в файле header.html

{% set class = "md-header" %}
{% if "navigation.tabs.sticky" in features %}
  {% set class = class ~ " md-header--shadow md-header--lifted" %}
{% elif "navigation.tabs" not in features %}
  {% set class = class ~ " md-header--shadow" %}
{% endif %}
<header class="{{ class }}" data-md-component="header">
  <nav class="md-header__inner md-grid" aria-label="{{ lang.t("header") }}">
    <a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
       title="{{ config.site_name | e }}"
       class="md-header__button md-logo"
       aria-label="{{ config.site_name }}"
       data-md-component="logo">{% include "partials/logo.html" %}</a>
    <label class="md-header__button md-icon" for="__drawer">
      {% set icon = config.theme.icon.menu or "material/menu" %}
      {% include ".icons/" ~ icon ~ ".svg" %}
    </label>
    <div class="md-header__title" data-md-component="header-title">
      <div class="md-header__ellipsis">
        <div class="md-header__topic">
          <span class="md-ellipsis">{{ config.site_name }}</span>
        </div>
        <div class="md-header__topic" data-md-component="header-topic">
          <span class="md-ellipsis">
            {% if page.meta and page.meta.title %}
              {{ page.meta.title }}
            {% else %}
              {{ page.title }}
            {% endif %}
          </span>
        </div>
      </div>
    </div>
    {% if config.theme.palette %}
      {% if not config.theme.palette is mapping %}
        {% include "partials/palette.html" %}
      {% endif %}
    {% endif %}
    {% if not config.theme.palette is mapping %}
      {% include "partials/javascripts/palette.html" %}
    {% endif %}
    {% if config.extra.alternate %}
      {% include "partials/alternate.html" %}
    {% endif %}
    {% if "material/search" in config.plugins %}
      {% include "partials/search.html" %}
      <label class="md-header__button md-icon" for="__search">
        {% set icon = config.theme.icon.search or "material/magnify" %}
        {% include ".icons/" ~ icon ~ ".svg" %}
      </label>
    {% endif %}
    {% if config.repo_url %}
      <div class="md-header__source">{% include "partials/source.html" %}</div>
    {% endif %}
  </nav>
  {% if "navigation.tabs.sticky" in features %}
    {% if "navigation.tabs" in features %}
      {% include "partials/tabs.html" %}
    {% endif %}
  {% endif %}
</header>

Мы убрали блок, который отвечает за отображение элемента поиска, оставив его для мобильной верстки.

Вот изменения в файле main.html

{% extends "base.html" %}

{% block hero %}
<div class="title_container">
  <h1 class="title_main">Документация</h1>
</div>
{% endblock %}

{% block site_nav %}
<!--{% if not (page.meta and page.meta.hide) %}-->
  <div>
      {% if "material/search" in config.plugins %}
        <header class="md-search-nav" data-md-component="header">
          <!-- <div class="md-flex__cell md-flex__cell--shrink"> -->
          <label class="md-header__button md-icon" for="__search">
            {% set icon = config.theme.icon.search or "material/magnify" %}
            {% include ".icons/" ~ icon ~ ".svg" %}
          </label>
          {% include "partials/search.html" %}
          <!-- </div> -->
        </header>
      {% endif %}
    {{ super() }}
  </div>
<!--{% endif %}  -->
{% endblock %}

{% block container %}
{% if page.url == '' %}
  {{ super() | replace('<div class="md-content" data-md-component="content">', '<div class="md-content is_home" data-md-component="content">') | safe }}
{% else %}
    {{ super() }}
{% endif %}

{% endblock %}
{% block content %}
  {{ super() }}
  <div class="md-breadcrumbs-buttons" role="navigation" aria-label="navigation">
    {%- if page.previous_page and page.next_page %}
      <div class="text nav_button">
        <a href="{{ page.previous_page.url|url }}" class="float-left" title="{{ page.previous_page.title }}">Предыдущая</a>
      </div>
      <div class="text nav_button">
        <a href="{{ page.next_page.url|url }}" class="float-right" title="{{ page.next_page.title }}">Следующая</a>
      </div>
    {%- endif %}
    {%- if page.previous_page and not page.next_page %}
      <div class="text nav_button">
        <a href="{{ page.previous_page.url|url }}" class="float-left" title="{{ page.previous_page.title }}">Предыдущая</a>
      </div>
      <div></div>
    {%- endif %}
    {%- if not page.previous_page and page.next_page %}
      <div></div>
      <div class="text nav_button">
        <a href="{{ page.next_page.url|url }}" class="float-right" title="{{ page.next_page.title }}">Следующая</a>
      </div>
    {%- endif %}
  </div>
{% endblock %}
{% block footer %}{# Отключаем footer #}{% endblock %}

Также мы внесли изменения в реализацию кнопок перемещения по содержанию сайта и отключили footer.

2. Несовместимые якоря страниц в GitLab и MkDocs

При работе с документаций в формате Markdown заголовкам автоматически назначаются якорные ссылки. Ссылки упрощают навигацию внутри документа и позволяют создавать перекрестные ссылки между разными документами .

Оказалось, что GitLab и MkDocs используют разные алгоритмы генерации якорных ссылок, что приводит к поломке ссылок при переходе между системами.

В чем различия?

GitLab приводит заголовок к нижнему регистру, убирает все не буквенно-цифровые символы, заменяет пробелы на дефисы.

Пример:

## Настройка SSL-сертификата  → "настройка-ssl-сертификата"

MkDocs удаляет кириллицу, оставляет только латинские буквы, цифры и дефисы.

Для предыдущего примера MkDocs создаст следующий заголовок:

## Настройка SSL-сертификата  → "#ssl-"

Решение: Для приведения якорей к одному виду мы добавили в файл mkdocs.yml расширение toc с правилом slugify:

markdown_extensions:
  - toc:
      slugify: !!python/name:pymdownx.slugs.uslugify

Интеграция документации в интернет-магазин на Битрикс

Рассмотрим, как интегрировать статический сайт с документацией на MkDocs Material, в интернет-магазин на платформе 1С-Битрикс. В качестве примера используем портал https://trusted.ru/documentation/.

Пример главной страницы статического сайта, созданной по шаблону MkDocs Material:

Портал https://trusted.ru/documentation/

Мы уже рассмотрели проект документации на базе MkDocs Material. Теперь разберемся с его структурой и настройками CI/CD для автоматической сборки и доставки документации в окружение Битрикс.

В GitLab проект организован следующим образом:

.
├── docs/                   # Основная директория с документацией
├── overrides/              # Кастомные шаблоны и стили
├── extra/
│   ├── template.php        # Шаблон для интеграции с Битрикс
│   └── html-to-php.sh      # Скрипт конвертации
...

В папке docs/ размещаются исходные файлы документации в формате Markdown со стилями MkDocs Material. Именно эти файлы используются для сборки статического сайта.

Папка extra/ содержит скрипт html‑to‑php.sh и шаблон template.php, необходимые для интеграции с Битрикс.

Шаблон template.php обеспечивает обертку вокруг каждой HTML‑страницы, добавляя шапку и подвал сайта.

Пример кода template.php

require($_SERVER['DOCUMENT_ROOT'] . '/bitrix/header.php');
$APPLICATION->SetPageProperty("description", "Официальный сайт ООО «Цифровые технологии»");
$APPLICATION->SetPageProperty("title", "Сайт ООО «Цифровые технологии»");
$APPLICATION->SetTitle("Главная"); 
?>
<style>
  label.md-nav__link::before, label.md-nav__link::after {
    display: none!important;
  }
  .content {
    min-height: initial!important;
  }
</style>
<script>
  function resizeHeader() {
    const r = document.querySelector(':root');
    const h1 = $('#header_shop')?.height() || 0;
    const h2 = $('.md-overlay')?.height() || 0;
    const marginTop = Math.abs(h1 - h2 - 3);
    const additionalMarging = 17; //// ????? нужно для sidebar
    r.style.setProperty('--cryptoarm-marging-top', `${marginTop}px`);
    r.style.setProperty('--cryptoarm-marging-top-sidebar', `${marginTop + additionalMarging}px`);
  }
</script>
<div>
  <?php include ('REPLACEME'); ?>
</div>
<script>  
  // resizeHeader();
  $(window).on( "resize", resizeHeader);
</script>
<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>

Скрипт html‑to‑php.sh содержит алгоритм обработки страниц документации, после их преобразования в html. Скрипт создает PHP файлы на основе шаблона из template.php, заменяя в нем строку REPLACEME на имена соответствующих HTML файлов. Каждый новый PHP файл сохраняется в ту же директорию, что и оригинальный HTML файл.

Пример кода html-to-php.sh

#!/bin/bash
template=$(cat template.php)
if [[ -z $template ]]
then
    echo 'template is empty' >&2
    exit 1
fi
find ./../docs -type f -name "*.html" | while read fname; 
do 
    dir=$(dirname -- "$fname")
    filename=$(basename -- "$fname")
    filename_noext="${filename%.*}"
    echo "${template/REPLACEME/$filename}" > "$dir/$filename_noext.php"
done

В результате этой обработки каждая сгенерированная статическая страница дополняется хедером и футером сайта Битрикс и все файлы хранятся в формате PHP с сохранением структуры статического сайта.

В каталоге overrides в проекте, использующем MkDocs Material, размещаются пользовательские файлы и настройки, которые позволяют изменять и настраивать внешний вид и поведение документации. Этот каталог используется для переопределения стандартных стилей, шаблонов и других ресурсов, предоставляемых темой Material для MkDocs. В файле mkdocs.yml конфигурируются основные настройки проекта MkDocs, включая параметры для темы, навигации, расширений и других аспектов.

Процесс сборки документации организован с помощью двухэтапного Dockerfile. На первом этапе мы собираем сайт из исходников, на втором — упаковываем в образ с минималистичным nginx‑сервером.

Пример кода dockerfie

FROM registry.example.ru/mkdocs/mkdocs-material-data:9 as build

ARG CI_COMMIT_BRANCH
ARG CI_JOB_TOKEN
ARG CI_SERVER_HOST
ARG CI_PROJECT_NAMESPACE
ARG CI_PROJECT_NAME

ENV DOCS_PATH /docs
RUN git clone -b ${CI_COMMIT_BRANCH} --single-branch --depth 1 \  https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}.git \
    ${DOCS_PATH}
RUN mkdocs build -f ${DOCS_PATH}/mkdocs.yml -d ${DOCS_PATH}/site
FROM flashspys/nginx-static
COPY --from=build /docs/site /static
EXPOSE 80
STOPSIGNAL SIGTERM
CMD ["nginx", "-g", "daemon off;"]

Конвейер CI/CD состоит из трёх стадий:

build — собирает и сохраняет сайт;
convert — преобразует HTML в PHP с помощью html-to-php.sh;
deploy— выкладывает результат на dev или prod-сервер в зависимости от ветки.

Пример кода gitlab-ci.yml

stages:
  - build
  - convert
  - deploy

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: never
    - when: always

docs_build:
  stage: build
  tags:
    - mkdocs
  before_script:
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
    - export BUILD_VERSION=${CI_COMMIT_BRANCH}-$(date +%Y-%m-%d-%H%M)
    - export LATEST_VERSION=${CI_COMMIT_BRANCH}-latest
    - export DOCS_DIR=$CI_PROJECT_DIR/docs
  script:
    - echo "Building and pushing BUILD_VERSION version for $CI_COMMIT_BRANCH branch"
    - if [ -d "$DOCS_DIR" ]; then rm -Rf $DOCS_DIR; fi
    - >
      docker build 
      --pull 
      --no-cache 
      --tag $CI_REGISTRY_IMAGE:$BUILD_VERSION 
      --build-arg CI_COMMIT_BRANCH=$CI_COMMIT_BRANCH 
      --build-arg CI_JOB_TOKEN=$CI_JOB_TOKEN 
      --build-arg CI_SERVER_HOST=$CI_SERVER_HOST 
      --build-arg CI_PROJECT_NAMESPACE=$CI_PROJECT_NAMESPACE 
      --build-arg CI_PROJECT_NAME=$CI_PROJECT_NAME 
      .
    - docker create --name $BUILD_VERSION $CI_REGISTRY_IMAGE:$BUILD_VERSION
    - docker cp $BUILD_VERSION:/static $DOCS_DIR
    - docker rm -f $BUILD_VERSION
    - docker tag $CI_REGISTRY_IMAGE:$BUILD_VERSION $CI_REGISTRY_IMAGE:$LATEST_VERSION
    - docker push $CI_REGISTRY_IMAGE:$BUILD_VERSION;
    - docker push $CI_REGISTRY_IMAGE:$LATEST_VERSION;
    - docker rmi $CI_REGISTRY_IMAGE:$BUILD_VERSION
    - docker rmi $CI_REGISTRY_IMAGE:$LATEST_VERSION
  artifacts:
    name: docs
    paths:
      - ./docs
    expire_in: never

convert_html_to_php:
  stage: convert
  tags:
    - mkdocs
  needs: ["docs_build"]
  script:
    - cd ./extra && bash html-to-php.sh
  artifacts:
    name: docs-php
    paths:
      - ./docs
    expire_in: never

docs_deploy_dev:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  tags:
    - mkdocs
  needs: ["convert_html_to_php"]
  rules:
    - if: $CI_COMMIT_BRANCH == 'dev'
  script:
    - echo "Deploying dev version"
    - rm -rf /var/www/dev_trusted/documentation/*
    - cp -r ./docs/* /var/www/dev_trusted/documentation

docs_deploy_prod:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  tags:
    - mkdocs
  needs: ["convert_html_to_php"]
  rules:
    - if: $CI_COMMIT_BRANCH == 'main'
  script:
    - echo "Deploying prod version"

Послесловие

Мы интегрировали MkDocs Material и автоматизировали публикацию в Битрикс, создав единую систему документации. Это принесло положительные результаты:

Оперативность обновлений: правки доходят до пользователей за считанные минуты.
Снижение нагрузки: нет необходимости дублировать контент для GitLab и Битрикс — всё синхронизируется автоматически.
Гибкость: Markdown дает свободу форматирования, а тема Material обеспечивает современный адаптивный дизайн.

Эта система — не финальное решение, а гибкая основа, которая будет развиваться вместе с нашими продуктами. Сейчас мы активно работаем над улучшениями. Вводим версионность документации и добавляем выбор продукта. Если у вас есть опыт подобных внедрений, мы будем рады обсудить в комментариях!

Спасибо, что прочитали до конца.