${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
Expression ::= Term ( ( "+" | "-" ) Term )*
Term ::= Factor ( ( "*" | "/" ) Factor )*
Factor ::= Constant | Variable | "(" Expression ")"
Variable ::= "x" | "y" | "z"
Constant ::= [0-9]+