nik codes

Archive for the month “August, 2013”

Semantic Markdown

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 Markable.in and Dillinger.io) 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:

GITHUB FLAVOR
=============

## syntax highlighted code
```ruby
require 'redcarpet'
markdown = Redcarpet.new("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

MARKDOWN EXTRA FLAVOR
=====================

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

## definition list
Apple
:   Pomaceous fruit of plants of the genus Malus in 
    the family Rosaceae.
Orange
:   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.

MULTIMARKDOWN FLAVOR
====================

## 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<<}.

AARON PARECKI FLAVOR
====================

## 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)
![:github](nikmd23/ossperks)

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:

MEMOFON
=======

- _italic_
- **bold**
- [links](http://google.com)
 - images
	![](/images/doc/grasshopper.png)
- 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:

mindmap

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!

Introducing Nonacat: Web Extensibility and Hacking GitHub

A few weeks ago I was honored to be selected as a speaker at MonkeySpace 2013 in Chicago.

monkeyspacelogo

For the uninitiated, MonkeySpace (formerly MonoSpace) is a cross-platform and open source conference which covers topics such as developing for the iPhone, Android, Mac, and *nix platforms using .NET technologies. It’s put on by the good folks at MonkeySquare, and has quickly become one of my favorite conferences.

My presentation was titled “Introducing Nonacat (Guerilla Hacking an Extra Arm onto GitHub)” and covered lots of “web extensibility” techniques, each with an example of extending the GitHub website/service. The presentation’s namesake, Nonacat, is a space-aged mutant version of GitHub’s Octocat with an extra arm. (“Nona” being the prefix for nine.)

nonacat
Nonacat designed by @headloose

The presentation covered lots of extensibility techniques and tools, which I promised I’d enumerate with plenty of links on my blog. So, without further ado, here is my list of wonderful tools to extend GitHub:

  • MarkdownPad – The only Windows based markdown editor I know of that fully supports GitHub flavored markdown, as well as instant preview and many other useful features. Great for working on long .md files.
  • Emoji Cheat Sheet – An online visual listing of all the emoji icons that GitHub (and several other services) support with nice click-to-copy functionality for quickly dropping an emoji into an issue comment. I’m sure this site was invaluable for the authors of Emoji Dick.
  • Contributing.md – A GitHub convention that allows for a repository owner to hook a message into “GitHub’s chrome” and describe the way that users should contribute to a project.
  • 5 Minute Fork – An ingenious little service from Remy Sharp that allows a user to clone and host a repository online with a click of a button. Here’s an example link, which when clicked will automatically clone my Oss Zero to Sixty repository and host it for you to browse online.
  • Huboard – A web based GitHub issue management GUI with a Trello/kanban board vibe.
  • jsFiddle – Many of my readers will know about jsFiddle, but did you know that it automatically hooks into GitHub Gist’s? This is a great feature to leverage to enable shareable, executable code samples.
  • Executify – A service very similar to jsFiddle, but for C# code based on scriptcs.
  • User Scripts – There are lots of pre-build portable little user scripts out there that enhance the GitHub experience. User scripts are much lighter weight than browser extensions and very easy to write since they are based on JavaScript and the browser API’s you already know. I’ve created one for tracking user votes on GitHub issues.
  • Web Hooks – Not a tool specifically, but rather a technique. I covered tools useful to debug a web hook including RequestBin, PageKite and my favorite: nGrok.
  • Revision.io – A service for creating a shareable, embeddable change log from your GitHub repository.
  • Signatory.io – A service I created to demonstrate GitHub’s API and web hooks which allows repository owners to manage their contributor license agreements painlessly.
  • Diagramming Tools – If a picture is worth a thousand words, than we should be putting more of them into our online conversations. AsciiFlow (ascii diagrams), WebSequenceDiagrams.com (sequence diagrams), MemoFon (mind maps) and yUml (uml class diagrams) allow you to do just that with convenient (and editable) text based input mechanisms.
  • Issue2PR – I didn’t find out about this service until after the conference, but it is very handy as it allows you to convert any given issue in your repository to a pull request.

If you have a service, tool or technique that improves your GitHub experience, please do share it in the comments.

NOTE: The video of this presentation, although not as high quality as I’d like, is now available:

Introducing Nonacat (Guerilla Hacking an Extra Arm onto GitHub) – Nik Molnar from Monkey Square on Vimeo.

Post Navigation