MultiMarkdown Cross References

Spec
1

CommonMark has yet to implement the popular MultiMarkdown v2+ feature, “Cross References.”

One of the things I’ve struggled with is creating unique id's on elements, and incorporating them into Tables of Contents.

So, when I want to create a TOC, I have to use HTML. I’m not opposed to that, but it really doesn’t look as nice as Markdown.

Consider the following Markdown:

## Table of Contents

* [This Is a Header][]
* [This Is a Subhead][subhead]

# This Is a Header

This is a paragraph.

## This Is a Subhead [subhead]

This is another paragraph.

This is a [link][This Is a Header] to the header.

This is a [link][subhead] to the subhead, using an alternate reference link instead of \_the\_actual\_header\_title\_.

The resultant HTML would be:

<h2>Table of Contents</h2>

<ul>
<li><a href="#thisisaheader">This Is a Header</a></li>
<li><a href="#subhead">This Is a Subhead</a></li>
</ul>

<h1>This Is a Header</h1>

<p>This is a paragraph.</p>

<h2 id="subhead">This Is a Subhead</h2>

<p>This is another paragraph.</p>

<p>This is a <a href="#thisisaheader">link</a> to the header.</p>

<p>This is a <a href="#subhead">link</a> to the subhead, using an alternate reference link instead of _the_actual_header_title_.</p>

So instead of reverting to the HTML parlance of <h1 id="..., you can just use slightly modified Markdown link syntax. You can see how MultiMarkdown makes it easy to link to headers in the document—without having to insert icky HTML into the source document.

Just something I’ve been thinking about suggesting for a while :slight_smile:

1 Like
2

This has been discussed before, probably more than once.

Automatic IDs and shortcut links are implemented in several implementations and CM doesn’t forbid such extensions, I think. Assigning (or at least using) explicit IDs, however, could be done in a more indirect way than you show:

* [This Is a Header]
* [This Is a Subhead][subhead]

# This Is a Header

## This Is a Subhead

  [subhead]: [This Is a Subhead]
3

Again, I can see the previous discussion. And again, sigh.

Your suggestion was, as far as I can see, a decent one—it’s basically the standard reference link syntax. That said, it does add a bit of cruft that is not present in the MultiMarkdown implementation, specifically, the MMD implementation makes the Headers references in and of themselves, which is neat-o.

4

The idea behind the indirect syntax for IDs in my example is to not pollute the basic textual content with markup that should be invisible in the output. There already are some places, like reference link definitions and code block info-strings, that should not be rendered and hence can better cope with arbitrary code. Other places, like optional ATX line suffixes and all kinds of horizontal rules, currently require that nothing follows it on the same line, but maybe that nothing could be changed to no textual content which would allow IDs and classes at least.

Ideally, the solution would be backwards-compatible, too, but current implementations handle it wildly differently.

5

Sure. I agree. The more I learn about CommonMark, the more it feels …impossible.

The concept of a version of Markdown that stays true to Gruber’s original spec, and yet contains all the bells and whistles of all the other “Markdown+” versions—that seems easier said that done.

A community can decide on how to alter Gruber’s original spec much easier than it can decide on what to add. Because once “what to add” comes into play, everyone has their own favorite version.

These “discussions” you reference could go on forever! :wink:

Anyways. Thanks for your replies.

6

The concept of a version of Markdown that stays true to Gruber’s original spec, and yet contains all the bells and whistles of all the other “Markdown+” versions—that seems easier said that done.

The goal of the project, in this phase, is not to “contain all the bells and whistles of all other Markdown+ versions,” but to give a rationalized, clear and complete specification of the core syntax. That has to be done before we think about new syntax elements, and that project still isn’t quite finished.

We recommend that people who want special extensions start with CommonMark as a base and extend from there. (See e.g. the markdown-it project, which has many plugins for extensions.) Eventually some extensions will be incorporated into CommonMark. Personally I quite like the MMD style of links to section headers, and pandoc supports it.

7

Thanks for your reply. Everything you’re saying makes sense. I guess it’s just hard to wait, when it feels like there are other great Markdown implementations out there. I want to see CommonMark become the true “Standard Markdown.” That would make everything Markdown better all-around :smile:

2 Likes