martex v0.0.3-4

MarTeX

A helper library for extending Markdown for mathematical documents.

Introduction

Markdown is a lightweight markup language with plain-text-formatting syntax, created in 2004 by John Gruber with Aaron Swartz. The use of markdown is not confined to the software development community; with inter-conversion tools like pandoc, markdown is gaining a strong position as an easy document publishing format.

In recent years, there has been a move to standardize specifications (i.e. CommonMark), but there are also various dialects that have been extended, such as GFM. One such extension is the incorporation of LaTeX-style notation into markdown, which allows for the writing of documents in the natural sciences, including mathematical expressions. While the idea is very appealing, this kind of naive extension does not go well with the development of a sophisticated processor in markdown.

MarTeX's approach is as follows: 1. Separates LaTeX-style formulas and Markdown-formatted parts from mixed documents. 2. Render each part with an existing processor appropriate to it. 3. Integrate these results and get the complete output.

Installation

You can install martex from npm:

> npm --save install martex

MarTeX itself does not have a markdown or LaTeX format processor. These need to be installed separately. We recommend markdown-it and KaTeX:

> npm --save install markdown-it katex

Processing mixed documents

Using markdown-it and KaTeX, let's create a script to process mixed documents:

// run-martex.js
const martex = require('martex')
const markdownIt = require('markdown-it')
const katex = require('katex')

const main = async () => {
  // read input
  const source = await new Promise(done => {
    const buf = []
    process.stdin.on('data', chunk => buf.push(chunk))
    process.stdin.on('end', () => done(buf.join('')))
  })

  // translate using MarTeX, backend = markdown-it, katex
  const output = await martex.run(source, {
    // Specify the markdown processor.
    // This function only needs to be able to handle normal markdown,
    // and does not need to support formulas in LaTeX format.
    renderMarkdown: source => new markdownIt().render(source),
    // Specifies the processor for LaTeX formatted formulas.
    // This function only needs to be able to handle formulas,
    // and does not need to support markdown.
    renderMath: (source, delimiter) => katex.renderToString(source, {
      throwOnError: false,
      displayMode: !!delimiter.display
    })
  })

  // write output
  process.stdout.write(output)
}

if (require.main === module) main()

Convert this to HTML using the script we just created:

> echo '# Hello $\LaTeX$' | node ./run-martex.js > out.html

The following HTML will be generated:

<h1>Hello <span class="katex"><span class="katex-mathml"><math ...

Want to try it now? We also have a web-based demo page: MarTeX playground

How it works

Coming soon...

Configuring MarTeX / API Documents

Coming soon...

Contribution

You can report issues and suggest improvements on GitHub issues. We'd love to hear from you!

License

MarTeX is licensed under the MIT License.