markdown-it-amsmath

[![ci-badge]][ci-link]
[![npm-badge]][npm-link]

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 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:

``javascript
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:

`html




rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css"
/>











`

Development

$3

- 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])

$3

1. Create a GitHub repository from the template.
2. Replace package details in the following files:
- package.json
- LICENSE
- README.md
- rollup.config.js
3. Install the node_module dependencies: npm install or npm ci (see Install a project with a clean slate).
4. Run code formatting; npm run format, and linting: npm run lint:fix.
5. 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].

[ci-badge]: https://github.com/executablebooks/markdown-it-amsmath/workflows/CI/badge.svg
[ci-link]: https://github.com/executablebooks/markdown-it--plugin-template/actions
[npm-badge]: https://img.shields.io/npm/v/markdown-it-amsmath.svg
[npm-link]: https://www.npmjs.com/package/markdown-it-amsmath
[github actions]: https://docs.github.com/en/actions
[github pages]: https://docs.github.com/en/pages
[prettier]: https://prettier.io/
[eslint]: https://eslint.org/
[vitest]: https://vitest.dev/
[rollup]: https://rollupjs.org
[npm]: https://www.npmjs.com
[unpkg]: https://unpkg.com/