MultiMarkdown and CommonMark links

Contents

Inline links

There is an inline link that takes one of the following forms:

• [text](destination)
• [text](<destination>)
• [text](destination "title")
• [text](<destination> "title")
• [text]() <– Parses to <a href="">text</a>
• [text]("title") <– Parses to <a href="%22title%22">text</a>

The exact specifications for “text”, “destination”, and “title” are spelled out later in these comments.

Reference links

1. Full reference link

     [text][label]
   

The [label] points to a link reference definition.

Caution: any instance of “[text that may be a reference link]” should be tested to see if such a destination occurs within the document. If there isn’t one, the brackets should be left in place.

2. Collapsed reference link, where it is assumed the normalized version of “text” has a matching link reference definition in the document, or, in the case of MultiMarkdown, a heading from levels 1 through 6 that matches the [text].

     [text][]
   

3. Shortcut reference link, which is functionally identical to a collapsed reference link:

     [text]
   

Link reference definition

Reference links require a link reference definition in the document that takes the form:

  [label]: destination "title" optional attribute definitions

Example:

  [wiki:markdown]: https://en.wikipedia.org/wiki/Markdown "Wikipedia entry
  on Markdown" class="wikilink"

Image link

4. An image link takes one of four forms:

• ![label]
• ![alt text](image-url)
• [![alt text](image-url)](/url "title") (a clickable picture)
• `[][label] (a clickable picture)

The [label] is a link reference definition as detailed above.

Footnotes, glossary entries, citations

MultiMarkdown extends the reference link idea to footnotes, glossaries, and citations.

5. Footnotes

     Text leading up to the footnote. [^footnote-ref]
     Or something like this.[^This is footnote text, not a reference.]
         ...
     [^footnote-ref]: This is the text of the footnote.
   

When rendered in HTML:

      Text leading up to the footnote.[1]
      Or something like this. [2]

      [1] This is the text of the footnote. <backlink>
      [2] This is footnote text, not a reference. <backlink>

The fun part here might be the fact footnotes render immediately following the text in HTML, but could well at the bottom of the page in LaTeX or PDF. There’s also the fact footnotes can be multi-line, but that’s easy to handle because the footnote lines have a leading tab.

5. Glossary term

     [^glossaryfootnote]: glossary: term (optional sort key)
   
     The actual definition belongs on a new line, and can continue on
     just as other footnotes.
   

Glossary terms are collected by MultiMarkdown and rendered at the end of the file in alphabetical order.

6. Citation:

To use citations in MultiMarkdown, you use a syntax much like that for anchors:

   This is a statement that should be attributed to
   its source[p. 23][#Doe:2006].

And following is the description of the reference to be used in the bibliography.

    [#Doe:2006]: John Doe. *Some Big Fancy Book*.  Vanity Press, 2006.

In HTML output, citations are indistinguishable from footnotes. Or, in notes2html I can collect them the same way as glossary entries and render them at the end of the document (with appropriate backlinks; note that there may be more than one.)

7. As an extension (because it’s in the CommonMark spec.md document), a link reference definition can also consist of:

     [label](@)
   

Note that it looks like an inline link, but in HTML the <a> element gets an “id” attribute containing the normalized version of “label” and a “class” attribute of “definition”, while an inline link gets an “href” attribute that matches the destination.

Details of the text, destination, and title

The real devil is in the details due to various complexities of determining where the [text] and (destination) portions end. For the [text], one simply can’t jump forward to the ‘]’ because:

• It may be escaped:
  ... noting that [a \] character can be escaped][label]
• It may be part of an internal matching pair:
  ... noting that [link text can contain [balanced pairs] of brackets]
• It may be within backticks or raw HTML, in which case the ‘[text’ part may not even be a link at all.
• The link text can also include inline content such emphasis

Destination

• May or may not be enclosed in < >
• Like the text part, may contain escaped parentheses or balanced pairs of parentheses

Title:

• Can be enclosed in a) single quotes, b) double quotes, c) parentheses
• Can contain escaped versions of the closing character (the specification notes an escaped closing parenthesis but does not mention balanced parentheses)
• Can span multiple lines, but cannot contain a blank line.

When seeking the end of a text, destination, or title, it boils down to:

• Keep going on an escaped closing character
• Watch out for balanced pairs: add one to a counter any time an opening bracket/parenthesis is found, decrement it when the closing one is found, and stop when the counter reaches zero.