docmd v0.5: Минималистичный генератор документации с версионированием и zero-config режимом

TL;DR

docmd v0.5 — это Node.js генератор статической документации с автоматическим роутингом, встроенным версионированием и zero-config режимом. Решение для тех, кому надоели React/Vue-оверхеды в документации.

Введение: Контекст и боль

Современные генераторы документации (Docusaurus, VitePress) часто:

1. Требуют ручного описания навигации
2. Перегружены hydration-логикой
3. Неудобно работают с версионированием

docmd предлагает альтернативу:

• 20kb JS вместо мегабайтных бандлов
• Автоматический роутинг через AST-парсинг заголовков
• Нативная поддержка версий без ветвления репозитория

Основная часть: Архитектурные решения

Zero-Config Mode

Запуск с флагом -z сканирует директорию и строит навигацию:

npx docmd dev -z

Как это работает:

1. Рекурсивный обход ./docs
2. Парсинг H1-H3 заголовков (без полного AST)
3. Генерация sidebar.json с сохранением иерархии

Enterprise Versioning

Конфиг для multi-version проектов:

// docmd.config.js
export default defineConfig({
  versions: {
    latest: './docs',
    v2: './docs-v2',
    legacy: './docs-2020'
  }
})

Принципы работы:

• Изолированные сборки в /v2/, /legacy/
• Контекстные редиректы при переключении версий
• Умный sidebar скрывает несуществующие пути

DX Улучшения

1. TypeScript-first конфиг:

defineConfig({
  src: './docs', // Автодополнение путей
  out: './dist',
  title: 'My Project'
})

2. Нативные 404:

• Генерация физических 404.html
• SEO-friendly редиректы для GitHub Pages/S3

Практическое применение

Кейс: Миграция с Docusaurus

Проблемы:

• 300ms задержка из-за hydration
• Ручное версионирование через ветки

Решение:

# 1. Инициализация
npx docmd init -z

# 2. Перенос версий
mkdir -p docs/v1 docs/v2
cp -r old-docs/versioned_docs/1.x/* docs/v1/

Интеграция с CI/CD

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

- name: Build docs
  run: |
    npx docmd build --minify
    echo "Built versions: $(ls dist)"

Заключение

Когда выбирать docmd:

• Нужен легковесный SSG без React
• Требуется простое версионирование
• Важна скорость First Contentful Paint

Когда смотреть в сторону Docusaurus:

• Нужны кастомные React-компоненты в MDX
• Требуется готовый поиск (хотя docmd планирует Algolia-интеграцию)

Философия проекта: документация должна быть быстрой и содержательной, а не демонстрацией возможностей фреймворка.

Источник: https://github.com/docmd-io/docmd