DOCSUP-116726

.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:

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) | \- | \+ ||
+|#

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) для расширения возможностей разметки документации.
 ||
 |#

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 экранируется;
 * использует динамическую валидацию;
 * позволяет собрать документационный проект.

ru/index.yaml

@@ -110,7 +110,7 @@ blocks:
         text: |
           [Transformer](tools/transform/index.md)
 
-          [Плагины](plugins/index.md)
+          [Плагины](plugins/)
 
       - type: basic-card
         title: 

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$

ru/plugins/index.md

@@ -1,13 +1,40 @@
-# Плагины
+# Плагины в Diplodoc
 
-Кроме базового синтаксиса [CommonMark Spec](https://spec.commonmark.org/), YFM предоставляет набор плагинов с дополнительными возможностями и уникальными элементами разметки.
+Diplodoc предоставляет расширенные возможности разметки Markdown с помощью системы плагинов. Плагины позволяют дополнять базовый синтаксис [CommonMark Spec](https://spec.commonmark.org/) уникальными элементами разметки и новыми возможностями для ваших технических и проектных документов.
 
-{% note warning %}
+Доступны два типа плагинов:
 
-Порядок добавления плагинов важен. При добавлении плагинов необходимо указывать полный набор плагинов.
+- [Предустановленные плагины](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).
 
-{% endnote %}
+Отличие встроенных от внешних плагинов в том, что первые нужно только подключить в конфигурации, а вторые — сначала установить через менеджер пакетов [npm](https://www.npmjs.com/package/npm), а затем подключить.
 
-{% include [plugins.md](../_includes/plugins.md) %}
+## Как подключить плагины
+
+В Diplodoc для подключения плагинов используется встроенное расширение `mdit-plugins`. Управление подключением осуществляется через файл конфигурации `.yfm` вашего проекта. Вам достаточно добавить или изменить секцию `extensions` следующим образом:
+
+```yaml
+extensions:
+	- name: mdit-plugins # включаем встроенное в CLI расширение для подключения плагинов к markdown-it
+      plugins:
+      	- "имя плагина" # если у плагина нет параметров - можно указать его имя строкой
+		    - name: "имя плагина" # если у плагина есть какие-то параметры или нужно что-то еще прописать, тогда используется полная форма передачи
+          options: #...список опций плагина, которые у каждого могут отличаться...
+```
+
+Если плагин экспортирует свой код не через `export default`, а через именованный экспорт — например, `export const somename = ...,` — укажите имя такого экспорта в поле `exportName`. Например, для [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji) (у которого несколько вариантов экспорта: full, light, bare) потребуется явно указать нужный экспорт:
+
+
+```yaml
+extensions:
+  - name: mdit-plugins
+    plugins:
+      - name: markdown-it-emoji
+        exportName: full # Доступные значения: full, light, bare
+```
+
+Подробней про подключение плагинов читайте в разделах:
+- [Предустановленные плагины](installed.md)
+- [Внешние плагины](external.md)
 
-Выше перечислены плагины, включенные в пакет YFM. Но вы можете [подключить дополнительные](import.md) или написать свой плагин, используя [руководство от markdown-it](https://github.com/markdown-it/markdown-it/tree/master/docs).