A markdown variant

I use a version of markdown with a few extra features, some custom and some commonplace.

1. Features

The usual things like mathematics $x+y$ and

Make a citation with :cite[hello]. Currently the citation id is looked up from a huge bibtex file. But the hope is to have it lookup citations automatically.

Frontmatter is supported with --- tags:

---
title: Hello world
---

• math $x + y$

• table-of-contents

• numbering figures

• figures and code samples with captions

• extensibility for making interactive documents etc

• frontmatter

• Markdown parsing doesn't stop inside certain HTML blocks; the main one is table.

• assigning reference labels to figures, sections and equations

2. Directives

Markdown directives are used for custom elements.

Inline directives can put content inline :hello[world]

:::sidenote
This is a block sidenote.
:::

Directives can also be decorated with {#hello.world data-kind="eqn"} things, which can give the element custom ids, classes and attributes. If a directive appears in a markdown ast, by default the renderer treats it as an html element.

3. Goals

• It works with existing tooling that I use:

  • Markdown All in One VScode extension.

  • Obsidian: local links use double square brackets and use the path structure.

• Minimal changes from CommonMark and Obsidian markdown.

• Parses to an AST.

4. Prior work

• Scholarly markdown; this misses the point, which is that we really just want an extensible markdown.

• R markdown

• Bookdown

• mdx is like JSX but for markdown.