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/_includes/plugins.md b/ru/_includes/plugins.md index 8f8c0139..fe73cbe7 100644 --- a/ru/_includes/plugins.md +++ b/ru/_includes/plugins.md @@ -1,20 +1,73 @@ #| -|| Название плагина | Описание | Параметры | Подключен по умолчанию | -|| **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 +|| **Название плагина** | **Описание** | **Параметры** | **Подключен по умолчанию** || +|| **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) | \- | \+ || +|# 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 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/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/external.md b/ru/plugins/external.md new file mode 100644 index 00000000..ca254545 --- /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 01af15f5..00000000 --- a/ru/plugins/import.md +++ /dev/null @@ -1,74 +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} - -Перед подключением установите пакет с нужным плагином с помощью команды `npm i <имя_плагина>`. Например, чтобы установить [markdown-it-emoji](https://www.npmjs.com/package/markdown-it-emoji), выполните: - -```shell -npm i markdown-it-emoji -``` - -{% list tabs %} - -- Transformer - - {% note warning %} - - При переопределении параметра `plugins` необходимо заново подключать [плагины YFM](index.md). Для этого импортируйте их из пакета `@diplodoc/transform` и передайте в массиве плагинов. - - {% endnote %} - - 1. Подключите плагин в своем коде с помощью функций `require()` или `import()`: - ```javascript - const plugin1 = require('<имя_плагина>'); - ``` - - 1. В параметре `plugins` добавьте новый плагин в массив: - ```javascript - const {result: {html, meta}, logs} = transform(content, {plugins: [<имя_плагина>]}); - ``` - - **Пример:** - ```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]}); - ``` - - -- 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} - -YFM применяет неизвестные параметры из объекта `options` ко всем плагинам, поэтому для передачи параметров добавьте их в объект `options`. diff --git a/ru/plugins/index.md b/ru/plugins/index.md index caec6a22..f49652d8 100644 --- a/ru/plugins/index.md +++ b/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). 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/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} diff --git a/ru/toc.yaml b/ru/toc.yaml index be693873..bf2f4e2c 100644 --- a/ru/toc.yaml +++ b/ru/toc.yaml @@ -208,8 +208,10 @@ items: - name: Плагины href: plugins/index.md items: - - name: Дополнительные плагины - href: plugins/import.md + - name: Предустановленные + href: plugins/installed.md + - name: Внешние + href: plugins/external.md - name: Библиотека Mermaid href: tools/mermaid.md hidden: true