Ink’s CommonMark Extensions

A catalog of the CommonMark extensions currently being used and being considered. They’re organized by syntax rather than semantics, to make it easier to see how all the different syntaxes fit together.

A lot of these are based on Pandoc’s Markdown and other extended CommonMark implementations.

“Not yet implemented” usually means that the feature is accessible through some other syntax such as HTML tags.

Prefixed Inline

Tags

Distinguished from titles, which have a space after the #. Tags at the top level are parsed as note or page metadata. Tags in some contexts, like task lists, may be styled in special ways.

#tag1 #tag2

A #tag in a sentence.

* [ ] A tag in a task list item #next

(The #tag1 and #tag2 are parsed as metadata and not included in the text of the note.)

A #tag in a sentence.

Mentions

Mentions start with @ and continue until the next whitespace or punctuation. They have to be preceeded by whitespace, so test@example.com isn’t a mention.

Unless identifiers are added to an allow-list, they’re replaced with anonymized references.

This person is on the allow-list: @threeseagrass. This person is not: @signet. Emails like test@example.com should not be recognized as mentions.

This person is on the allow-list: @Three Seagrass. This person is not: @Someone. Emails like test@example.com should not be recognized as mentions.

Delimited Inline

Cite Titles

Double double quotes can be used to mark up the title of a work using the <cite> element

The article "Foo" from the journal ""Bar"".

The article “Foo” from the journal Bar.

Cross-References

[[note-identifier#header-identifier|replacement text]]

Consider a variant for intra-document cross-references (e.g. with an implied note-identifier of the current document)?

[[#header-identifier|replacement text]]

Ruby

I’m really bad at reading kanji, so I end up relying on furigana a lot. Roughly based on でんでんマークダウン’s syntax.

{京都|きょうと}

京都（きょうと）

Fullwidth variants of the delimiters are also supported. To avoid the need for escaping text in some situations, the first character after the opening curly bracket must be a Japanese character. でんでんマークダウン’s モノルビ風 syntax isn’t supported right now.

See the syntax documentation (external link).

Citation References

* No location [@citekey1]
* With location [@citekey1 12]
* Suppressed author [-@citekey1 12]
* Multiple sources [@citekey1 12;@citekey2 34]

Rougly inspired by Pandoc’s citations (external link), but without as much semantic parsing going on. Locations are copied verbatim, and there isn’t any author-in-text version for now.

Blocks

Fenced Blocks

::: asdf
Contents (this will appear inside a `div` with the class `asdf`).
:::

Contents (this will appear inside a div with the class asdf).

Definition Lists

Term 1

:   Definition 1

Term 2

:   Definition 2

    Definition 2 second paragraph.
Term 1

Definition 1

Term 2

Definition 2

Definition 2 second paragraph.

Task Lists

* [ ] Item #tag @person
  * [ ] Nested item
* [x] Completed item

Transclusions

{{note-identifier}}

This snippet of text is being transcluded from another note.

Admonition Blocks

A special case of fenced blocks.

::: note

The contents of the note.

:::
Note

The contents of the note.

Used to break up documents with notes, warnings, and so on.

There isn’t much agreement between any of the extensions. GitHub, Pandoc, mkdocs, and Obsidian all have different syntaxes. For now I’ve settled on just using fenced blocks; it’s one less syntax to deal with.

Some of the advanced common concerns include collapsing, nesting, and custom styling; none of those are supported here yet.

Complex

Named Blocks

Borrowing from pandoc’s footnote extension, these named blocks of content can be referenced as figure captions or sidenotes.

[^identifier]: A named block.

Sidenotes

References a named block.

Text text[^identifier].

Text text11A named block..

1A named block.

Math

```katex
a = \frac{b}{c}
```

Inline $$a = \frac{b}{c}$$ math.
a=bca = \frac{b}{c}

Inline a=bca = \frac{b}{c} math.

Bare $ math $ seemed too fraught. Some implementations require a space after the $ to disambiguate with $10.00, but that seems kind of finicky.

Under Consideration

Marks

Stylistically, emphasis is probably preferred here, but this could be used to highlight notable items in a table, or possibly overlay emphasis in quotations without modifying the formatting in the quoted text.

Roam uses ^^mark^^. Bear uses ::mark::. Many extensions seem to have settled on ==mark==.

Test Sources

  1. FirstName LastName. Test Book. 2020.
  2. FirstName LastName and FirstName LastName. Test Book (Two Authors). 2020.