Простой трансформер текста на YFM (Yandex Flavored Markdown) в HTML.

Yandex Flavored Markdown

Yandex Flavored Markdown (YFM) является диалектом Markdown, который используется сейчас для документации Яндекс.Облака, контента сайта Я.Облака и в различных внутренних проектах Яндекса.

Синтаксис базируется на CommonMark Spec, расширяя его дополнительными возможностями. В том числе, для создания полноценного сложного документационного проекта, такого как документация Яндекс.Облака.

Для сборки своего документационного проекта на YFM вы можете использовать пакет yfm-docs.

Более подробное описание синтаксиса YFM

Использование

Параметры

Имя | Описание | Тип | Значение по-умолчанию :--- | :--- | :--- | :--- vars | Переменные | Object | {} plugins | Используемые плагины | function[] | alerts, attrs, anchors, code, cut, deflist, imsize, meta, sup, tabs, titles highlightLangs | Дополнительные языки для подсветки | {'lang': function} | {} extractTitle | Вернуть первый заголовок первого уровня в качестве заголовка всего документа | bool | false needTitle | Вернуть первый заголовок первого уровня не удалив его из контента | bool | false allowHTML | Разрешено ли использование HTML | bool | false linkify | Делать ли ссылками ссылкоподобные строки | bool | false breaks | Переносить ли строки по символу перевода каретки | bool | true conditionsInCode | Выполнять ли условия в блоках кода | bool | false

Подключение и вызов

Трансформер возвращает результат преобразования и лог, разделенный по типу сообщения: ошибки, предупреждения и информационные. Вы можете обработать сообщения об ошибках и предупреждениях исходя из необходимого вам уровня строгости.

const fs = require('fs');
const transform = require('@yfm/transform');

const content = fs.readFileSync(filePath, 'utf');
const vars = { user: { name: 'Alice' } };

const {result: {html, meta}, logs} = transform(content, {vars});

Плагины

Вы можете использовать произвольный набор плагинов, как предоставленные этим пакетом, так и любые markdown-it плагины

const fs = require('fs');
const transform = require('@yfm/transform');
const {plugins: {cut, sup}} = require('@yfm/transform');
const video = require('markdown-it-video');

const content = fs.readFileSync(filePath, 'utf');
const vars = { user: { name: 'Alice' } };

const {result: {html, meta}, logs} = transform(content, {vars, plugins: [cut, sup, video]});

Предоставляемые плагины

Имя | Описание | Параметры :--- | :--- | :--- anchors | Добавляет якоря заголовкам | {extractTitleOption? = false - нужно ли учитывать заголовок первого уровня} code | Добавляет кнопку копирования в блоки кода | - cut | Сворачиваемые блоки | - images | Вставка изображений | {assetsPublicPath = '/' - путь до расположения иконок, root - путь до корня проекта, path - путь до текущего трансформируемого файла} includes | Вставки | {path - путь до текущего трансформируемого файла, getVarsPerFile? - функция, которая должна по пути файла вернуть вычисленные переменные} links | Расширенные ссылки | {path - путь до текущего трансформируемого файла, root - путь до корня проекта} notes | Заметки | {lang? = ru - язык, нужен для локализации дефолтных текстов} tabs | Табы | -

Набор плагинов подключаемый по умолчанию: attrs, meta, deflist, cut, alerts, anchors, tabs, code, imsize, sup.

Все плагины принимают опциональным параметром path путь до файла, который будет добавлен в лог ошибок.

Дополнительные языки для подсветки

Трансформер YFM использует highlight.js для подсветки языков. Вы можете передать дополнительный набор языков, который будет зарегистрирован для использования. Набор языков представляет собой обьект, где ключ - это имя языка, а значение - функция, определяющая язык. Смотрите уже существующие языки.

const transform = require('@yfm/transform');
const customLang = require('./custom-lang');

const highlightLangs = { 'custom-lang': customLang };

const {result: {html, meta}, logs} = transform(content, {highlightLangs});

Исходники

Установка

git clone [email protected]:yandex-cloud/yfm-transform.git
cd yfm-transform
npm install

При добавлении изменений в файлы из директории src перед обновлением версии пакета нужно выполнить

npm run dist

License

MIT