System Interrupt Me!

A blog by a Mac user.

Markdown and Breaking the Page Metaphor

For those of you that don’t realize it but care, this site is created using Octopress from the text-based content that I write using the Markdown syntax. And those of you that realize this is a site created using Octopress will know that I use Markdown syntax in the text-based content that I create for the posts.

Following on from a discussion I had with a fellow member of INCOSE, I wrote him an note describing Markdown and the various tools that I use to create my Markdown content. While writing that note I had a bit of an epiphany and so, to quote myself:

I think the power of Markdown is that it breaks the “everything is a page” metaphor that we’ve all got locked into with our Word and Pages, etc., document editors. [I’ve deliberately tried to say “content” rather than “document” in this post.] Once you have created your content using Markdown you can then decide which media/medium you would like to use to present it, e.g. web post, document, etc.

(I’m sure this is just me remembering what someone else had written, so my apologies to them!)

I thought I would share some of the note I wrote for those of you that want to know a bit more about Markdown and how I use it. Please read on…

The Markdown syntax is described on John Gruber’s site.

(Bearing in mind that I use Macs for work and play) I use the following applications in my Markdown toolchain: I can use any text editor for creating content that uses Markdown – vi, nano, TextEditor, TextWrangler, etc. However I generally use Byword for creating & editing text content, especially if I’m going to do a lot of Markdown writing. Byword displays some of the Markdown syntax as you type so words in italics appears in italics, etc.

Although Byword can also fully render Markdown, I use an application called Marked to render the Markdown in near real-time as I type it up in Byword. The reason for this is that Marked can render the Markdown using a specific Cascading Style Sheet (CSS) which is useful if you are creating the content for a website.

Both Byword and Marked can export Markdown content into other formats:

  • Byword: HTML; PDF; RTF; Word; Latex.
  • Marked: HTML; PDF; RTF.

I have been using Markdown for few months, primarily for creating blog posts that will be rendered by Octopress. Look through this site for examples of what comes out after Octopress renders the Markdown into HTML.

The beauty of using Markdown is that I can use a simple text editor to create what ends up being transformed into complex posts without having to worry about HTML and CSS – Octopress deals with all that. Because the source is all text-based files, I can use Git for my configuration management / source control.

(Although its getting a bit off topic) the simplicity of the Markdown content means I can have a very simple but powerful write-on-any-device set up. My main Mac syncs with my Git server (in the cloud) so I can load content onto my MacBook via Git when traveling. Through Dropbox I can also use Byword and/or Nebulous on my iPad for creating/editing content as well. (And the Dropbox and Git files are synchronized in case you are wondering…)

I think the power of Markdown is that it breaks the “everything is a page” metaphor that we’ve all got locked into with our Word and Pages, etc., document editors. [I’ve deliberately tried to say “content” rather than “document” in this post.] Once you have created your content using Markdown you can then decide which media/medium you would like to use to present it, e.g. web post, document, etc.

I think it would be nice to see the systems engineering and software engineering tools allowing Markdown to be used by the user when they input content into the various documentation fields in the tools. Then when it comes to displaying or exporting the content, the tool can make use of any Markdown syntax that is present and render the content accordingly. If it is not present, it doesn’t matter and the plain text is displayed/exported.