@diplodoc/transform 4.0.0 → 4.2.0

package/README.md

@@ -1,38 +1,73 @@
 **english** | [русский](https://github.com/yandex-cloud/yfm-transform/blob/master/README.ru.md)
 - - -
 
-[![NPM version](https://img.shields.io/npm/v/@doc-tools/transform.svg?style=flat)](https://www.npmjs.org/package/@doc-tools/transform)
+[![NPM version](https://img.shields.io/npm/v/@diplodoc/transform.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/transform)
 
+[@diplodoc/transform](https://www.npmjs.com/package/@diplodoc/transform) is a package for converting Yandex Flavored Markdown to HTML.
 
-A simple transformer of text in YFM (Yandex Flavored Markdown) to HTML.
+Use it in your code to work with text during program execution. For example, to display user-generated content.
 
-## Yandex Flavored Markdown
+## Installation {#install}
 
-Yandex Flavored Markdown (YFM) is a Markdown dialect that is now used for
-[Yandex.Cloud documentation](https://cloud.yandex.com/docs), [Yandex.Cloud website content](https://cloud.yandex.com), and in
-a variety of internal Yandex projects.
+1. Install a package:
 
-The syntax is based on the CommonMark Spec, extending it with additional features. It's designed for creating
-a full-fledged complex documentation project, such as the Yandex.Cloud documentation.
+    ```shell
+    npm i @diplodoc/transform
+    ```
 
-To build your documentation project in YFM, use the [@doc-tools/docs](https://www.npmjs.com/package/@doc-tools/docs) package.
+1. Add the package in your code using the `require()` or `import()` function:
 
-[Learn more about YFM](https://ydocs.tech)
+    ```javascript
+    const transform = require('@diplodoc/transform');
+    ```
 
-## Source files
+1. To ensure text is displayed properly, add CSS styles and client scripts to the project:
 
-### Installation
+     ```css
+     @import '~@diplodoc/transform/dist/css/yfm.css';
+     ```
 
-```shell script
-git clone git@github.com:yandex-cloud/yfm-transform.git
-cd yfm-transform
-npm install
-```
+     ```javascript
+     import '@diplodoc/transform/dist/js/yfm';
+     ```
+
+## Usage {#use}
+
+The package provides the `transform()` function:
+
+* Input data: [Settings](settings.md) 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](../../syntax/meta.md#meta) 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
+
+```javascript
+const fs = require('fs');
+const transform = require('@diplodoc/transform');
 
-When you add changes to files from the SRC folder, before updating the package version, run
+const content = fs.readFileSync(filePath, 'utf');
+const vars = { user: { name: 'Alice' } };
 
-```shell script
-npm run dist
+const {
+    result: {html, meta, title, headings},
+    logs,
+    } = transform(content, {vars});
 ```
 
 ## License

package/README.ru.md

@@ -1,36 +1,73 @@
 **русский** | [english](https://github.com/yandex-cloud/yfm-transform/blob/master/README.md)
 - - -
 
-[![NPM version](https://img.shields.io/npm/v/@doc-tools/transform.svg?style=flat)](https://www.npmjs.org/package/@doc-tools/transform)
+[![NPM version](https://img.shields.io/npm/v/@diplodoc/transform.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/transform)
 
-Простой трансформер текста на YFM (Yandex Flavored Markdown) в HTML.
+[@diplodoc/transform](https://www.npmjs.com/package/@diplodoc/transform) — пакет для трансформации Yandex Flavored Markdown в HTML.
 
-## Yandex Flavored Markdown
+Используйте его в своем коде для работы с текстом во время выполнения программы. Например, чтобы отображать пользовательский контент.
 
-Yandex Flavored Markdown (YFM) является диалектом Markdown, который используется сейчас для
-[документации Яндекс.Облака](https://cloud.yandex.ru/docs), [контента сайта Я.Облака](https://cloud.yandex.ru) и в
-различных внутренних проектах Яндекса.
+## Установка {#install}
 
-Синтаксис базируется на CommonMark Spec, расширяя его дополнительными возможностями. В том числе, для создания
-полноценного сложного документационного проекта, такого как документация Яндекс.Облака.
+1. Установите пакет:
 
-Для сборки своего документационного проекта на YFM вы можете использовать пакет [@doc-tools/docs](https://www.npmjs.com/package/@doc-tools/docs).
+    ```shell
+    npm i @diplodoc/transform
+    ```
 
-[Более подробное описание YFM](https://ydocs.tech)
+1. Подключите пакет в своем коде, используя функцию `require()` или `import()`:
 
-## Исходники
-### Установка
-```shell script
-git clone git@github.com:yandex-cloud/yfm-transform.git
-cd yfm-transform
-npm install
-```
+    ```javascript
+    const transform = require('@diplodoc/transform');
+    ```
+
+1. Для корректного отображения подключите в проект CSS-стили и клиентские скрипты:
+
+     ```css
+     @import '~@diplodoc/transform/dist/css/yfm.css';
+     ```
+
+     ```javascript
+     import '@diplodoc/transform/dist/js/yfm';
+     ```
+
+## Использование {#use}
+
+Пакет предоставляет функцию `transform()`:
+* входные данные — строка с YFM и [настройки](settings.md);
+* возвращаемое значение — объект с полями `result` и `logs`.
+
+### Поле result
 
-При добавлении изменений в файлы из директории src перед обновлением версии пакета нужно выполнить
-```shell script
-npm run dist
+`result` — объект результата, содержит поля:
+* `html` — строка с HTML.
+* `meta` — [метаданные](../../syntax/meta.md#meta) из переданного контента.
+* `title` — заголовок документа. Возвращается, если заданы настройки `extractTitle = true` или `needTitle = true`.
+* `headings` — список заголовков документа.
+
+### Поле logs
+
+`logs` — информация о процессе трансформации, включает массивы:
+* `error` — ошибки.
+* `warn` — предупреждения.
+* `info` — дополнительная информация.
+
+### Пример вызова функции
+
+```javascript
+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});
 ```
 
+
 ## License
 
 MIT

package/dist/css/print.css

@@ -0,0 +1,70 @@
+/* src/scss/print.scss */
+@media print {
+  .yfm .yfm-clipboard > pre > code {
+    white-space: pre-wrap;
+  }
+}
+@media print {
+  .yfm .yfm-page__delimeter {
+    display: none;
+  }
+  .yfm h1[data-original-article],
+  .yfm h2[data-original-article] {
+    page-break-before: always;
+  }
+}
+@media print {
+  .yfm .yfm-cut-title {
+    padding-left: 0;
+  }
+  .yfm .yfm-cut-title:before {
+    display: none;
+  }
+  .yfm .yfm-cut-content {
+    height: auto;
+    padding: 5px 0 15px 30px;
+  }
+}
+@media print {
+  .yfm .yfm-note {
+    page-break-inside: avoid;
+  }
+}
+.yfm .yfm-table-container {
+  position: relative;
+}
+.yfm .yfm-table-container > table {
+  overflow: visible;
+  overflow: initial;
+  position: absolute;
+  top: 0;
+  left: 0;
+  max-width: none;
+  max-width: initial;
+  transform-origin: top left;
+}
+.yfm .yfm-table-container > table thead {
+  display: table-row-group;
+}
+.yfm .yfm-table-container > table th,
+.yfm .yfm-table-container > table td {
+  page-break-inside: avoid;
+  white-space: pre-wrap;
+  text-overflow: initial;
+}
+@media print {
+  .yfm .yfm-tab-list {
+    display: none;
+  }
+  .yfm .yfm-tab-panel:before {
+    content: attr(data-title);
+    margin-bottom: -1px;
+    margin-right: 20px;
+    border-bottom: 2px solid transparent;
+    line-height: 33px;
+    font-weight: 700;
+    outline: 0;
+    cursor: pointer;
+  }
+}
+/*# sourceMappingURL=print.css.map */

package/dist/css/print.css.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/scss/home/runner/work/transform/transform/src/scss/print/code.scss", "../../src/scss/%3Cinput%20css%20bc_ZVo%3E", "../../src/scss/home/runner/work/transform/transform/src/scss/print/common.scss", "../../src/scss/home/runner/work/transform/transform/src/scss/print/cut.scss", "../../src/scss/home/runner/work/transform/transform/src/scss/print/note.scss", "../../src/scss/home/runner/work/transform/transform/src/scss/print/table.scss", "../../src/scss/home/runner/work/transform/transform/src/scss/print/tabs.scss"],
+  "sourcesContent": ["@media print {\n    .yfm {\n        .yfm-clipboard {\n            & > pre > code {\n                white-space: pre-wrap;\n            }\n        }\n    }\n}", "@media print {\n  .yfm .yfm-clipboard > pre > code {\n    white-space: pre-wrap;\n  }\n}\n@media print {\n  .yfm .yfm-page__delimeter {\n    display: none;\n  }\n  .yfm h1[data-original-article], .yfm h2[data-original-article] {\n    page-break-before: always;\n  }\n}\n@media print {\n  .yfm .yfm-cut-title {\n    padding-left: 0;\n  }\n  .yfm .yfm-cut-title:before {\n    display: none;\n  }\n  .yfm .yfm-cut-content {\n    height: auto;\n    padding: 5px 0 15px 30px;\n  }\n}\n@media print {\n  .yfm .yfm-note {\n    page-break-inside: avoid;\n  }\n}\n.yfm .yfm-table-container {\n  position: relative;\n}\n.yfm .yfm-table-container > table {\n  overflow: initial;\n  position: absolute;\n  top: 0;\n  left: 0;\n  max-width: initial;\n  transform-origin: top left;\n}\n.yfm .yfm-table-container > table thead {\n  display: table-row-group;\n}\n.yfm .yfm-table-container > table th, .yfm .yfm-table-container > table td {\n  page-break-inside: avoid;\n  white-space: pre-wrap;\n  text-overflow: initial;\n}\n\n@media print {\n  .yfm .yfm-tab-list {\n    display: none;\n  }\n  .yfm .yfm-tab-panel:before {\n    content: attr(data-title);\n    margin-bottom: -1px;\n    margin-right: 20px;\n    border-bottom: 2px solid transparent;\n    line-height: 33px;\n    font-weight: 700;\n    outline: 0;\n    cursor: pointer;\n  }\n}\n/*# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VSb290IjoiL2hvbWUvcnVubmVyL3dvcmsvdHJhbnNmb3JtL3RyYW5zZm9ybS9zcmMvc2NzcyIsInNvdXJjZXMiOlsicHJpbnQvY29kZS5zY3NzIiwicHJpbnQvY29tbW9uLnNjc3MiLCJwcmludC9jdXQuc2NzcyIsInByaW50L25vdGUuc2NzcyIsInByaW50L3RhYmxlLnNjc3MiLCJwcmludC90YWJzLnNjc3MiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7RUFHWTtJQUNJOzs7QUNKaEI7RUFFUTtJQUNJOztFQUlBO0lBQ0k7OztBQ1JoQjtFQUdZO0lBQ0k7O0VBRUE7SUFDSTs7RUFJUjtJQUNJO0lBQ0E7OztBQ2JoQjtFQUVRO0lBQ0k7OztBQ0ZSO0VBQ0k7O0FBRUE7RUFDSTtFQUNBO0VBQ0E7RUFDQTtFQUNBO0VBQ0E7O0FBRUE7RUFDSTs7QUFHSjtFQUNJO0VBQ0E7RUFDQTs7O0FDbkJoQjtFQUdZO0lBQ0k7O0VBR0o7SUFDSTtJQUNBO0lBQ0E7SUFDQTtJQUNBO0lBQ0E7SUFDQTtJQUNBIiwic291cmNlc0NvbnRlbnQiOlsiQG1lZGlhIHByaW50IHtcbiAgICAueWZtIHtcbiAgICAgICAgLnlmbS1jbGlwYm9hcmQge1xuICAgICAgICAgICAgJiA+IHByZSA+IGNvZGUge1xuICAgICAgICAgICAgICAgIHdoaXRlLXNwYWNlOiBwcmUtd3JhcDtcbiAgICAgICAgICAgIH1cbiAgICAgICAgfVxuICAgIH1cbn0iLCJAbWVkaWEgcHJpbnQge1xuICAgIC55Zm0ge1xuICAgICAgICAueWZtLXBhZ2VfX2RlbGltZXRlciB7XG4gICAgICAgICAgICBkaXNwbGF5OiBub25lO1xuICAgICAgICB9XG5cbiAgICAgICAgaDEsIGgyIHtcbiAgICAgICAgICAgICZbZGF0YS1vcmlnaW5hbC1hcnRpY2xlXSB7XG4gICAgICAgICAgICAgICAgcGFnZS1icmVhay1iZWZvcmU6IGFsd2F5cztcbiAgICAgICAgICAgIH1cbiAgICAgICAgfVxuICAgIH1cbn0iLCJAbWVkaWEgcHJpbnQge1xuICAgIC55Zm0ge1xuICAgICAgICAueWZtLWN1dCB7XG4gICAgICAgICAgICAmLXRpdGxlIHtcbiAgICAgICAgICAgICAgICBwYWRkaW5nLWxlZnQ6IDA7XG5cbiAgICAgICAgICAgICAgICAmOmJlZm9yZSB7XG4gICAgICAgICAgICAgICAgICAgIGRpc3BsYXk6IG5vbmU7XG4gICAgICAgICAgICAgICAgfVxuICAgICAgICAgICAgfVxuXG4gICAgICAgICAgICAmLWNvbnRlbnQge1xuICAgICAgICAgICAgICAgIGhlaWdodDogYXV0bztcbiAgICAgICAgICAgICAgICBwYWRkaW5nOiA1cHggMCAxNXB4IDMwcHg7XG4gICAgICAgICAgICB9XG4gICAgICAgIH1cbiAgICB9XG59XG4iLCJAbWVkaWEgcHJpbnQge1xuICAgIC55Zm0ge1xuICAgICAgICAueWZtLW5vdGUge1xuICAgICAgICAgICAgcGFnZS1icmVhay1pbnNpZGU6IGF2b2lkO1xuICAgICAgICB9XG4gICAgfVxufVxuIiwiLnlmbSB7XG4gICAgLnlmbS10YWJsZS1jb250YWluZXIge1xuICAgICAgICBwb3NpdGlvbjogcmVsYXRpdmU7XG5cbiAgICAgICAgJiA+IHRhYmxlIHtcbiAgICAgICAgICAgIG92ZXJmbG93OiBpbml0aWFsO1xuICAgICAgICAgICAgcG9zaXRpb246IGFic29sdXRlO1xuICAgICAgICAgICAgdG9wOiAwO1xuICAgICAgICAgICAgbGVmdDogMDtcbiAgICAgICAgICAgIG1heC13aWR0aDogaW5pdGlhbDtcbiAgICAgICAgICAgIHRyYW5zZm9ybS1vcmlnaW46IHRvcCBsZWZ0O1xuXG4gICAgICAgICAgICB0aGVhZCB7XG4gICAgICAgICAgICAgICAgZGlzcGxheTogdGFibGUtcm93LWdyb3VwO1xuICAgICAgICAgICAgfVxuXG4gICAgICAgICAgICB0aCwgdGQge1xuICAgICAgICAgICAgICAgIHBhZ2UtYnJlYWstaW5zaWRlOiBhdm9pZDtcbiAgICAgICAgICAgICAgICB3aGl0ZS1zcGFjZTogcHJlLXdyYXA7XG4gICAgICAgICAgICAgICAgdGV4dC1vdmVyZmxvdzogaW5pdGlhbDtcbiAgICAgICAgICAgIH1cbiAgICAgICAgfVxuICAgIH1cbn0iLCJAbWVkaWEgcHJpbnQge1xuICAgIC55Zm0ge1xuICAgICAgICAueWZtLXRhYiB7XG4gICAgICAgICAgICAmLWxpc3Qge1xuICAgICAgICAgICAgICAgIGRpc3BsYXk6IG5vbmU7XG4gICAgICAgICAgICB9XG5cbiAgICAgICAgICAgICYtcGFuZWw6YmVmb3JlIHtcbiAgICAgICAgICAgICAgICBjb250ZW50OiBhdHRyKGRhdGEtdGl0bGUpO1xuICAgICAgICAgICAgICAgIG1hcmdpbi1ib3R0b206IC0xcHg7XG4gICAgICAgICAgICAgICAgbWFyZ2luLXJpZ2h0OiAyMHB4O1xuICAgICAgICAgICAgICAgIGJvcmRlci1ib3R0b206IDJweCBzb2xpZCB0cmFuc3BhcmVudDtcbiAgICAgICAgICAgICAgICBsaW5lLWhlaWdodDogMzNweDtcbiAgICAgICAgICAgICAgICBmb250LXdlaWdodDogNzAwO1xuICAgICAgICAgICAgICAgIG91dGxpbmU6IDA7XG4gICAgICAgICAgICAgICAgY3Vyc29yOiBwb2ludGVyO1xuICAgICAgICAgICAgfVxuICAgICAgICB9XG4gICAgfVxufVxuIl19 */", "@media print {\n    .yfm {\n        .yfm-page__delimeter {\n            display: none;\n        }\n\n        h1, h2 {\n            &[data-original-article] {\n                page-break-before: always;\n            }\n        }\n    }\n}", "@media print {\n    .yfm {\n        .yfm-cut {\n            &-title {\n                padding-left: 0;\n\n                &:before {\n                    display: none;\n                }\n            }\n\n            &-content {\n                height: auto;\n                padding: 5px 0 15px 30px;\n            }\n        }\n    }\n}\n", "@media print {\n    .yfm {\n        .yfm-note {\n            page-break-inside: avoid;\n        }\n    }\n}\n", ".yfm {\n    .yfm-table-container {\n        position: relative;\n\n        & > table {\n            overflow: initial;\n            position: absolute;\n            top: 0;\n            left: 0;\n            max-width: initial;\n            transform-origin: top left;\n\n            thead {\n                display: table-row-group;\n            }\n\n            th, td {\n                page-break-inside: avoid;\n                white-space: pre-wrap;\n                text-overflow: initial;\n            }\n        }\n    }\n}", "@media print {\n    .yfm {\n        .yfm-tab {\n            &-list {\n                display: none;\n            }\n\n            &-panel:before {\n                content: attr(data-title);\n                margin-bottom: -1px;\n                margin-right: 20px;\n                border-bottom: 2px solid transparent;\n                line-height: 33px;\n                font-weight: 700;\n                outline: 0;\n                cursor: pointer;\n            }\n        }\n    }\n}\n"],
+  "mappings": ";AAAA,OAAA;AAGY,GAAA,IAAA,CAAA,cAAA,EAAA,IAAA,EAAA;AACI,iBAAA;ACDd;AACF;ACJA,OAAA;AAEQ,GFCI,IEDJ,CAAA;AACI,aAAA;ADKV;ACDU,GFJA,IEIA,EAAA,CAAA;EAAA,CFJA,IEIA,EAAA,CAAA;AACI,uBAAA;ADGd;AACF;AEZA,OAAA;AAGY,GHAA,IGAA,CAAA;AACI,kBAAA;AFYd;AEVc,GHHJ,IGGI,CAHJ,aAGI;AACI,aAAA;AFYlB;AERU,GHRA,IGQA,CAAA;AACI,YAAA;AACA,aAAA,IAAA,EAAA,KAAA;AFUd;AACF;AGxBA,OAAA;AAEQ,GJCI,IIDJ,CAAA;AACI,uBAAA;AHyBV;AACF;AI5BI,CLEQ,IKFR,CAAA;AACI,YAAA;AJ8BR;AI5BQ,CLDI,IKCJ,CAHJ,oBAGI,EAAA;AACI,YAAA;AAAA,YAAA;AACA,YAAA;AACA,OAAA;AACA,QAAA;AACA,aAAA;AAAA,aAAA;AACA,oBAAA,IAAA;AJ8BZ;AI5BY,CLTA,IKSA,CAXR,oBAWQ,EAAA,MAAA;AACI,WAAA;AJ8BhB;AI3BY,CLbA,IKaA,CAfR,oBAeQ,EAAA,MAAA;AAAA,CLbA,IKaA,CAfR,oBAeQ,EAAA,MAAA;AACI,qBAAA;AACA,eAAA;AACA,iBAAA;AJ6BhB;AKhDA,OAAA;AAGY,GNAA,IMAA,CAAA;AACI,aAAA;ALiDd;AK9CU,GNJA,IMIA,CAAA,aAAA;AACI,aAAA,KAAA;AACA,mBAAA;AACA,kBAAA;AACA,mBAAA,IAAA,MAAA;AACA,iBAAA;AACA,iBAAA;AACA,aAAA;AACA,YAAA;ALgDd;AACF;",
+  "names": []
+}

package/dist/css/yfm.css

@@ -543,24 +543,6 @@
   right: 16px;
   z-index: 1;
 }
-@media print {
-  .tab-list {
-    display: none !important;
-  }
-  .tab-panel:before {
-    content: attr(data-title);
-    margin-bottom: -1px;
-    margin-right: 20px;
-    border-bottom: 2px solid transparent;
-    line-height: 33px;
-    font-weight: 700;
-    outline: 0;
-    cursor: pointer;
-  }
-  .tab-panel {
-    display: block !important;
-  }
-}
 .yfm-cut-title {
   cursor: pointer;
   position: relative;