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.


Flashcards for Byword Keyboard Shortcuts now available from GitHub

The set of flashcards I created for Byword Keyboard Shortcuts on the Mac are now available to download from GitHub. Four versions of the cards are available – tilde-delimited, tab-delimited, Excel spreadsheet and Mental Case study exchange. These should allow you to import the cards into almost any Flashcard application.



In addition, I have also uploaded the cards to two more websites – and the excellent This means that they are now available, free of charge, from:



Are you a Byword Master?

If you have used the Byword Markdown editor on the Mac you’ll already know that knowledge of the keyboard shortcuts is essential if you really want to get the full benefit of the clean, uncluttered interface, especially in full-screen mode.

As a complement to my recently created set of flashcards for Byword I have created a new Smarterer test. With 59 possible questions, offered in a rapid-fire multiple choice format, this test will allow you to really evaluate your skills in just a few minutes.

After successful completion of the test you’ll receive a badge indicating your skill level that you can add to your resume or website. You can see mine at the bottom of the right-hand sidebar… unfortunately WordPress (.com) doesn’t allow embedded Javascript so it doesn’t appear exactly as it should but it is still effective.





Flashcards for Byword Keyboard Shortcuts

Whenever I have to write a substantial amount of text — more than a few hundred words — then Markdown is my format of choice and Byword on Mac OSX my editor of choice. With its beautifully uncluttered, full-screen interface it makes writing both pleasurable and more productive.

But… if you really want to get the best out of Byword then a good knowledge of the keyboard shortcuts is essential. The last thing you want is to have to pause in full flow and take your hand off the keyboard to reach for the mouse or trackpad to indent a paragraph.

A new set of flashcards I have created and uploaded to Quizlet and Flashcard Exchange contains 60 of the most useful Byword shortcuts. As always, you can use them online or download them, free of charge, into your favourite flashcard app.