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

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

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

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

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

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

Наша система теперь эффективно обрабатывает документацию из более чем 50 тысяч статей, включая отдельные статьи, содержащие более 10 МБ текста и разметки. Это позволяет использовать Diplodoc для создания и поддержки масштабных документационных проектов без потери производительности.

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, сделав её более аккуратной при работе с файловой системой, что особенно важно для больших проектов с множеством вложенных директорий.

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

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

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

Мы систематизировали параметры запуска для более интуитивного использования. Раньше у нас было несколько "выключающих" параметров, которые было сложно запомнить: --disableLiquid, --lintDisabled, --buildDisabled, --needToSanitizeHtml. Мы убрали лишние параметры, а оставшиеся привели к единой системе именования:

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

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

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

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

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

Небольшие технические улучшения

  • Разводящие страницы полностью поддерживают frontmatter, что позволяет настраивать их метаданные и поведение
  • Использование Latex и Mermaid синтаксиса больше не требует флаг --allow-custom-resources, эти функции теперь доступны по умолчанию
  • Более безопасная работа с файловой системой - закрыт ряд уязвимостей, позволявших обратиться к файлам за пределами проекта
Предыдущая
Logger Service