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.
- A tag in a task list item #next
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]
- No location (LastName)
- With location (LastName 12)
- Suppressed author (12)
- Multiple sources (LastName 12, LastName and LastName 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
- Item #tag @Someone
- Nested item
- 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.
:::
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..
Math
```katex
a = \frac{b}{c}
```
Inline $$a = \frac{b}{c}$$ math.
Inline 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
- FirstName LastName. Test Book. 2020.
- FirstName LastName and FirstName LastName. Test Book (Two Authors). 2020.