@diplodoc/latex-extension NPM

Diplodoc Latex extension

This is extension for Diplodoc platform which adds support for Latex syntax using katex library.

Extension contains some parts:

Prepared Katex runtime
MarkdownIt transform plugin
React hook and component for smart control of Katex

Quickstart

Attach plugin to transformer

import latex from '@diplodoc/latex-extension';
import transform from '@diplodoc/transform';

const {result} = await transform(`
### Inline latex

Some text $c = \pm\sqrt{a^2 + b^2}$

### Block latex

$$
c = \pm\sqrt{a^2 + b^2}
$$
`, {
    plugins: [
        latex.transform()
    ]
});

Add latex runtime to your final page

<html>
    <head>
        <link rel="stylesheet" href="_assets/latex-extension.css" />
        <!-- Read more about '_assets/latex-extension.js' in 'MarkdownIt transform plugin' section -->
        <script src="_assets/latex-extension.js" async />
        <script>
            // Read more about 'latexJsonp' in 'Prepared Mermaid runtime' section
            window.latexJsonp = window.latexJsonp || [];
            window.latexJsonp.push((latex) => {
                window.addEventListener('load', function() {
                    latex.run();
                });
            });
        </script>
    </head>
    <body style="background: #000">
        ${result.html}
    </body>
</html>

Prepared Katex runtime

Katex - is most popular and fast implementation of rendering tex/latex formulas.

The problem with Katex is that it has big bundle size. The most expected behavior is loading it asynchronously.

Prepared Katex runtime designed to solve this problem. We add latexJsonp global callback to handle Katex loading.

Also, we limit exposed Katex API by next methods:

run(options: KatexOptions & RunOptions) - start formula rendering

Usage example:

window.latexJsonp = window.latexJsonp || [];

// This callback will be called when runtime is loaded
window.latexJsonp.push((latex) => {
    latex.run();
});

// You can configure more that one callback
window.latexJsonp.push((latex) => {
    console.log('Render diagrams');
});

Run options

querySelector - The query selector to use when finding elements to render. (Default: .yfm-latex)
nodes - The nodes to render. If this is set, querySelector will be ignored.
sanitize - The function to remove dangerous content from final html. (Default: identity)

Security

By default runtime uses Katex security recomendations. But there is extra option for extended sanitize. You feel free to use your own sanitizer:

import dompurify from 'dompurify';
import domready from 'domready';

window.latexJsonp = window.latexJsonp || [];
window.latexJsonp.push((latex) => {
    domready(() => latex.run({
        sanitize: dompurify.sanitize
    }));
});

MarkdownIt transform plugin

Plugin for @diplodoc/transform package.

Configuration:

runtime - name of runtime script which will be exposed in results script and style sections. If bundle option was disabled then can be plain string. Otherwise should be string record. Default:
```
{
  "script": "_assets/latex-extension.js",
  "style": "_assets/latex-extension.css"
}
```
bundle - boolean flag to enable/disable copying of bundled runtime to target directory. Where target directory is <transformer output option>/<plugin runtime option> Should be disabled for clientside usage Default: true
validate - boolean flag to enable/disable build validation. Useful for serverside prebuild tools like @diplodoc/cli Should be disabled for clientside usage Default: true
classes - additional classes which will be added to Latex formula container. (Example: my-own-class and-other-class)
katexOptions - katex rendering option

React hook and component for smart control of Katex

Simplifies Katex control with react

import React from 'react'
import { transform } from '@diplodoc/transform'
import latex from '@diplodoc/latex-extension/plugin'
import { LatexRuntime } from '@diplodoc/latex-extension/react'

const LATEX_RUNTIME = 'extension:latex';

const Doc: React.FC = ({ content }) => {
    const result = transform(content, {
      plugins: [
        // Initialize plugin for client/server rendering
        latex.transform({
          // Do not touch file system
          bundle: false,
          // Set custom runtime name for searching in result scripts
          runtime: LATEX_RUNTIME
        })
      ]
    })

    // Load katex only if one or more formulas should be rendered
    if (result.script.includes(LATEX_RUNTIME)) {
      import('@diplodoc/latex-extension/runtime')
    }

    if (result.style.includes(LATEX_RUNTIME)) {
      import('@diplodoc/latex-extension/runtime/styles')
    }

    return <div dangerouslySetInnerHTML={{ __html: result.html }} />
}

export const App: React.FC = ({ theme }) => {
    return <>
        <Doc content={`
            $$
            c = \pm\sqrt{a^2 + b^2}
            $$
        `}/>
        <KatexRuntime />
    </>
}

@everything-registry/sub-chunk-245 @diplodoc/client

3 months ago

4 months ago

5 months ago

5 months ago

5 months ago