Diplodoc Latex extension
This is extension for Diplodoc platform which adds support for Latex syntax using katex library.
Extension contains some parts:
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" />
<script src="_assets/latex-extension.js" async />
<script>
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:
Usage example:
window.latexJsonp = window.latexJsonp || [];
window.latexJsonp.push((latex) => {
latex.run();
});
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: [
latex.transform({
bundle: false,
runtime: LATEX_RUNTIME
})
]
})
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 />
</>
}