Note to self: MultiMarkdown style within-document links are not supported in GitHub markdown

MultiMarkdown (MMD) lets us very simply add within-document links (also known as cross-links or cross-references).

Where a heading is defined in a page, like so:

### The Heading

all that we need to do to link to that heading from elsewhere in the same page is to include:

[The Heading][]

This makes it very easy and very quick to, for example, add a table of contents to an existing document – there’s also no need to add extra markup to the linked to heading (in this case) which simplifies and streamlines our document.

This syntax is available in most, if not all, editors that support MultiMarkdown, including my favourite Byword. The important phrase here is “that support MultiMarkdown” – this is not a feature of regular Markdown. Unfortunately, the Markdown supported by GitHub, GitHub Flavored Markdown (GFM), is a variation of regular MarkDown not MMD so, to include within-document links we have to revert to an ugly kludge. Firstly we have to precede the heading we want to link to with a HTML anchor tag:

<a name="headinglink">
### The Heading

and then link to it:

[Click this text to return to the heading](#headinglink)

This works because Markdown allows HTML to be embedded within a Markdown document. As MultiMarkdown is a superset of Markdown, it also supports this syntax as well as the newer style so this should be an acceptable, if ugly, solution in all cases. Note also that, unlike regular HTML, the heading being linked to must be on a separate line from the anchor tag. If you place them on the same line GitHub won’t render the heading properly.

Thankfully, GitHub makes it very easy for us to write and test our Markdown before committing it by providing three very useful resources:

  • Pressing the ‘m’ key while on pops up a Markdown cheat sheet showing the supported syntax
  • GitHub Flavored Markdown describes in more detail the options supported by GitHub and the differences between them and regular Markdown
  • The GFM Live Preview is a web page that allows us to enter some Markdown and instantly see how GitHub will interpret it.