From ee8333c6b60fd53221cb233286f2c1d4cefa9490 Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Fri, 24 Oct 2025 20:43:02 +0700
Subject: [PATCH 01/14] DOCSUP-116726

---
 ru/index.yaml            |   2 +-
 ru/plugins/extensions.md | 101 +++++++++++++++++++
 ru/plugins/import.md     | 204 ++++++++++++++++++++++++++++++++++++++-
 ru/plugins/index.md      |  97 ++++++++++++++++++-
 ru/toc.yaml              |   7 +-
 5 files changed, 403 insertions(+), 8 deletions(-)
 create mode 100644 ru/plugins/extensions.md

diff --git a/ru/index.yaml b/ru/index.yaml
index c5dc5f1a..7cadbd2f 100644
--- a/ru/index.yaml
+++ b/ru/index.yaml
@@ -110,7 +110,7 @@ blocks:
         text: |
           [Transformer](tools/transform/index.md)
 
-          [Плагины](plugins/index.md)
+          [Плагины](plugins/)
   
       - type: basic-card
         title: 
diff --git a/ru/plugins/extensions.md b/ru/plugins/extensions.md
new file mode 100644
index 00000000..2ce66ca6
--- /dev/null
+++ b/ru/plugins/extensions.md
@@ -0,0 +1,101 @@
+# Расширения
+
+Расширения — это дополнительные модули, которые расширяют функциональность Diplodoc, добавляя новые возможности для обработки и отображения контента. В отличие от плагинов markdown-it, расширения работают на уровне всего процесса сборки документации.
+
+## Что такое расширения
+
+Расширения позволяют:
+- Добавлять новые типы контента и блоков
+- Интегрироваться с внешними сервисами
+- Обрабатывать метаданные документов
+- Модифицировать процесс сборки
+
+## Встроенные расширения
+
+В Diplodoc включены следующие встроенные расширения, которые служат примерами для создания собственных:
+
+### OpenAPI Extension
+Расширение для отображения OpenAPI спецификаций в документации.
+
+**Возможности:**
+- Автоматическое создание документации API из OpenAPI/Swagger файлов
+- Интерактивное отображение эндпоинтов
+- Поддержка различных форматов спецификаций
+
+**Использование:**
+```yaml
+# В файле конфигурации
+openapi:
+  spec: path/to/openapi.yaml
+```
+
+### Mermaid Extension  
+Расширение для создания диаграмм с помощью Mermaid.
+
+**Возможности:**
+- Создание блок-схем, диаграмм последовательности, диаграмм Ганта
+- Рендеринг диаграмм на стороне клиента или сервера
+- Поддержка тем оформления
+
+**Использование:**
+```markdown
+```mermaid
+graph TD
+    A[Начало] --> B[Процесс]
+    B --> C[Конец]
+```
+```
+
+## Создание собственных расширений
+
+Встроенные расширения служат примерами архитектуры для создания собственных расширений. Они демонстрируют:
+
+- Структуру кода расширения
+- Интеграцию с процессом сборки
+- Обработку конфигурации
+- Взаимодействие с другими компонентами системы
+
+### Архитектура расширения
+
+Расширение должно экспортировать объект со следующими свойствами:
+
+```javascript
+module.exports = {
+  name: 'extension-name',
+  transform: (params) => {
+    // Логика обработки контента
+  },
+  hooks: {
+    // Хуки для интеграции с процессом сборки
+  }
+};
+```
+
+### Подключение расширения
+
+Расширения подключаются через конфигурационный файл:
+
+```javascript
+// diplodoc.config.js
+module.exports = {
+  extensions: [
+    './path/to/custom-extension',
+    '@scope/published-extension'
+  ]
+};
+```
+
+## Разница между плагинами и расширениями
+
+| Плагины | Расширения |
+|---------|------------|
+| Работают на уровне markdown-it | Работают на уровне всего процесса сборки |
+| Обрабатывают синтаксис Markdown | Могут модифицировать любую часть процесса |
+| Простая интеграция | Более сложная архитектура |
+| Множество готовых решений | Специфичны для Diplodoc |
+
+## Полезные ссылки
+
+- [Документация по разработке расширений](../dev/extensions-api.md)
+- [Примеры расширений на GitHub](https://github.com/diplodoc-platform/)
+- [API для разработчиков расширений](../dev/extensions/core-concepts.md)
\ No newline at end of file
diff --git a/ru/plugins/import.md b/ru/plugins/import.md
index 01af15f5..16f17c80 100644
--- a/ru/plugins/import.md
+++ b/ru/plugins/import.md
@@ -4,7 +4,7 @@ YFM использует [markdown-it](https://www.npmjs.com/package/markdown-it
 
 ## Подключение {#require}
 
-Перед подключением установите пакет с нужным плагином с помощью команды `npm i <имя_плагина>`. Например, чтобы установить [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji), выполните:
+Перед подключением установите пакет с нужным плагином с помощью команды `npm i <имя_плагина>`. Например, чтобы установить [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji), выполните:
 
 ```shell
 npm i markdown-it-emoji
@@ -72,3 +72,205 @@ npm i markdown-it-emoji
 ## Передача параметров {#options}
 
 YFM применяет неизвестные параметры из объекта `options` ко всем плагинам, поэтому для передачи параметров добавьте их в объект `options`.
+
+## Примеры подключения популярных плагинов
+
+### PlantUML диаграммы
+
+Плагин [markdown-it-plantuml](https://www.npmjs.com/package/markdown-it-plantuml) позволяет создавать UML-диаграммы прямо в Markdown.
+
+**Установка и настройка:**
+
+1. Склонируйте репозиторий CLI:
+   ```bash
+   git clone https://github.com/diplodoc-platform/cli.git
+   ```
+
+2. Установите зависимости и соберите проект:
+   ```bash
+   npm i && npm run build
+   ```
+
+3. Перейдите в папку `build` и создайте файл `index.js` со следующим содержимым:
+   ```javascript
+   const plantuml = require('markdown-it-plantuml');
+   
+   module.exports = [
+     plantuml
+   ];
+   ```
+
+**Использование:**
+
+После настройки вы можете добавлять PlantUML диаграммы в любую Markdown страницу:
+
+```markdown
+@startuml
+Alice -> Bob: Authentication Request
+Bob --> Alice: Authentication Response
+Alice -> Bob: Another authentication Request
+Alice <-- Bob: another authentication Response
+@enduml
+```
+
+**Результат:**
+
+@startuml
+Alice -> Bob: Authentication Request
+Bob --> Alice: Authentication Response
+Alice -> Bob: Another authentication Request
+Alice <-- Bob: another authentication Response
+@enduml
+
+### Списки задач (чекбоксы)
+
+Плагин для создания интерактивных списков задач уже входит в состав Diplodoc, но требует явного подключения.
+
+**Подключение:**
+
+{% list tabs %}
+
+- Transformer
+
+   ```javascript
+   const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
+   
+   const {result: {html, meta}, logs} = transform(content, {
+     plugins: [checkbox],
+     // Параметры плагина
+     divClass: 'checkbox',    // CSS-класс для div
+     idPrefix: 'checkbox'     // Префикс для id чекбокса
+   });
+   ```
+
+- Builder
+
+   ```javascript
+   // build/plugins/index.js
+   const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
+   
+   module.exports = [
+     checkbox
+   ];
+   ```
+
+{% endlist %}
+
+**Использование:**
+
+```markdown
+- [x] ~~Написать пресс-релиз~~
+- [ ] Обновить веб-сайт  
+- [ ] Связаться со СМИ
+```
+
+**Параметры:**
+- `divClass` — CSS-класс для `div`, который оборачивает чекбокс (по умолчанию: `checkbox`)
+- `idPrefix` — префикс для id чекбокса (по умолчанию: `checkbox`)
+
+### Эмодзи
+
+Плагин [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) добавляет поддержку эмодзи.
+
+**Установка:**
+```bash
+npm i markdown-it-emoji
+```
+
+**Подключение:**
+```javascript
+const emoji = require('markdown-it-emoji');
+
+// Для Transformer
+const {result: {html, meta}, logs} = transform(content, {
+  plugins: [emoji]
+});
+
+// Для Builder (в build/plugins/index.js)
+module.exports = [
+  emoji
+];
+```
+
+**Использование:**
+```markdown
+:smile: :heart: :thumbsup:
+```
+
+### Математические формулы
+
+Плагин [markdown-it-katex](https://www.npmjs.com/package/markdown-it-katex) позволяет отображать математические формулы.
+
+**Установка:**
+```bash
+npm i markdown-it-katex
+```
+
+**Подключение:**
+```javascript
+const katex = require('markdown-it-katex');
+
+const {result: {html, meta}, logs} = transform(content, {
+  plugins: [katex]
+});
+```
+
+**Использование:**
+```markdown
+Inline формула: $E = mc^2$
+
+Блочная формула:
+$$
+\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
+$$
+```
+
+## Создание собственного Builder
+
+Для удобства работы с дополнительными плагинами рекомендуется создать собственную сборку Builder:
+
+1. **Склонируйте репозиторий:**
+   ```bash
+   git clone https://github.com/diplodoc-platform/cli.git
+   cd cli
+   ```
+
+2. **Установите зависимости:**
+   ```bash
+   npm install
+   ```
+
+3. **Добавьте нужные плагины:**
+   ```bash
+   npm install markdown-it-plantuml markdown-it-emoji markdown-it-katex
+   ```
+
+4. **Настройте плагины в `build/plugins/index.js`:**
+   ```javascript
+   const plantuml = require('markdown-it-plantuml');
+   const emoji = require('markdown-it-emoji');
+   const katex = require('markdown-it-katex');
+   const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
+   
+   module.exports = [
+     plantuml,
+     emoji,
+     katex,
+     checkbox
+   ];
+   ```
+
+5. **Соберите проект:**
+   ```bash
+   npm run build
+   ```
+
+Теперь у вас есть собственная версия Diplodoc CLI со всеми необходимыми плагинами.
+
+## Полезные ссылки
+
+- [Список всех плагинов markdown-it](https://www.npmjs.com/search?q=keywords:markdown-it-plugin)
+- [Документация markdown-it](https://markdown-it.github.io/)
+- [Создание собственных плагинов](https://github.com/markdown-it/markdown-it/tree/master/docs)
+- [Предустановленные плагины Diplodoc](index.md)
+- [Расширения Diplodoc](extensions.md)
diff --git a/ru/plugins/index.md b/ru/plugins/index.md
index caec6a22..b714005b 100644
--- a/ru/plugins/index.md
+++ b/ru/plugins/index.md
@@ -1,13 +1,102 @@
-# Плагины
+# Предустановленные плагины
 
-Кроме базового синтаксиса [CommonMark Spec](https://spec.commonmark.org/), YFM предоставляет набор плагинов с дополнительными возможностями и уникальными элементами разметки.
+Diplodoc поставляется с набором предустановленных плагинов, которые расширяют базовый синтаксис [CommonMark Spec](https://spec.commonmark.org/) дополнительными возможностями и уникальными элементами разметки.
+
+## Как работают плагины
+
+Плагины — это модули [markdown-it](https://www.npmjs.com/package/markdown-it), которые обрабатывают и преобразуют разметку Markdown. Каждый плагин отвечает за определённый синтаксис или функциональность.
+
+## Подключение и настройка
+
+### Подключение отдельных плагинов
+
+Большинство предустановленных плагинов включены по умолчанию. Однако некоторые плагины требуют явного подключения:
+
+```javascript
+const transform = require('@diplodoc/transform');
+
+// Подключение плагина списка задач
+const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
+
+const {result: {html, meta}, logs} = transform(content, {
+  plugins: [checkbox]
+});
+```
+
+### Настройка параметров плагинов
+
+Параметры плагинов передаются через объект `options`:
+
+```javascript
+const {result: {html, meta}, logs} = transform(content, {
+  plugins: [checkbox],
+  // Параметры применяются ко всем подключённым плагинам
+  extractTitle: true,        // для плагина Anchors
+  supportGithubAnchors: true // для плагина Anchors
+});
+```
 
 {% note warning %}
 
-Порядок добавления плагинов важен. При добавлении плагинов необходимо указывать полный набор плагинов.
+При переопределении параметра `plugins` необходимо заново подключать все нужные плагины YFM. Порядок добавления плагинов важен — указывайте полный набор плагинов в правильной последовательности.
 
 {% endnote %}
 
+## Список предустановленных плагинов
+
 {% include [plugins.md](../_includes/plugins.md) %}
 
-Выше перечислены плагины, включенные в пакет YFM. Но вы можете [подключить дополнительные](import.md) или написать свой плагин, используя [руководство от markdown-it](https://github.com/markdown-it/markdown-it/tree/master/docs). 
+## Примеры использования
+
+### Настройка якорей заголовков
+
+```javascript
+const transform = require('@diplodoc/transform');
+
+const result = transform(content, {
+  extractTitle: true,           // Учитывать заголовок первого уровня
+  supportGithubAnchors: true,   // Генерировать якоря, совместимые с GitHub
+  disableCommonAnchors: false   // Включить стандартные якоря
+});
+```
+
+### Настройка заметок
+
+```javascript
+const result = transform(content, {
+  lang: 'en' // Язык для отображения типа заметки (по умолчанию 'ru')
+});
+```
+
+### Настройка списка задач
+
+```javascript
+const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
+
+const result = transform(content, {
+  plugins: [checkbox],
+  divClass: 'custom-checkbox',  // CSS-класс для div, оборачивающего чекбокс
+  idPrefix: 'task'              // Префикс для id чекбокса
+});
+```
+
+## Дополнительные возможности
+
+Помимо предустановленных плагинов, вы можете:
+
+- [Подключить дополнительные плагины](import.md) из экосистемы markdown-it
+- [Создать собственные расширения](extensions.md) для специфических потребностей
+- Использовать [встроенные расширения](extensions.md) как примеры для разработки
+
+## Отключение плагинов
+
+Чтобы отключить предустановленный плагин, исключите его из списка при явном указании плагинов:
+
+```javascript
+// Подключаем только нужные плагины
+const cut = require('@diplodoc/transform/lib/plugins/cut');
+const sup = require('@diplodoc/transform/lib/plugins/sup');
+
+const result = transform(content, {
+  plugins: [cut, sup] // Другие предустановленные плагины будут отключены
+});
diff --git a/ru/toc.yaml b/ru/toc.yaml
index 375cc1bf..257ca569 100644
--- a/ru/toc.yaml
+++ b/ru/toc.yaml
@@ -204,10 +204,13 @@ items:
     labeled: true
     items:
       - name: Плагины
-        href: plugins/index.md
         items:
-          - name: Дополнительные плагины
+          - name: Предустановленные
+            href: plugins/index.md
+          - name: Дополнительные
             href: plugins/import.md
+      - name: Расширения
+        href: plugins/extensions.md
       - name: Библиотека Mermaid
         href: tools/mermaid.md
         hidden: true

From b1ed7e71d479f92a040ef4e1629475ac933d87bd Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Mon, 27 Oct 2025 13:44:16 +0700
Subject: [PATCH 02/14] fix

---
 ru/_includes/plugins.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ru/_includes/plugins.md b/ru/_includes/plugins.md
index 8f8c0139..85d6db5a 100644
--- a/ru/_includes/plugins.md
+++ b/ru/_includes/plugins.md
@@ -1,5 +1,5 @@
 #|
-|| Название плагина | Описание | Параметры | Подключен по умолчанию |
+|| Название плагина | Описание | Параметры | Подключен по умолчанию ||
 || **Anchors**| Автоматическое генерирование [якорей для заголовков](../syntax/base.md#headers) | `extractTitle`: учитывать заголовок первого уровня</br> Тип: `bool`, По умолчанию: `false` </br></br>`supportGithubAnchors`: генерировать дополнительные якоря, совместимые с GitHub</br> Тип: `bool`, По умолчанию: `false` </br></br>`disableCommonAnchors`: отключить формирование якорей заголовков</br> Тип: `bool`, По умолчанию: `false` | + ||
 || **Code**| Отображение кнопки копирования в [блоках кода](../syntax/code.md#block) | - | + ||
 || **Cut** | Поддержка разметки [катов](../syntax/interactive-elements/cuts.md) | - | + ||

From 3d6e3639606f6c6d8f206f20e36e11c5a573f20b Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Mon, 27 Oct 2025 22:47:04 +0700
Subject: [PATCH 03/14] up

---
 ru/_includes/plugins.md |  89 ++++++++++++++++----
 ru/plugins/import.md    | 177 ++++++++++++----------------------------
 ru/plugins/index.md     | 115 +++++++++-----------------
 3 files changed, 161 insertions(+), 220 deletions(-)

diff --git a/ru/_includes/plugins.md b/ru/_includes/plugins.md
index 85d6db5a..c9455508 100644
--- a/ru/_includes/plugins.md
+++ b/ru/_includes/plugins.md
@@ -1,20 +1,73 @@
 #|
-|| Название плагина | Описание | Параметры | Подключен по умолчанию ||
-|| **Anchors**| Автоматическое генерирование [якорей для заголовков](../syntax/base.md#headers) | `extractTitle`: учитывать заголовок первого уровня</br> Тип: `bool`, По умолчанию: `false` </br></br>`supportGithubAnchors`: генерировать дополнительные якоря, совместимые с GitHub</br> Тип: `bool`, По умолчанию: `false` </br></br>`disableCommonAnchors`: отключить формирование якорей заголовков</br> Тип: `bool`, По умолчанию: `false` | + ||
-|| **Code**| Отображение кнопки копирования в [блоках кода](../syntax/code.md#block) | - | + ||
-|| **Cut** | Поддержка разметки [катов](../syntax/interactive-elements/cuts.md) | - | + ||
-|| **Deflist**| Поддержка разметки [списка определений](../syntax/lists.md#terms) | - | + ||
-|| **File** | Поддержка разметки [объектов файлов](../syntax/links.md#files) | `fileExtraAttrs`: дополнительные атрибуты для ссылки | + ||
-|| **Tasks list** | Добавление [списка задач](../syntax/additional.md#tasks-list) | `divClass`: classname для `div`, который оборачивает чекбокс</br> Тип: `string`, По умолчанию: `checkbox` </br></br> `idPrefix`: перфикс для id чекбокса</br> Тип: `string`, По умолчанию: `checkbox` | - ||
-|| **Images** | Добавление [изображений](../syntax/media.md#images) | `assetsPublicPath`: путь до иконок</br> Тип: `string`, По умолчанию: / | - ||
-|| **Imsize** | Задание размера изображений | - | - ||
-|| **Includes** | Переиспользование контента в документе | `getVarsPerFile`: функция, которая по пути к файлу возвращает вычисленные переменные</br> Тип: `function`, По умолчанию: -  | - ||
-|| **Links** | Расширение [синтаксиса ссылок](../syntax/links.md) | - | - ||
-|| **Monospace** | [Моноширинный шрифт](../syntax/base.md) | - | + ||
-|| **Meta** | Добавление [метаданных](../syntax/meta.md#meta) в начало файлов | - | + ||
-|| **Notes** | Поддержка разметки [заметок](../syntax/notes.md) | `lang`: язык для отображения типа заметки</br> Тип: `string`, По умолчанию: ru | + ||
-|| **Sup** | Вывод текста в [верхнем регистре](../syntax/base.md#line) | - | + ||
-|| **Table** | Поддержка [многострочных таблиц](../syntax/tables/multiline.md) | - | + ||
-|| **Tabs** | Поддержка разметки [табов](../syntax/interactive-elements/tabs.md) | - | + ||
-|| **Video** | Добавление [видео](../syntax/media.md#video) | - | + ||
+|| **Название плагина** | **Описание** | **Параметры** | **Подключен по умолчанию** ||
+|| **Anchors**
+|
+Автоматическое генерирование [якорей для заголовков](../syntax/base.md#headers)
+|
+
+`extractTitle`: учитывать заголовок первого уровня
+Тип: `bool`, По умолчанию: `false`
+
+`supportGithubAnchors`: генерировать дополнительные якоря, совместимые с GitHub
+Тип: `bool`, По умолчанию: `false`
+
+`disableCommonAnchors`: отключить формирование якорей заголовков
+Тип: `bool`, По умолчанию: `false`
+
+|
+\+
+||
+|| **Code**| Отображение кнопки копирования в [блоках кода](../syntax/code.md#block) | \- | \+ ||
+|| **Cut** | Поддержка разметки [катов](../syntax/interactive-elements/cuts.md) | \- | \+ ||
+|| **Deflist**| Поддержка разметки [списка определений](../syntax/lists.md#terms) | \- | \+ ||
+|| **File** | Поддержка разметки [объектов файлов](../syntax/links.md#files) | `fileExtraAttrs`: дополнительные атрибуты для ссылки | \+ ||
+||
+**Tasks list**
+|
+Добавление [списка задач](../syntax/additional.md#tasks-list)
+|
+`divClass`: classname для `div`, который оборачивает чекбокс
+Тип: `string`, По умолчанию: `checkbox`
+
+`idPrefix`: перфикс для id чекбокса
+Тип: `string`, По умолчанию: `checkbox`
+|
+\-
+||
+||
+**Images** 
+|
+Добавление [изображений](../syntax/media.md#images)
+|
+`assetsPublicPath`: путь до иконок
+Тип: `string`, По умолчанию: `/` | \-
+||
+|| **Imsize** | Задание размера изображений | \- | \- ||
+||
+**Includes**
+|
+Переиспользование контента в документе
+|
+`getVarsPerFile`: функция, которая по пути к файлу возвращает вычисленные переменные
+Тип: `function`, По умолчанию: \-
+|
+\-
+||
+|| **Links** | Расширение [синтаксиса ссылок](../syntax/links.md) | \- | \- ||
+|| **Monospace** | [Моноширинный шрифт](../syntax/base.md) | \- | \+ ||
+|| **Meta** | Добавление [метаданных](../syntax/meta.md#meta) в начало файлов | \- | \+ ||
+||
+**Notes**
+|
+Поддержка разметки [заметок](../syntax/notes.md)
+|
+`lang`: язык для отображения типа заметки
+Тип: `string`, По умолчанию: ru
+|
+\+
+||
+|| **Sup** | Вывод текста в [верхнем регистре](../syntax/base.md#line) | \- | \+ ||
+|| **Table** | Поддержка [многострочных таблиц](../syntax/tables/multiline.md) | \- | \+ ||
+|| **Tabs** | Поддержка разметки [табов](../syntax/interactive-elements/tabs.md) | \- | \+ ||
+|| **Video** | Добавление [видео](../syntax/media.md#video) | \- | \+ ||
 |#
\ No newline at end of file
diff --git a/ru/plugins/import.md b/ru/plugins/import.md
index 16f17c80..22ed7ec5 100644
--- a/ru/plugins/import.md
+++ b/ru/plugins/import.md
@@ -12,6 +12,43 @@ npm i markdown-it-emoji
 
 {% list tabs %}
 
+- Builder
+  
+  1. Склонируйте репозиторий CLI:
+
+      ```bash
+      git clone https://github.com/diplodoc-platform/cli.git
+      ```
+
+  1. Установите зависимости и соберите проект:
+
+      ```bash
+      npm i && npm run build
+      ```
+
+   1. Перейдите в папку `node_modules/@diplodoc/cli/build/plugins` и создайте файл `index.js` со следующим содержимым:
+ 
+      ```javascript
+         const emojiPlugin = require('markdown-it-emoji');
+
+         // Плагины необходимо экспортировать в виде массива функций, а не как отдельные именованные экспорты.
+         // Экспортируем массив функций плагинов
+         module.exports = [
+         emojiPlugin.full, // Используем конкретную версию плагина
+         // Добавьте другие плагины при необходимости
+         ];
+         ```
+
+
+   {% note tip %}
+
+   Чтобы не переносить необходимые плагины перед каждой сборкой, соберите собственный Builder:
+   - Установите исходный код с [GitHub](https://github.com/yandex-cloud/yfm-docs).
+   - Перенесите дополнительные плагины в папку `./plugins`.
+   - Соберите Builder по [инструкции с GitHub](https://github.com/yandex-cloud/yfm-docs#installation-1).
+
+   {% endnote %}
+
 - Transformer
 
    {% note warning %}
@@ -21,16 +58,19 @@ npm i markdown-it-emoji
    {% endnote %}
 
    1. Подключите плагин в своем коде с помощью функций `require()` или `import()`:
+
       ```javascript
-      const plugin1 = require('<имя_плагина>');
+      const plugin1 = require('markdown-it-emoji');
       ```
 
-   1. В параметре `plugins` добавьте новый плагин в массив:
+   2. В параметре `plugins` добавьте новый плагин в массив:
+   
       ```javascript
-      const {result: {html, meta}, logs} = transform(content, {plugins: [<имя_плагина>]});
+      const {result: {html, meta}, logs} = transform(content, {plugins: [markdown-it-emoji]});
       ```
 
    **Пример:**
+
    ```javascript
    const fs = require('fs');
    const transform = require('@diplodoc/transform');
@@ -41,32 +81,6 @@ npm i markdown-it-emoji
    const {result: {html, meta}, logs} = transform(content, {plugins: [cut, sup, emoji]});
    ```
 
-
-- Builder
-
-   1. Создайте файл `index.js` в папке `./plugins` в пакете `@diplodoc/cli` со следующим содержимым:
- 
-  ```javascript
-   // node_modules/@diplodoc/cli/build/plugins/index.js
-   const emojiPlugin = require('markdown-it-emoji');
-
-   // Плагины необходимо экспортировать в виде массива функций, а не как отдельные именованные экспорты.
-   // Экспортируем массив функций плагинов
-   module.exports = [
-     emojiPlugin.full, // Используем конкретную версию плагина
-     // Добавьте другие плагины при необходимости
-   ];
-   ```
-
-   {% note tip %}
-
-   Чтобы не переносить необходимые плагины перед каждой сборкой, соберите собственный Builder:
-   * Установите исходный код с [GitHub](https://github.com/yandex-cloud/yfm-docs).
-   * Перенесите дополнительные плагины в папку `./plugins`.
-   * Соберите Builder по [инструкции с GitHub](https://github.com/yandex-cloud/yfm-docs#installation-1).
-
-   {% endnote %}
-
 {% endlist %}
 
 ## Передача параметров {#options}
@@ -82,16 +96,19 @@ YFM применяет неизвестные параметры из объек
 **Установка и настройка:**
 
 1. Склонируйте репозиторий CLI:
+
    ```bash
    git clone https://github.com/diplodoc-platform/cli.git
    ```
 
 2. Установите зависимости и соберите проект:
+
    ```bash
    npm i && npm run build
    ```
 
 3. Перейдите в папку `build` и создайте файл `index.js` со следующим содержимым:
+
    ```javascript
    const plantuml = require('markdown-it-plantuml');
    
@@ -122,62 +139,18 @@ Alice -> Bob: Another authentication Request
 Alice <-- Bob: another authentication Response
 @enduml
 
-### Списки задач (чекбоксы)
-
-Плагин для создания интерактивных списков задач уже входит в состав Diplodoc, но требует явного подключения.
-
-**Подключение:**
-
-{% list tabs %}
-
-- Transformer
-
-   ```javascript
-   const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
-   
-   const {result: {html, meta}, logs} = transform(content, {
-     plugins: [checkbox],
-     // Параметры плагина
-     divClass: 'checkbox',    // CSS-класс для div
-     idPrefix: 'checkbox'     // Префикс для id чекбокса
-   });
-   ```
-
-- Builder
-
-   ```javascript
-   // build/plugins/index.js
-   const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
-   
-   module.exports = [
-     checkbox
-   ];
-   ```
-
-{% endlist %}
-
-**Использование:**
-
-```markdown
-- [x] ~~Написать пресс-релиз~~
-- [ ] Обновить веб-сайт  
-- [ ] Связаться со СМИ
-```
-
-**Параметры:**
-- `divClass` — CSS-класс для `div`, который оборачивает чекбокс (по умолчанию: `checkbox`)
-- `idPrefix` — префикс для id чекбокса (по умолчанию: `checkbox`)
-
 ### Эмодзи
 
 Плагин [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) добавляет поддержку эмодзи.
 
 **Установка:**
+
 ```bash
 npm i markdown-it-emoji
 ```
 
 **Подключение:**
+
 ```javascript
 const emoji = require('markdown-it-emoji');
 
@@ -193,6 +166,7 @@ module.exports = [
 ```
 
 **Использование:**
+
 ```markdown
 :smile: :heart: :thumbsup:
 ```
@@ -202,11 +176,13 @@ module.exports = [
 Плагин [markdown-it-katex](https://www.npmjs.com/package/markdown-it-katex) позволяет отображать математические формулы.
 
 **Установка:**
+
 ```bash
 npm i markdown-it-katex
 ```
 
 **Подключение:**
+
 ```javascript
 const katex = require('markdown-it-katex');
 
@@ -216,6 +192,7 @@ const {result: {html, meta}, logs} = transform(content, {
 ```
 
 **Использование:**
+
 ```markdown
 Inline формула: $E = mc^2$
 
@@ -224,53 +201,3 @@ $$
 \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
 $$
 ```
-
-## Создание собственного Builder
-
-Для удобства работы с дополнительными плагинами рекомендуется создать собственную сборку Builder:
-
-1. **Склонируйте репозиторий:**
-   ```bash
-   git clone https://github.com/diplodoc-platform/cli.git
-   cd cli
-   ```
-
-2. **Установите зависимости:**
-   ```bash
-   npm install
-   ```
-
-3. **Добавьте нужные плагины:**
-   ```bash
-   npm install markdown-it-plantuml markdown-it-emoji markdown-it-katex
-   ```
-
-4. **Настройте плагины в `build/plugins/index.js`:**
-   ```javascript
-   const plantuml = require('markdown-it-plantuml');
-   const emoji = require('markdown-it-emoji');
-   const katex = require('markdown-it-katex');
-   const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
-   
-   module.exports = [
-     plantuml,
-     emoji,
-     katex,
-     checkbox
-   ];
-   ```
-
-5. **Соберите проект:**
-   ```bash
-   npm run build
-   ```
-
-Теперь у вас есть собственная версия Diplodoc CLI со всеми необходимыми плагинами.
-
-## Полезные ссылки
-
-- [Список всех плагинов markdown-it](https://www.npmjs.com/search?q=keywords:markdown-it-plugin)
-- [Документация markdown-it](https://markdown-it.github.io/)
-- [Создание собственных плагинов](https://github.com/markdown-it/markdown-it/tree/master/docs)
-- [Предустановленные плагины Diplodoc](index.md)
-- [Расширения Diplodoc](extensions.md)
diff --git a/ru/plugins/index.md b/ru/plugins/index.md
index b714005b..4c538bab 100644
--- a/ru/plugins/index.md
+++ b/ru/plugins/index.md
@@ -1,102 +1,63 @@
 # Предустановленные плагины
 
-Diplodoc поставляется с набором предустановленных плагинов, которые расширяют базовый синтаксис [CommonMark Spec](https://spec.commonmark.org/) дополнительными возможностями и уникальными элементами разметки.
-
-## Как работают плагины
-
-Плагины — это модули [markdown-it](https://www.npmjs.com/package/markdown-it), которые обрабатывают и преобразуют разметку Markdown. Каждый плагин отвечает за определённый синтаксис или функциональность.
+Diplodoc предоставляет набор предустановленных плагинов, которые расширяют базовый синтаксис [CommonMark Spec](https://spec.commonmark.org/) дополнительными возможностями и уникальными элементами разметки.
 
 ## Подключение и настройка
 
-### Подключение отдельных плагинов
-
-Большинство предустановленных плагинов включены по умолчанию. Однако некоторые плагины требуют явного подключения:
+Большинство предустановленных плагинов подключены по умолчанию. Однако некоторые требуют явного подключения.
 
-```javascript
-const transform = require('@diplodoc/transform');
+### Пример подключения
 
-// Подключение плагина списка задач
-const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
+**Установка и настройка плагина `Tasks list` (списки задач):**
 
-const {result: {html, meta}, logs} = transform(content, {
-  plugins: [checkbox]
-});
-```
-
-### Настройка параметров плагинов
+1. Склонируйте репозиторий CLI:
 
-Параметры плагинов передаются через объект `options`:
+    ```bash
+    git clone https://github.com/diplodoc-platform/cli.git
+    ```
 
-```javascript
-const {result: {html, meta}, logs} = transform(content, {
-  plugins: [checkbox],
-  // Параметры применяются ко всем подключённым плагинам
-  extractTitle: true,        // для плагина Anchors
-  supportGithubAnchors: true // для плагина Anchors
-});
-```
+1. Установите зависимости и соберите проект:
 
-{% note warning %}
+    ```bash
+    npm i && npm run build
+    ```
 
-При переопределении параметра `plugins` необходимо заново подключать все нужные плагины YFM. Порядок добавления плагинов важен — указывайте полный набор плагинов в правильной последовательности.
-
-{% endnote %}
-
-## Список предустановленных плагинов
-
-{% include [plugins.md](../_includes/plugins.md) %}
+1. Установите пакет с плагин:
 
-## Примеры использования
+    ```bash
+      npm i markdown-it-plantuml
+      ```
 
-### Настройка якорей заголовков
+2. Перейдите в папку `node_modules/@diplodoc/cli/build/plugins` и создайте файл `index.js` со следующим содержимым:
+  
+    ```javascript
+    const plantuml = require('markdown-it-plantuml');
+    
+    module.exports = [
+      plantuml
+    ];
+    ```
 
-```javascript
-const transform = require('@diplodoc/transform');
+**Использование:**
 
-const result = transform(content, {
-  extractTitle: true,           // Учитывать заголовок первого уровня
-  supportGithubAnchors: true,   // Генерировать якоря, совместимые с GitHub
-  disableCommonAnchors: false   // Включить стандартные якоря
-});
+```markdown
+- [x] ~~Написать пресс-релиз~~
+- [ ] Обновить веб-сайт  
+- [ ] Связаться со СМИ
 ```
 
-### Настройка заметок
+**Параметры:**
+- `divClass` — CSS-класс для `div`, который оборачивает чекбокс (по умолчанию: `checkbox`)
+- `idPrefix` — префикс для id чекбокса (по умолчанию: `checkbox`)
 
-```javascript
-const result = transform(content, {
-  lang: 'en' // Язык для отображения типа заметки (по умолчанию 'ru')
-});
-```
-
-### Настройка списка задач
-
-```javascript
-const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
+## Список предустановленных плагинов
 
-const result = transform(content, {
-  plugins: [checkbox],
-  divClass: 'custom-checkbox',  // CSS-класс для div, оборачивающего чекбокс
-  idPrefix: 'task'              // Префикс для id чекбокса
-});
-```
+{% include [plugins.md](../_includes/plugins.md) %}
 
 ## Дополнительные возможности
 
 Помимо предустановленных плагинов, вы можете:
 
-- [Подключить дополнительные плагины](import.md) из экосистемы markdown-it
-- [Создать собственные расширения](extensions.md) для специфических потребностей
-- Использовать [встроенные расширения](extensions.md) как примеры для разработки
-
-## Отключение плагинов
-
-Чтобы отключить предустановленный плагин, исключите его из списка при явном указании плагинов:
-
-```javascript
-// Подключаем только нужные плагины
-const cut = require('@diplodoc/transform/lib/plugins/cut');
-const sup = require('@diplodoc/transform/lib/plugins/sup');
-
-const result = transform(content, {
-  plugins: [cut, sup] // Другие предустановленные плагины будут отключены
-});
+- [Подключить дополнительные плагины](import.md).
+- [Создать собственные расширения](extensions.md) для специфических потребностей.
+- Использовать [встроенные расширения](extensions.md) как примеры для разработки.

From b893678b870d59f5e0636f2ca32b1519dd8d3043 Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Tue, 28 Oct 2025 15:34:49 +0700
Subject: [PATCH 04/14] up

---
 ru/plugins/extensions.md | 101 ---------------------------------------
 ru/plugins/import.md     |  16 +++----
 ru/plugins/index.md      |  23 ++++-----
 ru/toc.yaml              |   2 -
 4 files changed, 17 insertions(+), 125 deletions(-)
 delete mode 100644 ru/plugins/extensions.md

diff --git a/ru/plugins/extensions.md b/ru/plugins/extensions.md
deleted file mode 100644
index 2ce66ca6..00000000
--- a/ru/plugins/extensions.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Расширения
-
-Расширения — это дополнительные модули, которые расширяют функциональность Diplodoc, добавляя новые возможности для обработки и отображения контента. В отличие от плагинов markdown-it, расширения работают на уровне всего процесса сборки документации.
-
-## Что такое расширения
-
-Расширения позволяют:
-- Добавлять новые типы контента и блоков
-- Интегрироваться с внешними сервисами
-- Обрабатывать метаданные документов
-- Модифицировать процесс сборки
-
-## Встроенные расширения
-
-В Diplodoc включены следующие встроенные расширения, которые служат примерами для создания собственных:
-
-### OpenAPI Extension
-Расширение для отображения OpenAPI спецификаций в документации.
-
-**Возможности:**
-- Автоматическое создание документации API из OpenAPI/Swagger файлов
-- Интерактивное отображение эндпоинтов
-- Поддержка различных форматов спецификаций
-
-**Использование:**
-```yaml
-# В файле конфигурации
-openapi:
-  spec: path/to/openapi.yaml
-```
-
-### Mermaid Extension  
-Расширение для создания диаграмм с помощью Mermaid.
-
-**Возможности:**
-- Создание блок-схем, диаграмм последовательности, диаграмм Ганта
-- Рендеринг диаграмм на стороне клиента или сервера
-- Поддержка тем оформления
-
-**Использование:**
-```markdown
-```mermaid
-graph TD
-    A[Начало] --> B[Процесс]
-    B --> C[Конец]
-```
-```
-
-## Создание собственных расширений
-
-Встроенные расширения служат примерами архитектуры для создания собственных расширений. Они демонстрируют:
-
-- Структуру кода расширения
-- Интеграцию с процессом сборки
-- Обработку конфигурации
-- Взаимодействие с другими компонентами системы
-
-### Архитектура расширения
-
-Расширение должно экспортировать объект со следующими свойствами:
-
-```javascript
-module.exports = {
-  name: 'extension-name',
-  transform: (params) => {
-    // Логика обработки контента
-  },
-  hooks: {
-    // Хуки для интеграции с процессом сборки
-  }
-};
-```
-
-### Подключение расширения
-
-Расширения подключаются через конфигурационный файл:
-
-```javascript
-// diplodoc.config.js
-module.exports = {
-  extensions: [
-    './path/to/custom-extension',
-    '@scope/published-extension'
-  ]
-};
-```
-
-## Разница между плагинами и расширениями
-
-| Плагины | Расширения |
-|---------|------------|
-| Работают на уровне markdown-it | Работают на уровне всего процесса сборки |
-| Обрабатывают синтаксис Markdown | Могут модифицировать любую часть процесса |
-| Простая интеграция | Более сложная архитектура |
-| Множество готовых решений | Специфичны для Diplodoc |
-
-## Полезные ссылки
-
-- [Документация по разработке расширений](../dev/extensions-api.md)
-- [Примеры расширений на GitHub](https://github.com/diplodoc-platform/)
-- [API для разработчиков расширений](../dev/extensions/core-concepts.md)
\ No newline at end of file
diff --git a/ru/plugins/import.md b/ru/plugins/import.md
index 22ed7ec5..8c3d799a 100644
--- a/ru/plugins/import.md
+++ b/ru/plugins/import.md
@@ -101,13 +101,18 @@ YFM применяет неизвестные параметры из объек
    git clone https://github.com/diplodoc-platform/cli.git
    ```
 
-2. Установите зависимости и соберите проект:
+1. Установите зависимости и соберите проект:
 
    ```bash
    npm i && npm run build
    ```
+1. Установите пакет с плагином:
 
-3. Перейдите в папку `build` и создайте файл `index.js` со следующим содержимым:
+    ```bash
+      npm install markdown-it-plantuml --save
+      ```
+
+1. Перейдите в папку `build` и создайте файл `index.js` со следующим содержимым:
 
    ```javascript
    const plantuml = require('markdown-it-plantuml');
@@ -194,10 +199,5 @@ const {result: {html, meta}, logs} = transform(content, {
 **Использование:**
 
 ```markdown
-Inline формула: $E = mc^2$
-
-Блочная формула:
-$$
-\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
-$$
+$\sqrt{3x-1}+(1+x)^2$
 ```
diff --git a/ru/plugins/index.md b/ru/plugins/index.md
index 4c538bab..d359ca8b 100644
--- a/ru/plugins/index.md
+++ b/ru/plugins/index.md
@@ -8,7 +8,8 @@ Diplodoc предоставляет набор предустановленны
 
 ### Пример подключения
 
-**Установка и настройка плагина `Tasks list` (списки задач):**
+**Установка и настройка плагина `Tasks list` (списки задач)**.
+Плагин для создания интерактивных списков задач уже входит в состав Diplodoc, но требует явного подключения.
 
 1. Склонируйте репозиторий CLI:
 
@@ -22,19 +23,19 @@ Diplodoc предоставляет набор предустановленны
     npm i && npm run build
     ```
 
-1. Установите пакет с плагин:
+1. Установите пакет с плагином:
 
     ```bash
-      npm i markdown-it-plantuml
+      npm i markdown-it-task-lists
       ```
 
-2. Перейдите в папку `node_modules/@diplodoc/cli/build/plugins` и создайте файл `index.js` со следующим содержимым:
+1. Перейдите в папку `node_modules/@diplodoc/cli/build/plugins` и создайте файл `index.js` со следующим содержимым:
   
     ```javascript
-    const plantuml = require('markdown-it-plantuml');
-    
+    const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
+
     module.exports = [
-      plantuml
+     checkbox
     ];
     ```
 
@@ -54,10 +55,4 @@ Diplodoc предоставляет набор предустановленны
 
 {% include [plugins.md](../_includes/plugins.md) %}
 
-## Дополнительные возможности
-
-Помимо предустановленных плагинов, вы можете:
-
-- [Подключить дополнительные плагины](import.md).
-- [Создать собственные расширения](extensions.md) для специфических потребностей.
-- Использовать [встроенные расширения](extensions.md) как примеры для разработки.
+Выше перечислены плагины, включенные в пакет YFM. Но вы можете [подключить дополнительные](import.md) или написать свой плагин, используя [руководство от markdown-it](https://github.com/markdown-it/markdown-it/tree/master/docs). 
diff --git a/ru/toc.yaml b/ru/toc.yaml
index 257ca569..90dce14f 100644
--- a/ru/toc.yaml
+++ b/ru/toc.yaml
@@ -209,8 +209,6 @@ items:
             href: plugins/index.md
           - name: Дополнительные
             href: plugins/import.md
-      - name: Расширения
-        href: plugins/extensions.md
       - name: Библиотека Mermaid
         href: tools/mermaid.md
         hidden: true

From 79ed8860a0dfe060752b2bcf56d4170cd4bb387e Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Wed, 29 Oct 2025 18:18:00 +0700
Subject: [PATCH 05/14] fix

---
 ru/_includes/plugins.md | 14 +++++++-------
 ru/plugins/import.md    | 11 +++++++----
 ru/plugins/index.md     |  5 -----
 3 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/ru/_includes/plugins.md b/ru/_includes/plugins.md
index c9455508..fe73cbe7 100644
--- a/ru/_includes/plugins.md
+++ b/ru/_includes/plugins.md
@@ -27,10 +27,10 @@
 Добавление [списка задач](../syntax/additional.md#tasks-list)
 |
 `divClass`: classname для `div`, который оборачивает чекбокс
-Тип: `string`, По умолчанию: `checkbox`
+Тип: `string`, по умолчанию: `checkbox`
 
 `idPrefix`: перфикс для id чекбокса
-Тип: `string`, По умолчанию: `checkbox`
+Тип: `string`, по умолчанию: `checkbox`
 |
 \-
 ||
@@ -40,16 +40,16 @@
 Добавление [изображений](../syntax/media.md#images)
 |
 `assetsPublicPath`: путь до иконок
-Тип: `string`, По умолчанию: `/` | \-
+Тип: `string` | \+
 ||
-|| **Imsize** | Задание размера изображений | \- | \- ||
+|| **Imsize** | Задание размера изображений | \- | \+ ||
 ||
 **Includes**
 |
 Переиспользование контента в документе
 |
 `getVarsPerFile`: функция, которая по пути к файлу возвращает вычисленные переменные
-Тип: `function`, По умолчанию: \-
+Тип: `function`, по умолчанию: \-
 |
 \-
 ||
@@ -62,7 +62,7 @@
 Поддержка разметки [заметок](../syntax/notes.md)
 |
 `lang`: язык для отображения типа заметки
-Тип: `string`, По умолчанию: ru
+Тип: `string`, по умолчанию: ru
 |
 \+
 ||
@@ -70,4 +70,4 @@
 || **Table** | Поддержка [многострочных таблиц](../syntax/tables/multiline.md) | \- | \+ ||
 || **Tabs** | Поддержка разметки [табов](../syntax/interactive-elements/tabs.md) | \- | \+ ||
 || **Video** | Добавление [видео](../syntax/media.md#video) | \- | \+ ||
-|#
\ No newline at end of file
+|#
diff --git a/ru/plugins/import.md b/ru/plugins/import.md
index 8c3d799a..74f17077 100644
--- a/ru/plugins/import.md
+++ b/ru/plugins/import.md
@@ -146,18 +146,21 @@ Alice <-- Bob: another authentication Response
 
 ### Эмодзи
 
-Плагин [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) добавляет поддержку эмодзи.
+Плагин [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) добавляет поддержку синтаксиса emoji и смайликов.
 
 **Установка:**
 
 ```bash
-npm i markdown-it-emoji
+npm install i markdown-it-emoji
 ```
 
 **Подключение:**
 
 ```javascript
-const emoji = require('markdown-it-emoji');
+import { full as emoji } from 'markdown-it-emoji'
+import markdownit from 'markdown-it'
+
+const md = markdownit().use(emoji/* , options */);
 
 // Для Transformer
 const {result: {html, meta}, logs} = transform(content, {
@@ -173,7 +176,7 @@ module.exports = [
 **Использование:**
 
 ```markdown
-:smile: :heart: :thumbsup:
+:smile: :heart: :thumbsup: :satellite:
 ```
 
 ### Математические формулы
diff --git a/ru/plugins/index.md b/ru/plugins/index.md
index d359ca8b..fc7861e0 100644
--- a/ru/plugins/index.md
+++ b/ru/plugins/index.md
@@ -41,15 +41,10 @@ Diplodoc предоставляет набор предустановленны
 
 **Использование:**
 
-```markdown
 - [x] ~~Написать пресс-релиз~~
 - [ ] Обновить веб-сайт  
 - [ ] Связаться со СМИ
-```
 
-**Параметры:**
-- `divClass` — CSS-класс для `div`, который оборачивает чекбокс (по умолчанию: `checkbox`)
-- `idPrefix` — префикс для id чекбокса (по умолчанию: `checkbox`)
 
 ## Список предустановленных плагинов
 

From 4e46f5cdb3a53e23f024f2682f88cb6fa1ed84f2 Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Wed, 29 Oct 2025 19:03:34 +0700
Subject: [PATCH 06/14] fix

---
 ru/plugins/import.md | 76 ++++++++++++++++++--------------------------
 1 file changed, 31 insertions(+), 45 deletions(-)

diff --git a/ru/plugins/import.md b/ru/plugins/import.md
index 74f17077..852e54bc 100644
--- a/ru/plugins/import.md
+++ b/ru/plugins/import.md
@@ -4,10 +4,12 @@ YFM использует [markdown-it](https://www.npmjs.com/package/markdown-it
 
 ## Подключение {#require}
 
-Перед подключением установите пакет с нужным плагином с помощью команды `npm i <имя_плагина>`. Например, чтобы установить [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji), выполните:
+Для примера рассмотрим подключение плагина [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) добавляет поддержку синтаксиса эмодзи и смайликов.
+
+Перед подключением установите пакет с нужным плагином с помощью команды `npm i <имя_плагина>`.
 
 ```shell
-npm i markdown-it-emoji
+npm install i markdown-it-emoji
 ```
 
 {% list tabs %}
@@ -20,13 +22,19 @@ npm i markdown-it-emoji
       git clone https://github.com/diplodoc-platform/cli.git
       ```
 
-  1. Установите зависимости и соберите проект:
+      Перейдите в папку cli:
+
+      ```bash
+      cd cli
+      ```
+
+  2. Установите зависимости и соберите проект:
 
       ```bash
       npm i && npm run build
       ```
 
-   1. Перейдите в папку `node_modules/@diplodoc/cli/build/plugins` и создайте файл `index.js` со следующим содержимым:
+   3. Перейдите в папку `node_modules/@diplodoc/cli/build/plugins` и создайте файл `index.js` со следующим содержимым:
  
       ```javascript
          const emojiPlugin = require('markdown-it-emoji');
@@ -83,6 +91,12 @@ npm i markdown-it-emoji
 
 {% endlist %}
 
+**Использование:**
+
+```markdown
+:smile: :heart: :thumbsup: :satellite:
+```
+
 ## Передача параметров {#options}
 
 YFM применяет неизвестные параметры из объекта `options` ко всем плагинам, поэтому для передачи параметров добавьте их в объект `options`.
@@ -93,7 +107,13 @@ YFM применяет неизвестные параметры из объек
 
 Плагин [markdown-it-plantuml](https://www.npmjs.com/package/markdown-it-plantuml) позволяет создавать UML-диаграммы прямо в Markdown.
 
-**Установка и настройка:**
+Установите пакет с плагином:
+
+   ```bash
+   npm install markdown-it-plantuml --save
+   ```
+
+**Подключение**:
 
 1. Склонируйте репозиторий CLI:
 
@@ -101,16 +121,17 @@ YFM применяет неизвестные параметры из объек
    git clone https://github.com/diplodoc-platform/cli.git
    ```
 
+   Перейдите в папку cli:
+
+      ```bash
+      cd cli
+      ```
+
 1. Установите зависимости и соберите проект:
 
    ```bash
    npm i && npm run build
    ```
-1. Установите пакет с плагином:
-
-    ```bash
-      npm install markdown-it-plantuml --save
-      ```
 
 1. Перейдите в папку `build` и создайте файл `index.js` со следующим содержимым:
 
@@ -144,41 +165,6 @@ Alice -> Bob: Another authentication Request
 Alice <-- Bob: another authentication Response
 @enduml
 
-### Эмодзи
-
-Плагин [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) добавляет поддержку синтаксиса emoji и смайликов.
-
-**Установка:**
-
-```bash
-npm install i markdown-it-emoji
-```
-
-**Подключение:**
-
-```javascript
-import { full as emoji } from 'markdown-it-emoji'
-import markdownit from 'markdown-it'
-
-const md = markdownit().use(emoji/* , options */);
-
-// Для Transformer
-const {result: {html, meta}, logs} = transform(content, {
-  plugins: [emoji]
-});
-
-// Для Builder (в build/plugins/index.js)
-module.exports = [
-  emoji
-];
-```
-
-**Использование:**
-
-```markdown
-:smile: :heart: :thumbsup: :satellite:
-```
-
 ### Математические формулы
 
 Плагин [markdown-it-katex](https://www.npmjs.com/package/markdown-it-katex) позволяет отображать математические формулы.

From 15f3467b3ac11f85199ada0f3f2a2b407812da8e Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Fri, 14 Nov 2025 20:14:00 +0700
Subject: [PATCH 07/14] fix

---
 .yfm                    |   5 ++
 ru/plugins/external.md  |  79 +++++++++++++++++
 ru/plugins/import.md    | 192 ----------------------------------------
 ru/plugins/index.md     |  69 ++++++---------
 ru/plugins/installed.md |  57 ++++++++++++
 ru/toc.yaml             |   7 +-
 6 files changed, 173 insertions(+), 236 deletions(-)
 create mode 100644 ru/plugins/external.md
 delete mode 100644 ru/plugins/import.md
 create mode 100644 ru/plugins/installed.md

diff --git a/.yfm b/.yfm
index ccd2e407..a9c3d063 100644
--- a/.yfm
+++ b/.yfm
@@ -11,6 +11,11 @@ interface:
 
 extensions:
   - github-vcs
+  - name: mdit-plugins
+    plugins:
+      - '@diplodoc/transform/lib/plugins/checkbox'
+      - "markdown-it-emoji"
+      - "markdown-it-katex"
 
 resources:
   style:
diff --git a/ru/plugins/external.md b/ru/plugins/external.md
new file mode 100644
index 00000000..33dbee62
--- /dev/null
+++ b/ru/plugins/external.md
@@ -0,0 +1,79 @@
+# Внешние плагины
+
+## Подключение {#require}
+
+Отличие внешних плагинов от встроенных в том, что перед подключением их нужно предварительно установить (`npm install`), а затем — добавить в секцию плагинов `mdit-plugins`.
+
+Для внешних плагинов в поле `plugins` указывется имя плагина.
+
+### Примеры подключения популярных плагинов
+
+#### Установка и настройка плагина [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji)
+
+Плагин добавляет поддержку синтаксиса эмодзи и смайликов.
+
+1. Склонируйте репозиторий CLI:
+
+    ```bash
+    git clone https://github.com/diplodoc-platform/cli.git
+    ```
+
+2. Установите зависимости и соберите проект:
+
+    ```bash
+    npm i && npm run build
+    ```
+
+3. Установите пакет с плагином:
+
+   ```bash
+   npm install i markdown-it-emoji
+   ```
+
+4. Добавьте в файл `.yfm` следующую конфигурацию:
+
+   ```yaml
+   extensions:
+   - name: mdit-plugins
+      plugins:
+         - "markdown-it-emoji"
+   ```
+
+**Использование:**
+
+```markdown
+:smile: :heart: :thumbsup: :satellite:
+```
+
+**Результат:**
+
+:smile: :heart: :thumbsup: :satellite:
+
+#### Математические формулы
+
+Плагин [markdown-it-katex](https://www.npmjs.com/package/markdown-it-katex) позволяет отображать математические формулы.
+
+**Установка:**
+
+```bash
+npm install i markdown-it-katex
+```
+
+**Подключение:**
+
+```yaml
+   extensions:
+   - name: mdit-plugins
+      plugins:
+         - "markdown-it-katex"
+   ```
+
+**Использование:**
+
+```markdown
+$\sqrt{3x-1}+(1+x)^2$
+```
+
+**Результат:**
+
+$\sqrt{3x-1}+(1+x)^2$
diff --git a/ru/plugins/import.md b/ru/plugins/import.md
deleted file mode 100644
index 852e54bc..00000000
--- a/ru/plugins/import.md
+++ /dev/null
@@ -1,192 +0,0 @@
-# Дополнительные плагины
-
-YFM использует [markdown-it](https://www.npmjs.com/package/markdown-it) в качестве парсера, поэтому вы можете подключить любой плагин из [списка плагинов для markdown-it](https://www.npmjs.com/search?q=keywords:markdown-it-plugin).
-
-## Подключение {#require}
-
-Для примера рассмотрим подключение плагина [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) добавляет поддержку синтаксиса эмодзи и смайликов.
-
-Перед подключением установите пакет с нужным плагином с помощью команды `npm i <имя_плагина>`.
-
-```shell
-npm install i markdown-it-emoji
-```
-
-{% list tabs %}
-
-- Builder
-  
-  1. Склонируйте репозиторий CLI:
-
-      ```bash
-      git clone https://github.com/diplodoc-platform/cli.git
-      ```
-
-      Перейдите в папку cli:
-
-      ```bash
-      cd cli
-      ```
-
-  2. Установите зависимости и соберите проект:
-
-      ```bash
-      npm i && npm run build
-      ```
-
-   3. Перейдите в папку `node_modules/@diplodoc/cli/build/plugins` и создайте файл `index.js` со следующим содержимым:
- 
-      ```javascript
-         const emojiPlugin = require('markdown-it-emoji');
-
-         // Плагины необходимо экспортировать в виде массива функций, а не как отдельные именованные экспорты.
-         // Экспортируем массив функций плагинов
-         module.exports = [
-         emojiPlugin.full, // Используем конкретную версию плагина
-         // Добавьте другие плагины при необходимости
-         ];
-         ```
-
-
-   {% note tip %}
-
-   Чтобы не переносить необходимые плагины перед каждой сборкой, соберите собственный Builder:
-   - Установите исходный код с [GitHub](https://github.com/yandex-cloud/yfm-docs).
-   - Перенесите дополнительные плагины в папку `./plugins`.
-   - Соберите Builder по [инструкции с GitHub](https://github.com/yandex-cloud/yfm-docs#installation-1).
-
-   {% endnote %}
-
-- Transformer
-
-   {% note warning %}
-
-   При переопределении параметра `plugins` необходимо заново подключать [плагины YFM](index.md). Для этого импортируйте их из пакета `@diplodoc/transform` и передайте в массиве плагинов.
-
-   {% endnote %}
-
-   1. Подключите плагин в своем коде с помощью функций `require()` или `import()`:
-
-      ```javascript
-      const plugin1 = require('markdown-it-emoji');
-      ```
-
-   2. В параметре `plugins` добавьте новый плагин в массив:
-   
-      ```javascript
-      const {result: {html, meta}, logs} = transform(content, {plugins: [markdown-it-emoji]});
-      ```
-
-   **Пример:**
-
-   ```javascript
-   const fs = require('fs');
-   const transform = require('@diplodoc/transform');
-   const cut = require('@diplodoc/transform/lib/plugins/cut');
-   const sup = require('@diplodoc/transform/lib/plugins/sup');
-   const emoji = require('markdown-it-emoji');
-   const content = fs.readFileSync(filePath, 'utf');
-   const {result: {html, meta}, logs} = transform(content, {plugins: [cut, sup, emoji]});
-   ```
-
-{% endlist %}
-
-**Использование:**
-
-```markdown
-:smile: :heart: :thumbsup: :satellite:
-```
-
-## Передача параметров {#options}
-
-YFM применяет неизвестные параметры из объекта `options` ко всем плагинам, поэтому для передачи параметров добавьте их в объект `options`.
-
-## Примеры подключения популярных плагинов
-
-### PlantUML диаграммы
-
-Плагин [markdown-it-plantuml](https://www.npmjs.com/package/markdown-it-plantuml) позволяет создавать UML-диаграммы прямо в Markdown.
-
-Установите пакет с плагином:
-
-   ```bash
-   npm install markdown-it-plantuml --save
-   ```
-
-**Подключение**:
-
-1. Склонируйте репозиторий CLI:
-
-   ```bash
-   git clone https://github.com/diplodoc-platform/cli.git
-   ```
-
-   Перейдите в папку cli:
-
-      ```bash
-      cd cli
-      ```
-
-1. Установите зависимости и соберите проект:
-
-   ```bash
-   npm i && npm run build
-   ```
-
-1. Перейдите в папку `build` и создайте файл `index.js` со следующим содержимым:
-
-   ```javascript
-   const plantuml = require('markdown-it-plantuml');
-   
-   module.exports = [
-     plantuml
-   ];
-   ```
-
-**Использование:**
-
-После настройки вы можете добавлять PlantUML диаграммы в любую Markdown страницу:
-
-```markdown
-@startuml
-Alice -> Bob: Authentication Request
-Bob --> Alice: Authentication Response
-Alice -> Bob: Another authentication Request
-Alice <-- Bob: another authentication Response
-@enduml
-```
-
-**Результат:**
-
-@startuml
-Alice -> Bob: Authentication Request
-Bob --> Alice: Authentication Response
-Alice -> Bob: Another authentication Request
-Alice <-- Bob: another authentication Response
-@enduml
-
-### Математические формулы
-
-Плагин [markdown-it-katex](https://www.npmjs.com/package/markdown-it-katex) позволяет отображать математические формулы.
-
-**Установка:**
-
-```bash
-npm i markdown-it-katex
-```
-
-**Подключение:**
-
-```javascript
-const katex = require('markdown-it-katex');
-
-const {result: {html, meta}, logs} = transform(content, {
-  plugins: [katex]
-});
-```
-
-**Использование:**
-
-```markdown
-$\sqrt{3x-1}+(1+x)^2$
-```
diff --git a/ru/plugins/index.md b/ru/plugins/index.md
index fc7861e0..41a7bc56 100644
--- a/ru/plugins/index.md
+++ b/ru/plugins/index.md
@@ -1,53 +1,40 @@
-# Предустановленные плагины
+# Плагины в Diplodoc
 
-Diplodoc предоставляет набор предустановленных плагинов, которые расширяют базовый синтаксис [CommonMark Spec](https://spec.commonmark.org/) дополнительными возможностями и уникальными элементами разметки.
+Diplodoc предоставляет расширенные возможности разметки Markdown с помощью системы плагинов. Плагины позволяют дополнять базовый синтаксис [CommonMark Spec](https://spec.commonmark.org/) уникальными элементами разметки и новыми возможностями для ваших технических и проектных документов.
 
-## Подключение и настройка
+Доступны два типа плагинов:
 
-Большинство предустановленных плагинов подключены по умолчанию. Однако некоторые требуют явного подключения.
+- [Предустановленные плагины](installed.md) – включены в Diplodoc. Часть из них активируется по умолчанию, часть можно включить при необходимости.
+- [Внешние плагины](external.md) – могут быть скачаны, установлены отдельно и затем подключены к вашему проекту.
+Diplodoc использует парсер [markdown-it](https://www.npmjs.com/package/markdown-it), поэтому вы можете подключить любой плагин из [списка плагинов для markdown-it](https://www.npmjs.com/search?q=keywords:markdown-it-plugin).
 
-### Пример подключения
+Отличие встроенных от внешних плагинов в том, что первые нужно только подключить в конфигурации, а вторые — сначала установить через менеджер пакетов [npm](https://www.npmjs.com/package/npm), а затем подключить.
 
-**Установка и настройка плагина `Tasks list` (списки задач)**.
-Плагин для создания интерактивных списков задач уже входит в состав Diplodoc, но требует явного подключения.
+## Как подключить плагины
 
-1. Склонируйте репозиторий CLI:
+В Diplodoc для подключения плагинов используется встроенное расширение `mdit-plugins`. Управление подключением осуществляется через файл конфигурации `.yfm` вашего проекта. Вам достаточно добавить или изменить секцию `extensions` следующим образом:
 
-    ```bash
-    git clone https://github.com/diplodoc-platform/cli.git
-    ```
 
-1. Установите зависимости и соберите проект:
+```yaml
+extensions:
+	- name: mdit-plugins # включаем встроенное в CLI расширение для подключения плагинов к markdown-it
+      plugins:
+      	- "имя плагина" # если у плагина нет параметров - можно указать его имя строкой
+		    - name: "имя плагина" # если у плагина есть какие-то параметры или нужно что-то еще прописать, тогда используется полная форма передачи
+          options: ...список опций плагина, которые у каждого могут отличаться...
+```
 
-    ```bash
-    npm i && npm run build
-    ```
+Если плагин экспортирует свой код не через `export default`, а через именованный экспорт — например, `export const somename = ...,` — укажите имя такого экспорта в поле `exportName`. Например, для [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) (у которого несколько вариантов экспорта: full, light, bare) потребуется явно указать нужный экспорт:
 
-1. Установите пакет с плагином:
 
-    ```bash
-      npm i markdown-it-task-lists
-      ```
+```yaml
+extensions:
+  - name: mdit-plugins
+    plugins:
+      - name: markdown-it-emoji
+        exportName: full # Доступные значения: full, light, bare
+```
 
-1. Перейдите в папку `node_modules/@diplodoc/cli/build/plugins` и создайте файл `index.js` со следующим содержимым:
-  
-    ```javascript
-    const checkbox = require('@diplodoc/transform/lib/plugins/checkbox');
-
-    module.exports = [
-     checkbox
-    ];
-    ```
-
-**Использование:**
-
-- [x] ~~Написать пресс-релиз~~
-- [ ] Обновить веб-сайт  
-- [ ] Связаться со СМИ
-
-
-## Список предустановленных плагинов
-
-{% include [plugins.md](../_includes/plugins.md) %}
-
-Выше перечислены плагины, включенные в пакет YFM. Но вы можете [подключить дополнительные](import.md) или написать свой плагин, используя [руководство от markdown-it](https://github.com/markdown-it/markdown-it/tree/master/docs). 
+Подробней про подключение плагинов читайте в разделах:
+- [Предустановленные плагины](installed.md)
+- [Внешние плагины](external.md)
diff --git a/ru/plugins/installed.md b/ru/plugins/installed.md
new file mode 100644
index 00000000..9dace2e3
--- /dev/null
+++ b/ru/plugins/installed.md
@@ -0,0 +1,57 @@
+# Предустановленные плагины
+
+## Подключение {#require}
+
+Для предустановленных плагинов вместо имени npm-пакета в поле `plugins` указывается путь до файла внутри Diplodoc CLI. Например, для чекбоксов (список задач):
+
+```yaml
+extensions:
+  - name: mdit-plugins
+    plugins:
+      - '@diplodoc/transform/lib/plugins/checkbox'
+```
+
+### Пример подключения
+
+**Установка и настройка плагина `Tasks list` (списки задач)**.
+
+Плагин для создания интерактивных списков задач входит в состав Diplodoc, но требует явного подключения.
+
+**Подключение:**
+
+1. Склонируйте репозиторий CLI:
+
+    ```bash
+    git clone https://github.com/diplodoc-platform/cli.git
+    ```
+
+1. Установите зависимости и соберите проект:
+
+    ```bash
+    npm i && npm run build
+    ```
+
+1. Добавьте в файл `.yfm` следующую конфигурацию:
+
+    ```yaml
+    extensions:
+    - name: mdit-plugins
+        plugins:
+        - '@diplodoc/transform/lib/plugins/checkbox'
+    ```
+
+**Использование:**
+
+После подключения вы можете создавать интерактивные списки задач:
+
+```markdown
+- [x] ~~Написать пресс-релиз~~
+- [ ] Обновить веб-сайт  
+- [ ] Связаться со СМИ
+```
+
+**Результат:**
+
+- [x] ~~Написать пресс-релиз~~
+- [ ] Обновить веб-сайт  
+- [ ] Связаться со СМИ
diff --git a/ru/toc.yaml b/ru/toc.yaml
index 90dce14f..1e2f701a 100644
--- a/ru/toc.yaml
+++ b/ru/toc.yaml
@@ -204,11 +204,12 @@ items:
     labeled: true
     items:
       - name: Плагины
+        href: plugins/index.md
         items:
           - name: Предустановленные
-            href: plugins/index.md
-          - name: Дополнительные
-            href: plugins/import.md
+            href: plugins/installed.md
+          - name: Внешние
+            href: plugins/external.md
       - name: Библиотека Mermaid
         href: tools/mermaid.md
         hidden: true

From c6e1a5a07d79ae544023d6ef03ad523d94bc3e1c Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Fri, 14 Nov 2025 20:22:27 +0700
Subject: [PATCH 08/14] fix

---
 .yfm | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/.yfm b/.yfm
index a9c3d063..ccd2e407 100644
--- a/.yfm
+++ b/.yfm
@@ -11,11 +11,6 @@ interface:
 
 extensions:
   - github-vcs
-  - name: mdit-plugins
-    plugins:
-      - '@diplodoc/transform/lib/plugins/checkbox'
-      - "markdown-it-emoji"
-      - "markdown-it-katex"
 
 resources:
   style:

From 67c98b17534f961f5e998d2bd4651ea7bb52d85b Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Fri, 14 Nov 2025 20:30:39 +0700
Subject: [PATCH 09/14] fix

---
 .yfm                   | 6 ++++++
 ru/plugins/external.md | 4 ++--
 ru/plugins/index.md    | 3 +--
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/.yfm b/.yfm
index ccd2e407..21bf1f10 100644
--- a/.yfm
+++ b/.yfm
@@ -11,6 +11,12 @@ interface:
 
 extensions:
   - github-vcs
+  - name: mdit-plugins
+    plugins:
+        - "markdown-it-emoji"
+        - '@diplodoc/transform/lib/plugins/checkbox'
+        - "markdown-it-katex"
+  
 
 resources:
   style:
diff --git a/ru/plugins/external.md b/ru/plugins/external.md
index 33dbee62..ca254545 100644
--- a/ru/plugins/external.md
+++ b/ru/plugins/external.md
@@ -8,7 +8,7 @@
 
 ### Примеры подключения популярных плагинов
 
-#### Установка и настройка плагина [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji)
+**Установка и настройка плагина [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji)**
 
 Плагин добавляет поддержку синтаксиса эмодзи и смайликов.
 
@@ -49,7 +49,7 @@
 
 :smile: :heart: :thumbsup: :satellite:
 
-#### Математические формулы
+**Математические формулы**
 
 Плагин [markdown-it-katex](https://www.npmjs.com/package/markdown-it-katex) позволяет отображать математические формулы.
 
diff --git a/ru/plugins/index.md b/ru/plugins/index.md
index 41a7bc56..96bb136a 100644
--- a/ru/plugins/index.md
+++ b/ru/plugins/index.md
@@ -14,14 +14,13 @@ Diplodoc использует парсер [markdown-it](https://www.npmjs.com/p
 
 В Diplodoc для подключения плагинов используется встроенное расширение `mdit-plugins`. Управление подключением осуществляется через файл конфигурации `.yfm` вашего проекта. Вам достаточно добавить или изменить секцию `extensions` следующим образом:
 
-
 ```yaml
 extensions:
 	- name: mdit-plugins # включаем встроенное в CLI расширение для подключения плагинов к markdown-it
       plugins:
       	- "имя плагина" # если у плагина нет параметров - можно указать его имя строкой
 		    - name: "имя плагина" # если у плагина есть какие-то параметры или нужно что-то еще прописать, тогда используется полная форма передачи
-          options: ...список опций плагина, которые у каждого могут отличаться...
+          options: #...список опций плагина, которые у каждого могут отличаться...
 ```
 
 Если плагин экспортирует свой код не через `export default`, а через именованный экспорт — например, `export const somename = ...,` — укажите имя такого экспорта в поле `exportName`. Например, для [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) (у которого несколько вариантов экспорта: full, light, bare) потребуется явно указать нужный экспорт:

From 15bea1983ba60709574504497e7702a9b141f33d Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Fri, 14 Nov 2025 20:39:20 +0700
Subject: [PATCH 10/14] fix

---
 ru/index-yfm.md         | 2 +-
 ru/syntax/additional.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/ru/index-yfm.md b/ru/index-yfm.md
index 786a24f1..0ea9a0e2 100644
--- a/ru/index-yfm.md
+++ b/ru/index-yfm.md
@@ -7,7 +7,7 @@
 * соответствует [CommonMark Spec](https://spec.commonmark.org/);
 * предоставляет собственный [набор плагинов](./plugins/index.md) с дополнительными возможностями и элементами разметки;
 * [быстрый](https://www.npmjs.com/package/markdown-it#benchmark);
-* расширяемый: можно [подключить](./plugins/import.md) любой плагин для markdown-it или [написать свой](https://github.com/markdown-it/markdown-it/tree/master/docs);
+* расширяемый: можно [подключить](./plugins/index.md) любой плагин для markdown-it или [написать свой](https://github.com/markdown-it/markdown-it/tree/master/docs);
 * безопасный: по умолчанию HTML экранируется;
 * использует динамическую валидацию;
 * позволяет собрать документационный проект.
diff --git a/ru/syntax/additional.md b/ru/syntax/additional.md
index a93fd6e5..f7b52dac 100644
--- a/ru/syntax/additional.md
+++ b/ru/syntax/additional.md
@@ -2,7 +2,7 @@
 
 Ниже перечислены элементы разметки, которые не поддерживаются по умолчанию, но могут быть подключены с помощью [плагинов markdown-it](https://www.npmjs.com/search?q=keywords:markdown-it-plugin).
 
-О том, как подключить дополнительный плагин, читайте в [инструкции](../plugins/import.md).
+О том, как подключить дополнительный плагин, читайте в [инструкции](../plugins/index.md).
 
 ## Нижний регистр {#sub}
 

From 31bf4e1296bfb96fc4c9a989dd677f97ff495f8a Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Fri, 14 Nov 2025 20:54:31 +0700
Subject: [PATCH 11/14] fix

---
 ru/toc.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/ru/toc.yaml b/ru/toc.yaml
index 1e2f701a..bf2f4e2c 100644
--- a/ru/toc.yaml
+++ b/ru/toc.yaml
@@ -203,6 +203,8 @@ items:
   - name: Инструменты и библиотеки
     labeled: true
     items:
+      - name: Расширения
+        href: extensions/index.md
       - name: Плагины
         href: plugins/index.md
         items:

From 5250eef03475a9a0f6d3482cbdaf91cdf4451016 Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Fri, 14 Nov 2025 20:56:01 +0700
Subject: [PATCH 12/14] fix

---
 ru/extensions/index.md | 58 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 ru/extensions/index.md

diff --git a/ru/extensions/index.md b/ru/extensions/index.md
new file mode 100644
index 00000000..b38a5e01
--- /dev/null
+++ b/ru/extensions/index.md
@@ -0,0 +1,58 @@
+# Расширения Diplodoc
+
+Расширения предназначены для дополнения функциональности Diplodoc новыми возможностями.
+
+## Установка {#install}
+
+Перед использованием расширения его необходимо загрузить. Это можно сделать с использованием `npm` через команду `npm install ...` или сохранив локально файлы расширения, что подходит – в том числе – для использования расширений [собственной разработки](../dev/extensions-api.md).
+
+Пример — установка расширения для [подключения Algolia](../project/algolia.md):
+```
+npm install @diplodoc/algolia-extension
+```
+
+## Подключение {#usage}
+
+Подключить расширение к проекту можно одним из двух способов:
+
+1. Прописав его в `.yfm` проекта в [параметре](../settings.md#extensions) ##extensions##:
+    ```yaml
+    extensions:
+        - @diplodoc/algolia-extension
+        - /local/path/to/extension
+    ```
+2. Передав через параметр `-e` при вызове `yfm`:
+    ```
+    yfm build -e @diplodoc/algolia-extension
+    ```
+
+{% note info %}
+
+Если расширение прописано для подключения, но недоступно, команда `yfm` будет выполнена с ошибкой.
+
+Если расширение не подключено при выполнении команды yfm, но необходимо для корректной обработки проекта, команда `yfm` может быть выполнена с корректным кодом ответа, но с непредсказуемым результатом.
+
+{% endnote %}
+
+## Встроенные расширения {#built-in}
+
+В Diplodoc встроено несколько расширений в качестве примеров работы Extensions API:
+
+#|
+|| **Название** | **Описание** ||
+||
+`github-vcs`
+|
+Получает информацию о [дате изменения](../settings.md#vcs-mtimes) и [авторах](../settings.md#vcs-authors) из репозитория Github при сборке проекта для размещения в контенте статей.
+||
+||
+`local-search`
+|
+Добавляет в проект [локальный поиск](../project/lunr.md) на базе lunr.js.
+||
+||
+`mdit-plugins`
+|
+Добавляет в парсер markdown-it [дополнительные плагины](../plugins/import.md) для расширения возможностей разметки документации.
+||
+|#
\ No newline at end of file

From b90696be70268c235fc500780c71f3e4cac583b6 Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Fri, 14 Nov 2025 20:56:40 +0700
Subject: [PATCH 13/14] fix

---
 ru/extensions/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ru/extensions/index.md b/ru/extensions/index.md
index b38a5e01..e00e8e0d 100644
--- a/ru/extensions/index.md
+++ b/ru/extensions/index.md
@@ -53,6 +53,6 @@ npm install @diplodoc/algolia-extension
 ||
 `mdit-plugins`
 |
-Добавляет в парсер markdown-it [дополнительные плагины](../plugins/import.md) для расширения возможностей разметки документации.
+Добавляет в парсер markdown-it [дополнительные плагины](../plugins/index.md) для расширения возможностей разметки документации.
 ||
 |#
\ No newline at end of file

From db5025d581cae04a064b305857696a412a5fac5e Mon Sep 17 00:00:00 2001
From: Konstantin <potapenko-k@yandex-team.ru>
Date: Tue, 18 Nov 2025 15:28:00 +0700
Subject: [PATCH 14/14] fix

---
 ru/plugins/index.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/ru/plugins/index.md b/ru/plugins/index.md
index 96bb136a..f49652d8 100644
--- a/ru/plugins/index.md
+++ b/ru/plugins/index.md
@@ -37,3 +37,4 @@ extensions:
 Подробней про подключение плагинов читайте в разделах:
 - [Предустановленные плагины](installed.md)
 - [Внешние плагины](external.md)
+