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
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 Katex 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>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');
});-
querySelector- The query selector to use when finding elements to render.
(Default:.yfm-latex) -
nodes- The nodes to render. If this is set,querySelectorwill be ignored. -
sanitize- The function to remove dangerous content from final html.
(Default:identity)
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
}));
});Plugin for @diplodoc/transform package.
Configuration:
-
runtime- name of runtime script which will be exposed in resultsscriptandstylesections.
Ifbundleoption 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
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 />
</>
}