--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://3y3.dev/ru/dev/extensions-api.md - href: ru/dev/extensions-api.md type: text/markdown title: Markdown version - href: llms.txt type: text/markdown title: llms.txt updatedAt: '2026-03-26T13:27:47.000Z' --- > **Documentation Index:** Fetch the complete configuration index at https://3y3.dev/ru/llms.txt # Diplodoc Extensions API Diplodoc Extensions API предоставляет механизм для расширения функциональности Diplodoc CLI. Построенный на hook-based системе на основе библиотеки [tappable](https://github.com/webpack/tapable), он позволяет создавать модульные, интегрируемые и расширяемые компоненты. На базе архитектуры Extensions API построены внутренние модули CLI. ## Возможности - **Hook-based Architecture**: Система хуков для расширения функциональности на различных этапах процесса сборки документации. - **Type Safety**: Полная поддержка TypeScript с подробными определениями типов. - **Modular Design**: Создание независимых, переиспользуемых расширений. - **Configuration Support**: Гибкая настройка через файлы конфигурации и параметры командной строки. - **Resource Management**: Встроенные lifecycle-хуки для правильной инициализации и очистки ресурсов. - **Logging and Debugging**: Интегрированная система логирования с несколькими уровнями детализации. ## Базовые концепции ### Program и Run В основе архитектуры Diplodoc лежат два ключевых класса: 1. ##**Program**## — базовый класс для всех команд CLI. Он предоставляет: - Систему хуков для расширения функциональности - Управление конфигурацией - Доступ к логированию - Интерфейс для регистрации расширений 2. ##**Run**## — контекст выполнения команды. Содержит: - Доступ к сервисам (TOC, Markdown, Leading и др.) - Информацию о текущем состоянии - Утилиты для работы с файлами - Системы логирования и отладки ### Хуки и их использование Хуки — это основной механизм расширения функциональности. Они позволяют: - Встраиваться в различные этапы выполнения программы - Модифицировать поведение сервисов - Добавлять новую функциональность Существует два типа хуков: 1. **Base Hooks** — общие хуки программы: ```typescript export class Extension { apply(program: Build) { // Получение базовых hooks const baseHooks = getBaseHooks(program); // Hook перед любым запуском baseHooks.BeforeAnyRun.tap('MyExtension', (run) => { // Инициализация }); // Hook после выполнения baseHooks.AfterAnyRun.tap('MyExtension', (run) => { // Очистка }); } } ``` 2. **Service Hooks** — специфичные для каждого сервиса: ```typescript export class Extension { apply(program: Build) { getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => { // Получение hooks конкретного сервиса const tocHooks = getTocHooks(run.toc); const markdownHooks = getMarkdownHooks(run.markdown); const leadingHooks = getLeadingHooks(run.leading); // Использование hooks tocHooks.Item.tap('MyExtension', (item) => { // Обработка элемента TOC }); }); } } ``` ### Работа с сервисами Сервисы — это основные компоненты Diplodoc, отвечающие за различные аспекты обработки документации. Доступ к сервисам осуществляется через контекст `run`: ```typescript export class Extension { apply(program: Build) { getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => { // Доступ к сервисам const {toc, markdown, leading, meta, vars} = run; // Получение hooks сервисов const tocHooks = getTocHooks(toc); const markdownHooks = getMarkdownHooks(markdown); const leadingHooks = getLeadingHooks(leading); const metaHooks = getMetaHooks(meta); const varsHooks = getVarsHooks(vars); }); } } ``` Подробное описание каждого сервиса: - [TOC Service](https://3y3.dev/ru/dev/extensions/services/toc-service.md) — управление структурой документации. - [Leading Service](https://3y3.dev/ru/dev/extensions/services/leading-service.md) — обработка разводящих страниц. - [Markdown Service](https://3y3.dev/ru/dev/extensions/services/markdown-service.md) — трансформация markdown-контента. - [Meta Service](https://3y3.dev/ru/dev/extensions/services/meta-service.md) — работа с метаданными документации. - [Vars Service](https://3y3.dev/ru/dev/extensions/services/vars-service.md) — управление переменными и шаблонами. - [VCS Service](https://3y3.dev/ru/dev/extensions/services/vcs-service.md) — работа с системой контроля версий. - [Search Service](https://3y3.dev/ru/dev/extensions/services/search-service.md) — организация поиска по документации. - [Logger Service](https://3y3.dev/ru/dev/extensions/services/logger-service.md) — управление логгированием. ## Когда использовать расширения Расширения особенно полезны, когда вам нужно: 1. Добавить новые параметры командной строки в Diplodoc CLI. 2. Модифицировать или улучшить процесс сборки документации. 3. Добавить поддержку новых типов файлов или методов обработки. 4. Интегрироваться с внешними сервисами или API. 5. Добавить пользовательские шаги валидации или трансформации документов. ## Типы расширений Diplodoc поддерживает несколько типов расширений, каждый из которых предназначен для решения определенных задач: ### 1. Command Extensions Этот тип расширений позволяет модифицировать CLI-интерфейс Diplodoc. Используйте его, когда нужно: - добавить новые команды в CLI, - расширить существующие команды новыми параметрами, - изменить поведение существующих команд. В примере ниже показано, как добавить новый параметр к команде: {% cut "Пример добавления нового параметра к команде" "%} ```typescript import {Build} from '@diplodoc/cli'; export class Extension { apply(program) { if (Build.is(program)) { getBaseHooks(program).Command.tap('MyCommand', (command) => { command.addOption(new Option('--my-option')); }); } } } ``` {% endcut %} ### 2. Processing Extensions Processing Extensions предназначены для модификации процесса сборки документации. Они особенно полезны, когда вам нужно: - изменить содержимое или структуру TOC, - трансформировать markdown-контент, - добавить пользовательские включатели, - выполнить валидацию контента во время сборки. {% cut "Пример расширения" "%} ```typescript export class Extension { apply(program: Build) { getBaseHooks(program).BeforeAnyRun.tap('MyProcessor', (run) => { // Получение hooks нужных сервисов const tocHooks = getTocHooks(run.toc); const markdownHooks = getMarkdownHooks(run.markdown); // Настройка обработки tocHooks.Item.tapPromise('MyProcessor', async (item) => { // Обработка элемента TOC return item; }); markdownHooks.Resolved.tapPromise('MyProcessor', async (content) => { // Обработка markdown return content; }); }); } } ``` {% endcut %} ### 3. Integration Extensions Integration Extensions обеспечивают взаимодействие Diplodoc с внешними сервисами. Используйте их для: - загрузки данных из внешних API, - обогащения документации внешними метаданными, - синхронизации с другими системами, - отправки уведомлений или метрик. Пример расширения: ```typescript export class Extension { constructor(private apiKey: string) {} apply(program: Build) { getBaseHooks(program).BeforeAnyRun.tap('MyIntegration', (run) => { // Интеграция с внешним API getLeadingHooks(run.leading).Resolved.tapPromise('MyIntegration', async (content) => { const externalData = await this.fetchExternalData(this.apiKey); return { ...content, externalData }; }); }); } private async fetchExternalData(apiKey: string) { // Логика получения данных из внешнего API } } ```