markdown-it-amsmath
v0.4.0
Published
A markdown-it plugin for amsmath LaTeX environments.
Downloads
3,395
Readme
markdown-it-amsmath
A markdown-it plugin for amsmath LaTeX environments.
The following "top-level" environments are parsed, with or without (ending *) numbering:
equation, multline, gather, align, alignat, flalign, matrix, pmatrix, bmatrix, Bmatrix, vmatrix, Vmatrix, eqnarray.
(these environments are taken from amsmath version 2.1)
Note the split, gathered, aligned, alignedat are not parsed, since they should be used within a parent environment.
See https://executablebooks.github.io/markdown-it-amsmath/ for a demonstration!
Usage
You should "bring your own" math render, provided as an option to the plugin. This function should take the string plus (optional) options, and return a string. For example, below the KaTeX render is used.
As a Node module:
import { renderToString } from "katex"
import MarkdownIt from "markdown-it"
import amsmathPlugin from "markdown-it-amsmath"
const katexOptions = { throwOnError: false, displayMode: true }
const renderer = math => renderToString(math, katexOptions)
const mdit = MarkdownIt().use(amsmathPlugin, { renderer })
const text = mdit.render("\\begin{equation}a = 1\\end{equation}")In the browser:
<!DOCTYPE html>
<html>
<head>
<title>Example Page</title>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css"
/>
<script src="https://cdn.jsdelivr.net/npm/markdown-it@12/dist/markdown-it.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.js"></script>
<script src="https://unpkg.com/markdown-it-amsmath"></script>
</head>
<body>
<div id="demo"></div>
<script>
const katexOptions = { throwOnError: false, displayMode: true }
const renderer = math => katex.renderToString(math, katexOptions)
const mdit = window.markdownit().use(window.markdownitAmsmath, { renderer })
const text = mdit.render("\\begin{equation}a = 1\\end{equation}")
document.getElementById("demo").innerHTML = text
</script>
</body>
</html>Development
Features
- TypeScript
- Code Formatting (prettier)
- Code Linting (eslint)
- Testing and coverage (vitest)
- Continuous Integration (GitHub Actions)
- Bundled as both UMD and ESM (rollup)
- Upload as NPM package and unpkg CDN
- Simple demonstration website (GitHub Pages)
Getting Started
- Create a GitHub repository from the template.
- Replace package details in the following files:
package.jsonLICENSEREADME.mdrollup.config.js
- Install the
node_moduledependencies:npm installornpm ci(see Install a project with a clean slate). - Run code formatting;
npm run format, and linting:npm run lint:fix. - Run the unit tests;
npm test, or with coverage;npm test -- --coverage.
Now you can start to adapt the code in src/index.ts for your plugin, starting with the markdown-it development recommendations.
Modify the test in tests/fixtures.spec.ts, to load your plugin, then the "fixtures" in tests/fixtures, to provide a set of potential Markdown inputs and expected HTML outputs.
On commits/PRs to the master branch, the GH actions will trigger, running the linting, unit tests, and build tests.
Additionally setup and uncomment the codecov action in .github/workflows/ci.yml, to provide automated CI coverage.
Finally, you can update the version of your package, e.g.: npm version patch -m "🚀 RELEASE: v%s", push to GitHub; git push --follow-tags, build; npm run build, and publish; npm publish.
Finally, you can adapt the HTML document in docs/, to load both markdown-it and the plugin (from unpkg), then render text from an input area.
This can be deployed by GitHub Pages.