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#fragment-identifier|link text]]
If no link text
is specified, the default link text will be “Note Title: Fragment Text”. The “Note Title:” can be suppressed by adding a !
prefix before the note-identifier
. A fragment can specify an alternate default text with a data-cross-reference-title
attribute.
Intra-page references can be made by omitting the note-identifier
:
[[#fragment-identifier|link 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.
Callout Blocks
A special case of fenced blocks.
::: note
The contents of the note.
:::
The contents of the note.
A callout’s title can be skipped by adding the no-title
class.
Used to break up documents with notes, warnings, and so on.
See Callouts.
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 text11 A 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.