english | русский
Core transformation package for the Diplodoc platform. Converts Yandex Flavored Markdown (YFM) to HTML with support for interactive components and extensible plugin architecture.
Use it in your code to work with text during program execution. For example, to display user-generated content.
- YFM to HTML transformation — Core markdown processing with YFM extensions
- Plugin system — Extensible architecture using extension packages (cut, tabs, file)
- Client-side runtime — Interactive components (tabs, cuts, terms, anchors, etc.)
- SCSS styles — Comprehensive styling system with CSS variables
- Multiple output formats — HTML, metadata, titles, headings
- HTML sanitization — Built-in XSS protection with customizable sanitizer
Note: Liquid template support and YFMLint integration are deprecated. Use separate packages (
@diplodoc/liquidand@diplodoc/yfmlint) instead.
-
Install a package:
npm i @diplodoc/transform
-
Add the package in your code using the
require()orimport()function:const transform = require('@diplodoc/transform');
-
To ensure text is displayed properly, add CSS styles and client scripts to the project:
@import '~@diplodoc/transform/dist/css/yfm.css';
import '@diplodoc/transform/dist/js/yfm';
The package provides the transform() function:
- Input data: Settings and a string with YFM.
- Returned value: An object with the
resultandlogsfields.
result: Resulting object, contains the fields:
html: A line with HTML.meta: Metadata from the transmitted content.title: The document title. Returned ifextractTitle = trueorneedTitle = true.headings: A list of document headers.
logs: Information about the transformation process, includes arrays:
error: Errors.warn: Warnings.info: Additional information.
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});You can replace the default HTML sanitizer with your own implementation by providing a sanitize function in the options:
const customSanitizer = (html, options) => {
// Your custom sanitization logic here
return sanitizedHtml;
};
const {result} = transform(content, {
sanitize: customSanitizer,
// Other options...
});This is useful when you need to implement specific sanitization rules or integrate with a different sanitization library. The sanitizer function should accept HTML string as input and return sanitized HTML.
MIT
common
--yfm-color-text--yfm-color-link--yfm-color-base--yfm-color-link-hover--yfm-color-border--yfm-color-accent--yfm-tab-size--yfm-text-block-margin-block--yfm-text-block-margin-inline--yfm-font-size--yfm-font-line-height--yfm-font-size-h1--yfm-font-line-height-h1--yfm-font-size-h2--yfm-font-line-height-h2--yfm-font-size-h3--yfm-font-line-height-h3--yfm-font-size-h4--yfm-font-line-height-h4--yfm-font-size-h5--yfm-font-line-height-h5--yfm-font-size-h6--yfm-font-line-height-h6
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
table
--yfm-color-table--yfm-color-table-border--yfm-color-table-background--yfm-color-table-head-background--yfm-color-table-stripe-row-background
# Install dependencies
npm install
# Build server-side code
npm run build:lib
# Build client-side assets
npm run build:dist
# Build both
npm run build
# Run unit tests
npm test
# Type check
npm run typecheck
# Lint code
npm run lint# Watch mode for server-side code
npm run dev:lib
# Start playground (interactive YFM testing)
npm run playgroundThis package features unit tests run by Jest (to be migrated to Vitest) and e2e & visual tests run by Playwright. Playwright tests are located in e2e sub-package.
To ensure maximum reproducibility and to avoid unwanted variance introduced by using different platforms
between CI environments and contributors' dev environments, it is recommended to run Playwright tests locally using
the test:playwright package script, which sets up a testing environment in a Docker container.
$ npm run test:playwrightThis assumes you have Docker CLI and Docker Engine installed.
To use Playwright in UI mode, instead use the playwright:docker:ui script:
$ cd e2e
$ npm run playwright:docker:uiDue to somewhat recent licensing changes, using Docker Desktop in enterprise setting is not free anymore. Consider using Lima or some of its wrappers, such as Colima or Rancher Desktop.
You can pass a LIMA_INSTANCE environment variable to playwright:docker/test:playwright:
$ LIMA_INSTANCE=instancename npm run test:playwrightThis ensures the DOCKER_HOST is set as necessary.
For detailed information about architecture, development, and contributing, see AGENTS.md.