Skip to content

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

License

Notifications You must be signed in to change notification settings

yndx-birman/yfm-transform

 
 

Repository files navigation

NPM version

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

Yandex Flavored Markdown

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

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

Для сборки своего документационного проекта на YFM вы можете использовать пакет @doc-tools/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

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 90.9%
  • CSS 9.1%