${toc}

This project requires Node.js 13 or greater. Node.js 12 is known to work if NODE_OPTIONS=--experimental-modules environment variable is set. Other versions are not supported.

Since I don’t have npm registry account and the ecosystem sucks, we have to deal with it.

Create a new GitHub token with read:packages scope. Then execute the following commands, replacing ACCESS_TOKEN with your token.

npm set '//npm.pkg.github.com/:_authToken' 'ACCESS_TOKEN'
npm set registry 'https://npm.pkg.github.com/mathdown'

GitHub documentation also recommends running npm set always-auth true.

If you find colors annoying, run npm set color false. This step is optional.

To disable Git commit and tag creating on version bump run npm set git-tag-version false.

Linting the code requires some extra hacks until eslint/eslint#13196 (support for ECMAScript 2020) and benmosher/eslint-plugin-import (support for eslint 7) are released. You can use setup-eslint.sh script to set up the required versions. Running this script will also install project dependencies.

Otherwise, simply run npm ci --ignore-scripts.

Then, to render this file using MathDown, run the command below from the project root and open README.html in web browser.

node bin/mathdown.mjs -input README.md -output README.html -metadata assets/metadata.yaml -template assets/template.htm

Markdown on steroids (i.e. lots of server-side compile-time Node.js dependencies).

MathDown renders mathup markup language as MathML.

Firefox and Safari support the standard out of the box, though the latter has some quirks, e.g. when rendering $f(x)$ expression (nested <mrow>). Partial support for MathML in Chromium is available in the latest build and Chrome Canary with experimental web platform features enabled.

MathJax is loaded as a fallback for browsers without MathML support. You may either force or disable this behavior by appending ?mathjax=force or ?mathjax=disable query to the file URL.

Rendering plots from Markdown is not a 🚀 science!

width: 320
height: 200
data:
- fn: 'x^2'
  graphType: 'polyline'
xAxis:
  label: 'x - axis'
  domain: [-6, 6]
yAxis:
  label: 'y - axis'

Graphs can be specified in DOT graph description language. The library used internally supports other popular formats, but the priority for now is graph layout.

digraph {
	a -> b -> c
	b -> d
}

Note that currently manual layout/positioning and attributes are not supported. Hence the support is experimental.

graph ethane {
	C_0 -- H_0 [type=s]
	C_0 -- H_1 [type=s]
	C_0 -- H_2 [type=s]
	C_0 -- C_1 [type=s]
	C_1 -- H_3 [type=s]
	C_1 -- H_4 [type=s]
	C_1 -- H_5 [type=s]
}

MathDown performs language-agnostic distraction-free syntax highlighting.

package main

import "fmt"

// fib returns a function that returns
// successive Fibonacci numbers.
func fib() func() int {
	a, b := 0, 1
	return func() int {
		a, b = b, a+b
		return a
	}
}

func main() {
	f := fib()
	// Function calls are evaluated left-to-right.
	fmt.Println(f(), f(), f(), f(), f())
}

Another killer feature is the support for syntax diagrams (also known as railroad diagrams).

Supported notations

• PEG.js
• EBNF
• Ohm

Expression ::= Term ( ( "+" | "-" ) Term )*
Term       ::= Factor ( ( "*" | "/" ) Factor )*
Factor     ::= Constant | Variable | "(" Expression ")"
Variable   ::= "x" | "y" | "z"
Constant   ::= [0-9]+