Diplodoc v5.0: Новый уровень производительности

Статья создана
Обновлена 19 ноября 2025 г.

Основные улучшения

Оптимизация производительности

  • Ускорение работы CLI-инструментов (базовое ускорение в 3 раза)
  • Многопоточная обработка документов с ускорением до 10 раз на многоядерных системах
  • Кэширование и оптимизация загрузки ресурсов
  • Оптимизированная обработка больших проектов

Сравнения со старой версией:

Работа над улучшением производительности велась с версии 4.39. Достигнуто базовое ускорение в три раза за счет оптимизации алгоритмов обработки документов, улучшения кэширования и оптимизированного использования ресурсов. Параллельная обработка документов дополнительно ускоряет сборку в зависимости от числа ядер в системе. При работе с большими проектами на многоядерных серверах наблюдается ускорение в 10 раз.

Система обрабатывает документацию из более чем 50 тысяч статей, включая отдельные статьи, содержащие более 10 МБ текста и разметки.

Extension API и система хуков

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

  • Система расширений для разработчиков с полной поддержкой TypeScript
  • Встроенная система хуков для расширения функциональности на различных этапах
  • Модульный дизайн для создания независимых, переиспользуемых расширений
  • Документированный API для создания плагинов и интеграций
  • Примеры интеграции с популярными инструментами
  • Система управления жизненным циклом расширений

Разработано несколько расширений на новой системе, которые можно использовать в качестве примеров для создания собственных расширений:

  • GenericIncluder - расширение для автоматической генерации оглавления (TOC). Анализирует файловую систему, находит Markdown-файлы и автоматически создает структуру оглавления на основе их расположения и содержимого. При формировании оглавления учитывает заголовок файла и его вес, указанные в frontmatter.

  • GithubVcsConnector - расширение для сбора информации о контрибьюторах и авторах статей из GitHub. Собирает метаданные о коммитах, авторах и контрибьюторах и отображает их в интерфейсе документации.

  • AlgoliaSearch - интеграция с Algolia для полнотекстового поиска. Индексирует контент документации в Algolia, настраивает поисковые подсказки и фильтры. Выполняет поиск по документации с поддержкой различных языков.

  • LocalSearch - расширение для локального поиска по документации с использованием библиотеки lunr.js. Создает поисковый индекс на стороне клиента. Поддерживает нечеткий поиск, поиск по фразам и ранжирование результатов по релевантности. Для проектов, требующих работы в офлайн-режиме или с ограничениями по конфиденциальности данных.

Эти расширения демонстрируют различные возможности новой системы расширений и могут служить отправной точкой для разработки собственных плагинов. Каждое из них реализует свой набор хуков и использует различные аспекты API расширений.

Улучшенная система оглавления (TOC)

  • Расширенная поддержка шаблонизации переменными для полей href и label
  • Автоматическое извлечение заголовков из файлов для поля name
  • Улучшенная обработка includes в TOC с более аккуратной работой с файловой системой

В системе оглавления (TOC) расширена поддержка шаблонизации переменными для динамического формирования ссылок и меток. Поле name автоматически извлекает заголовок из файла, на который ссылается элемент оглавления. Улучшена обработка includes в TOC при работе с файловой системой.

Система редиректов

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

Улучшенная система конфигурации

Систематизирована система именования параметров запуска:

  • --disableLiquid → --no-template
  • --lintDisabled → --no-lint
  • --needToSanitizeHtml false → --no-sanitize-html

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

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

  • --langs - управление языками документации
  • --search - настройка параметров поиска
  • --changelogs - управление списком изменений
  • --mtimes - настройка временных меток

Подробнее в обновленном разделе Настройки YFM-проекта

Другие технические улучшения

  • Разводящие страницы поддерживают frontmatter для настройки метаданных и поведения
  • Использование Latex и Mermaid синтаксиса доступно по умолчанию
  • Устранены уязвимости, позволявшие обратиться к файлам за пределами проекта