@diplodoc/transform NPM

русский | english

@diplodoc/transform — пакет для трансформации Yandex Flavored Markdown в HTML.

Используйте его в своем коде для работы с текстом во время выполнения программы. Например, чтобы отображать пользовательский контент.

Установка {#install}

Установите пакет:
```
npm i @diplodoc/transform
```
Подключите пакет в своем коде, используя функцию require() или import():
```
const transform = require('@diplodoc/transform');
```
Для корректного отображения подключите в проект CSS-стили и клиентские скрипты:
```
@import '~@diplodoc/transform/dist/css/yfm.css';
```
```
import '@diplodoc/transform/dist/js/yfm';
```

Использование {#use}

Пакет предоставляет функцию transform():

входные данные — строка с YFM и настройки;
возвращаемое значение — объект с полями result и logs.

Поле result

result — объект результата, содержит поля:

html — строка с HTML.
meta — метаданные из переданного контента.
title — заголовок документа. Возвращается, если заданы настройки extractTitle = true или needTitle = true.
headings — список заголовков документа.

Поле logs

logs — информация о процессе трансформации, включает массивы:

error — ошибки.
warn — предупреждения.
info — дополнительная информация.

Пример вызова функции

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

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

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

Пользовательский HTML-санитайзер

Вы можете заменить стандартный HTML-санитайзер своей собственной реализацией, передав функцию sanitize в опциях:

const customSanitizer = (html, options) => {
  // Ваша логика санитизации
  return sanitizedHtml;
};

const {result} = transform(content, {
  sanitize: customSanitizer,
  // Другие опции...
});

Это полезно, когда вам нужно реализовать специфические правила санитизации или интегрироваться с другой библиотекой санитизации. Функция санитайзера должна принимать HTML-строку в качестве входных данных и возвращать санитизированный HTML.

License

MIT

Публичные CSS-переменные

common

--yfm-color-text
--yfm-color-link
--yfm-color-base
--yfm-color-link-hover
--yfm-color-table
--yfm-color-table-row-background
--yfm-color-border
--yfm-color-accent
--yfm-tab-size
--yfm-text-block-margin-block
--yfm-text-block-margin-inline

code

--yfm-color-inline-code
--yfm-color-inline-code-background
--yfm-color-code-background
--yfm-tab-size-code

hightlight

--yfm-color-hljs-background
--yfm-color-hljs-subst
--yfm-color-hljs-comment
--yfm-color-hljs-deletion
--yfm-color-hljs-section
--yfm-color-hljs-pseudo
--yfm-color-hljs-literal
--yfm-color-hljs-addition
--yfm-color-hljs-meta
--yfm-color-hljs-meta-string

note

--yfm-color-note-tip
--yfm-color-note-tip-background
--yfm-color-note-warning
--yfm-color-note-warning-background
--yfm-color-note-important-background
--yfm-color-note-info
--yfm-color-note-info-background

term

--yfm-color-term-title
--yfm-color-term-title-hover
--yfm-color-term-dfn-background
--yfm-color-term-dfn-shadow
--yfm-color-term-dfn-pseudo-shadow

modal

--yfm-color-modal-content
--yfm-color-modal-actions-hover
--yfm-color-modal-wide-content
--yfm-color-modal-wide-content-overlay

file

--yfm-file-icon
--yfm-file-icon-color

list

--yfm-list-item-margin-block
--yfm-list-text-margin-block
--yfm-list-text-only-margin-block
--yfm-list-text-last-margin-block

Контрибуции

Тесты

В пакете представлены unit-тесты на базе Jest и визуальные e2e-тесты на базе Playwright. Playwright-тесты расположены в подпакете e2e.

Playwright: prerequisites

Для того, чтобы обеспечить минимальное количество внешних факторов, которые могут повлиять на выполнение e2e-тестов, рекомендуется запускать локально Playwright-тесты в Docker-контейнере с помощью скрипта пакета test:playwright. Этот скрипт настроит необходимое окружение в Docker и установит все зависимости для него.

$ npm run test:playwright

Подразумевается, что у вас установлен Docker CLI и Docker Engine.

Для того, чтобы использовать UI-режим Playwright, используйте скрипт playwright:docker:ui (в подпакете e2e):

$ cd e2e
$ npm run playwright:docker:ui

Пользователям macOS: не хотите/не имеете возможность использовать Docker Desktop?

Благодаря относительно недавним изменениям лицензии, использование Docker Desktop в коммерческих условиях больше не является бесплатным. Используйте Lima или одну из обёрток, таких как Colima или Rancher Desktop.

Если при настройке вы выбрали имя инстанса не docker, можете передать нужное с помощью переменной LIMA_INSTANCE при обращении к скрипту playwright:docker/test:playwright:

$ LIMA_INSTANCE=instancename npm run test:playwright

Эта информация необходима скрипту, чтобы корректно настроить переменную окружения DOCKER_HOST.