@diplodoc/transform

@diplodoc/transform is a package for converting Yandex Flavored Markdown to HTML.

Use it in your code to work with text during program execution. For example, to display user-generated content.

Installation {#install}

Install a package:
```
npm i @diplodoc/transform
```
Add the package in your code using the require() or import() 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';

Usage {#use}

The package provides the transform() function:

Input data: Settings and a string with YFM.
Returned value: An object with the result and logs fields.

Result field

result: Resulting object, contains the fields:

html: A line with HTML.
meta: Metadata from the transmitted content.
title: The document title. Returned if extractTitle = true or needTitle = true.
headings: A list of document headers.

Logs field

logs: Information about the transformation process, includes arrays:

error: Errors.
warn: Warnings.
info: Additional information.

Example of a function invocation

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});

Custom HTML Sanitizer

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.

License

MIT

CSS public variables

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

Contributing

Tests

This package features unit tests run by Jest and e2e & visual tests run by Playwright. Playwright tests are located in e2e sub-package.

Playwright: prerequisites

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:playwright

This 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:ui

macOS users: unable/unwilling to use Docker Desktop?

Due 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:playwright

This ensures the DOCKER_HOST is set as necessary.