search

executablebooks / markdown-it-amsmath

A markdown-it plugin for amsmath LaTeX environments.
https://executablebooks.github.io/markdown-it-amsmath/
MIT License
3 stars 1 forks source link

readme

markdown-it-amsmath

ci-badge npm-badge

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

Getting Started

  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.