CI/CD pipeline для документации

Основные концепции

CI/CD (Continuous Integration / Continuous Deployment) для документации — это процесс автоматизации сборки, тестирования и публикации документации при изменениях в исходном коде или контенте. В современном JavaScript-стеке для работы с Markdown и HTML широко используются библиотеки Remark и Rehype, которые позволяют обрабатывать текст, выполнять линтинг, трансформации и генерацию HTML с высокой гибкостью.

Структура pipeline

  1. Источники документации Markdown-файлы (.md) служат основой документации. Они хранятся в отдельной директории репозитория, обычно docs/ или documentation/. Каждый файл должен быть структурирован с использованием заголовков (#, ##, ###) для правильного построения дерева документа.

  2. Pre-processing с Remark Remark позволяет анализировать и преобразовывать Markdown. В pipeline обычно выполняются следующие шаги:

    • Линтинг Markdown через плагины вроде remark-lint для проверки стиля и структуры текста.
    • Обработка кастомных синтаксических расширений с помощью плагинов remark-parse и remark-rehype.
    • Добавление метаданных или автогенерация оглавления с помощью remark-toc или кастомных плагинов.

    Пример конфигурации линтера в .remarkrc.js:

    module.exports = {
  plugins: [
    'remark-preset-lint-recommended',
    ['remark-lint-heading-increment', true],
    ['remark-toc', { heading: 'Содержание' }]
  ]
};

  3. Преобразование в HTML с Rehype Rehype берет Markdown-дерево, преобразованное Remark, и конвертирует его в HTML. Это позволяет интегрировать документацию с веб-сайтами, статическими генераторами или системами публикации. Основные шаги:

    • remark-rehype выполняет трансформацию AST Markdown в AST HTML.
    • Плагины Rehype (rehype-highlight, rehype-slug, rehype-autolink-headings) добавляют подсветку синтаксиса, идентификаторы заголовков и ссылки на них.
    • Итоговый HTML можно сохранить локально или отправить на сервер/статический генератор.

    Пример pipeline в Node.js:

    const fs = require('fs');
const { unified } = require('unified');
const remarkParse = require('remark-parse');
const remarkRehype = require('remark-rehype');
const rehypeStringify = require('rehype-stringify');
const rehypeHighlight = require('rehype-highlight');

unified()
  .use(remarkParse)
  .use(remarkRehype)
  .use(rehypeHighlight)
  .use(rehypeStringify)
  .process(fs.readFileSync('docs/guide.md'))
  .then(file => fs.writeFileSync('dist/guide.html', String(file)));

  4. Интеграция с системой CI/CD Для автоматизации процесса обычно используют GitHub Actions, GitLab CI/CD или Jenkins. Pipeline строится по принципу:

    • Trigger: push или pull request в ветку документации.
    • Install: установка зависимостей Node.js (npm ci или yarn install).
    • Lint: проверка Markdown через Remark (npx remark docs/).
    • Build: генерация HTML с помощью Rehype (node build.js).
    • Deploy: публикация на сервер или статический хостинг (gh-pages, Netlify, Vercel).

    Пример workflow для GitHub Actions:

    name: Docs CI/CD
on:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npx remark docs/
      - run: node build.js
      - run: npx gh-pages -d dist

Расширенные возможности

  • Автогенерация ссылок и оглавлений Использование rehype-slug и rehype-autolink-headings позволяет автоматически создавать якоря для заголовков, что улучшает навигацию по документации и упрощает интеграцию с внешними ссылками.

  • Подсветка кода и улучшенная визуализация Плагин rehype-highlight или интеграция с prismjs позволяет автоматически подсвечивать синтаксис всех блоков кода Markdown, сохраняя единый стиль документации.

  • Проверка ссылок и валидность контента Remark-плагины типа remark-validate-links обеспечивают автоматическую проверку всех внутренних и внешних ссылок, предотвращая появление “битых” ссылок после деплоя.

  • Интеграция с генераторами статических сайтов Использование Remark/Rehype в связке с Next.js, Astro или Eleventy позволяет строить современную документацию с реактивными компонентами и клиентской логикой.

Организация проекта

Рекомендуется держать структуру проекта следующей:

project-root/
├─ docs/
│  ├─ guide.md
│  ├─ api.md
│  └─ tutorials/
├─ dist/
├─ build.js
├─ package.json
├─ .remarkrc.js
└─ .github/workflows/docs.yml
  • docs/ — исходные Markdown-файлы.
  • dist/ — готовый HTML после сборки.
  • build.js — Node.js скрипт для генерации документации.
  • .remarkrc.js — конфигурация Remark.
  • .github/workflows/docs.yml — CI/CD pipeline.

Лучшие практики

  • Единый стиль Markdown — строгое соблюдение правил линтинга через remark-lint.
  • Модульная структура документации — разделение на файлы по темам или разделам.
  • Автоматическое тестирование — проверка всех ссылок и корректности HTML в CI.
  • Версионирование документации — поддержка веток и тегов для разных версий продукта.
  • Сборка только изменённых файлов — оптимизация pipeline для ускорения деплоя при больших объёмах документации.

Этот подход обеспечивает полностью автоматизированный процесс: от написания Markdown до публикации готовой HTML-документации с подсветкой кода, валидными ссылками и интерактивными элементами.

Оглавление