diplodoc-platform / transform Goto Github PK

v. 4 transform requires fs and path, which forces the addition of Node.js polyfills on client

Minimal example

* {% cut "Cut 1" %}

  Some text

{% endcut %}

This inserts closing div in wrong place.

Expected to throw or to autofix cut closing tag.

We need to add relevant role to term popup.

Also we need to mark term as live region

How to fix

Get the conditionsInCode flag from the options https://github.com/yandex-cloud/yfm-transform/blob/2fa7df8173c0c538c97842bd878335d7ba2fdaf1/src/transform/utilsFS.ts#L48
Pass the conditionsInCode flag to liquid options https://github.com/yandex-cloud/yfm-transform/blob/2fa7df8173c0c538c97842bd878335d7ba2fdaf1/src/transform/utilsFS.ts#L63

How to reproduce

#index.md
{% include [Code example](include.md) %}

#include.md

```bash
mongosh --norc \
{% if foo %}
--test inside bash
{% else %}
--test-false
{% endif %}

• Fix warnings
• Enable strict mode

Switched to @gravity-ui/app-builder as build library in my project and got this warnings in dev mode:

WARNING in ./node_modules/@doc-tools/transform/dist/css/yfm.css (./node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[1].oneOf[3].use[1]!./node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[1].oneOf[3].use[2]!./node_modules/resolve-url-loader/index.js??ruleSet[1].rules[1].oneOf[3].use[3]!./node_modules/@doc-tools/transform/dist/css/yfm.css)
Module Warning (from ./node_modules/resolve-url-loader/index.js):
resolve-url-loader: webpack misconfiguration
  webpack or the upstream loader did not supply a source-map

I couldn't find it in documentation, so, most likely, the answer to my question is No, but is it possible to add arbitrary attributes to the resulted HTML for links? For example, I want links to have target attribute set to "_blank" to have links open in a separate tab. It seems some other markdown processors allow this. Does yfm-transform support it?

For example markup:

#|
|| a | `b|c` ||
|#

Expected:

Actual:

example on 3.2.0: https://codesandbox.io/s/rough-field-wx86kv?file=/src/App.tsx

the same example on 3.3.0: https://codesandbox.io/s/magical-night-gdcmdk?file=/src/App.tsx

https://github.com/yandex-cloud/yfm-transform/blob/c2ff77d48bfcfccced691efe299d1782b83cd483/src/transform/plugins/notes.ts#L30

We currently use <div> tags for collapsible content sections.

<div class="yfm-cut open">
    <div class="yfm-cut-title">Cut header</div>
    <div class="yfm-cut-content">
        <p>Content displayed when clicked.</p>
    </div>
</div>

I propose refactoring these to use HTML's <details> tag to enhance accessibility, usability, and maintainability.

<details>
  <summary>Cut header</summary>
  Content displayed when clicked.
</details>

Justification:

1. Accessibility: <details> provides built-in keyboard and screen reader support, aligning with WCAG standards.
2. Native Functionality: Reduces JavaScript reliance, enhancing load times and reducing UI bugs with browser-handled collapsible features.
3. Usability & User Experience: Offers a standardized interaction model for users.
4. Maintenance: Simplifies code and guards against deprecation with standard HTML5.

At current time all plugins consumes union (global) configuration object, which passes from md constructor.

This configuration method can be buggy on large scope of plugins.

Proposal:

Move plugin configuration to closure:

export function somePlugn(options) {
    return function pluginBody(md) {
        if (options.flag) {
            ...
        }
    }
}

http://diplodoc.com would not be parsed as link without wrapping it in links syntax

e.g: [http://diplodoc.com](http://diplodoc.com) or <http://diplodoc.com>

playground link

most platforms have text that makes a link transformed into links automatically, creating expectations from users to have that feature out of the box.

look into implementing plugin that will parse text that looks like a link as link

be cautious of performance degradation.

Migrate to ESM modules

https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

Markup:

{% cut "{title}" %}

content

{% endcut %}

transform() crash with error

Uncaught TypeError: Cannot read properties of undefined (reading 'type')
    at exports.getMatchingOpeningToken (utils.js:236:1)
    at Object.transform (patterns.js:328:1)
    at Array.curlyAttrs (index.js:30:1)
    at Core.process (parser_core.js:54:1)
    at MarkdownIt.parseInline (index.js:561:1)
    at Array.plugin (cut.js:32:1)
    at Core.process (parser_core.js:54:1)
    at MarkdownIt.parse (index.js:524:1)
    at md.js:69:1
    at transform (index.js:28:1)

Example in playground

I found an issue with ordered lists (ol) in FireFox while using YFM. You can see it in this demo: https://codepen.io/isqua/pen/qBxgGjN?editors=1100

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>YFM Ordered List</title>
    <!-- The stylesheet is taken from https://ydocs.tech -->
    <link rel="stylesheet" href="https://yastatic.net/s3/cloud/docs-viewer-external/static/freeze/en/vendor.4bed8c5e.css">
</head>
<body>
    <h1>YFM: broken order of ordered lists</h1>
    <ol>
        <li>
            <p>YFM list one:</p>
            <div class="yfm">
                <ol>
                    <li>First list, first element</li>
                    <li>First list, second element</li>
                </ol>
            </div>
        </li>
        <li>
            <p>YFM list two:</p>
            <div class="yfm">
                <ol>
                    <li>Second list, first element</li>
                    <li>Second list, second element</li>
                </ol>
            </div>
        </li>
        <li>
            <p>YFM list three:</p>
            <div class="yfm">
                <ol>
                    <li>Third list, first element</li>
                    <li>Third list, second element</li>
                </ol>
            </div>
        </li>
    </ol>
</body>
</html>

In FireFox 101.0.1 the code produces following output:

As you see, text «YFM list two» is numbered as 4, but expected number is 2. And text «YFM list three» is numbered as 7, but expected number is 3.

Here is some explanation of this behaviour on FireFox Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1545746#c5

Looks like they are right :) I suppose we need to change counter-reset of ol from list to list-item list.

In some cases we need to render markdown that suitable for displaying as one-liner -- without images, paragraphs, list and etc.

markdown-it has method to achieve this renderInline, it would be nice to have it in transform.

If I write a link with underscores, yfm converts this link as plain text.
Example: https://a_b.com

selecting heading and copying it leads to duplicate text:

select and ctrl+c on this text:

# heading {#anchor}

upon doing ctrl+v leads to:

heading heading

playground example: https://diplodoc-platform.github.io/playground/?input=%23%2520heading%2520

this is happening because every anchor(even implicit one) generates token of type anchor_hidden_desc with heading text as content and rendered as a hidden span(all of that is done for SEO purposes).

parser/transformation:

renderer:

css rules:

prevent select of hidden text with user-select: none

original issue for seo implementation: #244

should not affect SEO: https://webmasters.stackexchange.com/questions/99855/is-text-that-use-css-user-select-none-indexed-and-ranked-by-search-engines

We need to visually separate the inline code and the inline code with a link, because they are almost indistinguishable

For example, in github: link code code_with_link

In YFM (same markup):

I use @doc-tools/transform function and this function fetches a 1.5 mb chunk with highlight.js which I don't use. Can you do lazy loading for this chunk?

Add transform profile info about each plugin.

It should be enabled by profile option. (Default: false).

If profile option is enabled, transform should expose profile info in result object:

{
    "html": "...",
    "profile": {
        <some popular profile format?>
        <compatible with web inspector?>
    }
}

Profiler can affect performance.

Profiler should be platform agnostic.

Profiler should be implemented in transformer itself, not in each plugin.

At current time transform is sync function.

This limits power of transformation.

Propose to add transform.async in minor with new experimental features.
Propose to change transform interface to async in major.

How to reproduce:

$ mkdir doc3 && cd doc3 && npm install @doc-tools/transform@latest
$ node -e "console.log(require('@doc-tools/transform')('## test header', {allowHTML: true}))" 
{
  result: {
    meta: {},
    assets: undefined,
    headings: [ [Object] ],
    title: '',
    html: '<h2 id="test-header"><a href="#test-header" class="yfm-anchor" aria-hidden="true"><span class="visually-hidden">test header</span></a>test header</h2>\n'
  },
  logs: { info: [], warn: [], error: [], disabled: [] }
}

test header string is present twice:

test headertest header

Bad news: at current time all code of this package is external API.

The markup

{% list tabs %}

- tab1

  content of tab1
  
  {% list tabs %}

  - nested_tab1

    content of nested tab1

  {% endlist %}

{% endlist %}

converts to this HTML:

Tabs doesn't support keyboard navigation.

In the following line of the en and ru README.md file * Input data: [Settings](settings.md) and a string with YFM. the settings.md file is specified, but it is nowhere to be found.

There are several propositions:

1. Add more note types with more color options (e.g. grey)
2. What about removal on title attribute for note. It is optional, but when it is absent it still renders as empty block.
   What about going from this syntax:

   {% note title="title" %}
   
   content
   
   {% endnote%}
   

   To this:

   {% note %}
   
   *title*
   
   content
   
   {% endnote%}
   

Need update depends and move to https://github.com/yandex-cloud/eslint-config

plugins/links

We have reflink syntax, this markup [{#T}](file.md) extracts title from file.md and uses it as link text.

We need to mark link_open token with markup: reflink(analogous to how autolinks are parsed).

Right now i am doing it inside @diplodoc-platform/markdown-translation library when rendering tokens into XML.

Objectively links of reflink type should just be marked as such by parser.

to easier understand the token structure checkout tokens tab: link to the playground

For example: https://example.com/search?q=table%5C(maps
This is a valid url, but it breaks the markup of the link.
[link](https://example.com/search?q=table%5C(maps)

Github markdown has same problem: [link](https://example.com/search?q=table%5C(maps)

Can you please update the markdown-it and the related plugins to the latest versions?

Why: I think, It will be useful and save users time.

Known issues

• how to show that link is already in clipboard

Cuts final html doesn't have role and state

Looks like we need expanded state and some relevant role.