Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/diplodoc-platform/latex-extension

Latex extension for Diplodoc platform
https://github.com/diplodoc-platform/latex-extension

Last synced: about 2 months ago
JSON representation

Latex extension for Diplodoc platform

Awesome Lists containing this project

README 

        
# Diplodoc Latex extension



[![NPM version](https://img.shields.io/npm/v/@diplodoc/latex-extension.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/latex-extension)



This is extension for Diplodoc platform which adds support for Latex syntax using [katex](https://katex.org/) library.



Extension contains some parts:

- [Prepared Katex runtime](#prepared-katex-runtime)

- [MarkdownIt transform plugin](#markdownit-transform-plugin)

- [React hook and component for smart control of Katex](#react-hook-and-component-for-smart-control-of-katex)



## Quickstart

Attach plugin to transformer



```js

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



    

        

        

        

        

            // Read more about 'latexJsonp' in 'Prepared Katex runtime' section

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

            window.latexJsonp.push((latex) => {

                window.addEventListener('load', function() {

                    latex.run();

                });

            });

        

    

    

        ${result.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](https://katex.org/docs/options) & [RunOptions](#run-options))** - start formula rendering



Usage example:

```js

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](https://katex.org/docs/security).


But there is extra option for extended sanitize. You feel free to use your own sanitizer:



```js

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](https://github.com/diplodoc-platform/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**:

  ```json

  {

    "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 `/`


  **Should be disabled for clientside usage**


  **Default**: true



- `validate` - boolean flag to enable/disable build validation.


  Useful for serverside prebuild tools like [@diplodoc/cli](https://github.com/diplodoc-platform/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](https://katex.org/docs/options) rendering option



## React hook and component for smart control of Katex



Simplifies Katex control with react



```tsx

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 


}



export const App: React.FC = ({ theme }) => {

    return <>

        

        

    >

}

```