---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://3y3.dev/ru/dev/extensions/services.md
  - href: ru/dev/extensions/services.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

Сервисы — это основные компоненты Diplodoc, отвечающие за различные аспекты обработки документации. Каждый сервис предоставляет свой набор хуков для расширения функциональности.

## Доступные сервисы

- [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) — управление логгированием.

## Работа с сервисами

### Получение доступа к сервисам

Все сервисы доступны через контекст выполнения `run`, который передается в хуки:

```typescript
export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // Доступ к сервисам
            const {toc, markdown, leading} = run;
        });
    }
}
```

### Получение хуков сервиса

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

```typescript
import {getHooks as getBaseHooks} from '@diplodoc/cli/lib/program';
import {getHooks as getTocHooks} from '@diplodoc/cli/lib/toc';
import {getHooks as getMarkdownHooks} from '@diplodoc/cli/lib/markdown';
import {getHooks as getLeadingHooks} from '@diplodoc/cli/lib/leading';

export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // Получение хуков сервисов
            const tocHooks = getTocHooks(run.toc);
            const markdownHooks = getMarkdownHooks(run.markdown);
            const leadingHooks = getLeadingHooks(run.leading);
        });
    }
}
```

### Использование хуков

Хуки сервисов следуют единому паттерну использования:

```typescript
serviceHooks.HookName.tap('ExtensionName', (data) => {
    // Синхронная обработка
    return modifiedData;
});

// или

serviceHooks.HookName.tapPromise('ExtensionName', async (data) => {
    // Асинхронная обработка
    return modifiedData;
});
```

### API сервисов

Каждый сервис, помимо хуков, предоставляет набор методов для работы с данными:

```typescript
export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // TOC Service API
            const tocPath = run.toc.dir(entry);      // Получение директории TOC
            const tocData = run.toc.data(entry);     // Получение данных TOC
            const entries = run.toc.entries;         // Список всех entry в TOC
            
            // Leading Service API
            const hasLeading = run.leading.has(path);    // Проверка наличия leading-страницы
            const leadingData = run.leading.get(path);   // Получение данных leading-страницы
            
            // Markdown Service API
            const content = run.markdown.read(path);     // Чтение markdown-файла
            await run.markdown.save(path, content);      // Сохранение markdown-файла
        });
    }
}
```

Использование API сервисов вместо прямой работы с файловой системой позволяет:
- Получать данные в правильном контексте сборки
- Использовать внутреннее кеширование
- Поддерживать различные форматы и источники данных
- Обеспечивать консистентность данных

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

### 1. Изоляция логики

Разделяйте логику обработки по соответствующим сервисам:

```typescript
export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            // TOC-специфичная логика
            const tocHooks = getTocHooks(run.toc);
            tocHooks.Item.tap('MyExtension', (item) => {
                // Работа со структурой
                return item;
            });

            // Markdown-специфичная логика
            const markdownHooks = getMarkdownHooks(run.markdown);
            markdownHooks.Resolved.tap('MyExtension', (content) => {
                // Работа с контентом
                return content;
            });
        });
    }
}
```

### 2. Обработка ошибок

Всегда обрабатывайте возможные ошибки в хуках:

```typescript
export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap('MyExtension', (run) => {
            const tocHooks = getTocHooks(run.toc);
            
            tocHooks.Item.tapPromise('MyExtension', async (item) => {
                try {
                    const processedItem = await processItem(item);
                    return processedItem;
                } catch (error) {
                    run.logger.error('Failed to process TOC item:', error);
                    return item;
                }
            });
        });
    }
}
```

### 3. Порядок выполнения хуков

Порядок выполнения хуков определяется двумя факторами:

1. **Жизненный цикл программы**: основной порядок выполнения хуков определяется жизненным циклом Diplodoc. 
<!-- Подробнее об этом можно прочитать в [Extension Lifecycle](https://3y3.dev/ru/dev/lifecycle.md). -->

2. **Конфигурация хуков**: для управления порядком выполнения хуков с одинаковым именем используются возможности библиотеки [tapable](https://github.com/webpack/tapable):

```typescript
export class Extension {
    apply(program: Build) {
        getBaseHooks(program).BeforeAnyRun.tap({
            name: 'MyExtension',
            stage: 10, // Более высокий stage выполняется позже
            before: ['OtherExtension'], // Выполнить до указанных расширений
            after: ['AnotherExtension'], // Выполнить после указанных расширений
        }, (run) => {
            // Логика расширения
        });
    }
}
```

Также можно использовать различные типы хуков для специфических сценариев:
- `tap` - синхронный хук
- `tapAsync` - асинхронный хук с callback
- `tapPromise` - асинхронный хук с Promise
- `intercept` - для перехвата вызовов хука

<!-- ## Дополнительная информация

- [Core Concepts](https://3y3.dev/ru/dev/extensions/core-concepts.md) - базовые концепции архитектуры
- [Extension Lifecycle](https://3y3.dev/ru/dev/lifecycle.md) - жизненный цикл расширений
- [Examples](https://3y3.dev/ru/dev/examples.md) - примеры использования сервисов -->