nik codes

Semantic Markdown


Markdown, the lite, little, plain-text markup language that could just keeps growing and growing.

It’s heavily leveraged by two of the most prominent developer communities on the internet, GitHub and StackOverflow, and is supported on more sites everyday. To be honest, I quite frequently find myself accidentally typing Markdown into Gmail because I’ve just grown so accustomed to it. Markdown has several good browser based editors (like and as well as fantastic desktop editors for Windows (MarkdownPad) and OSX (Mou) as well we parsing libraries for every programming platform on the planet. Markdown is almost nine years old now and at this point I think it’s safe to say that it has become ubiquitous in the information technology space. What’s particularly interesting to me, and what this post it about, is the similarities in growth patterns between Markdown and the heavy weight champion of rich text markup; HTML.

During the late 90’s browser wars, vendors “embraced and extended” HTML in all kinds of crazy ways. (Remember the <blink> and <marquee> tags?) Likewise, Markdown is “embraced and extended” in the form of “flavors”, the most famous of which is GitHub’s flavored Markdown. GitHub has extended the language with all sorts of auto-hyperlinking syntactic sugar, syntax highlighted code and to-do lists complete with checkbox status indicators. The Markdown Extra project adds the ability to create tables, definition lists, footnotes and abbreviations. MultiMarkdown includes bibliographical style citations, support for mathematic equations, and “critic markup” similar to how you’d see an editor review a document. Aaron Parecki has enhanced Markdown to support user defined macros and binding to YAML data sets and there are several other flavors roaming around out there (which mostly do less interesting things).

Here’s some examples of Markdown flavors:


## syntax highlighted code
require 'redcarpet'
markdown ="Hello World!")
puts markdown.to_html

## to-do list
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item


## table
| Item      | Value |
| --------- | -----:|
| Computer  | $1600 |
| Phone     |   $12 |
| Pipe      |    $1 |

## definition list
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.
:   The fruit of an evergreen tree of the genus Citrus.

## footnote
That's some text with a footnote.[^1]
[^1]: And that's the footnote.


## citation
Let's cite a fake book.[p. 42][#fake]
[#fake]: John Doe. *A Totally Fake Book*. Vanity Press, 2006. 

## review
Strike out a {--word--}.
Insert a {++word++}.
Replace a {~~word~>with another~~}.
Highlight a {==word==}.
Comment on something.{>>This is a comment<<}.


## yaml binding
title: Semantic Markdown
author: {first: Nik, last: Molnar}
description: some yaml content
This post, '#{title}', is by #{author.first}...

## macro
![:vimeo 600x400](13697303)
![:youtube 600x400](G-M7ECt3-zY)

Of course, just like HTML, the deviations from “the Markdown standard” have some people concerned. Jeff Atwood posted a call to action to see Markdown standardized and the W3C Markdown Community Group has produced a set of standard Markdown tests to test parsers with. We’ll all have to wait and see what shakes out of the debates moving forward.

The really exciting, somewhat recent, advancement in this space is the rise of what I’m calling Semantic Markdown. Semantic Markdown, like semantic HTML, is just standard (or flavor enhanced) Markdown that is structured in such a way to make it machine readable.

I’ve been thinking about this technique for several months now since it is the cornerstone of Semantic Release Notes, a specialized format for writing software release notes that Anthony and I have been working on in our spare time. The idea is simple, a user writes Markdown formatted in such a way that our parser can understand what new features, breaking changes and bugs were addressed in a given release of a piece of software.

Turns out, we’re not the only ones who have had this idea!

API Blueprint uses Semantic Markdown to document REST and web API’s. The input Semantic Markdown can be automatically turned into an interactive documentation website, test suites, mocks and more. The creators of API Blueprint even have tools that help developers generate Markdown from cURL trace output.

With much less focus on developers, Memofon uses Semantic Markdown to generate interactive, shareable mind maps. For example this Markdown:


- _italic_
- **bold**
- [links](
 - images
- blockquote
  > The question is, whether you can make
  >> words mean so many different things.
- code
    var test = function test() {
      return this.isTest();

produces this mind map:


which is extremely cool!

Finally, Fountain, a Semantic Markdown based screenplay authoring format that provides for things like characters, scenes and dialog is rendered out in the standard screenplay format. This can be seen in the Fountain and PDF versions of the screenplay for the 2003 movie Big Fish.

I really like the idea of Semantic Markdown and am glad to see it beginning to gain traction. Of course it’s easy to write, requires no special tooling and is human readable – but all those benefits come directly from Markdown itself. It’s also easy to parse out domain specific semantics once the Markdown has been parsed into HTML because libraries like CsQuery and HTML Agility Pack make it easy to navigate HTML with CSS selectors and XPath expressions, at least more approachable than dealing with abstract syntax trees yourself.

So take a spin with these Semantic Markdown tools and continue to expand the possible uses of Markdown!

Single Post Navigation

3 thoughts on “Semantic Markdown

  1. Pingback: The Morning Brew - Chris Alcock » The Morning Brew #1426

  2. Hi,

    Do you know of any open semantic web markdown standard, draft or just suggestions written on the back of a napkin?

  3. nikmd23 on said:

    I’ve seen nothing even close to a standard. Depending on what you are trying to do, you may want to look at micro-format “standards” and see if they can be adapted to MarkDown.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: