In this three-part post, we’ll be exploring what Markdown is and how it is used in my workflow for creating documentation. Part 1 focuses on how Markdown came to be, how it is used, and how it has evolved. In part 2, we’ll cover writing, viewing, and outputting Markdown. Finally, in part 3, I’ll introduce you to the Markdown syntax, so that you can begin writing documents in Markdown too.
Why I’m writing this blog post
I spend my day in a text editor and enjoy documenting most everything I do. Writing documentation that will be consumed by others is more friendly when formatting is used to call the reader’s attention to certain things – like making something bold indicates emphasis or importance. Or, maybe I have a piece of code that is best read as a block of code that is properly styled and formatted with a programming language’s syntax highlighting.
Markdown can do these things, right in your text editor, all in plain text.
Apple nerds (wear it proud) probably know the name John Gruber of Daring Fireball. Markdown dates back to 2004 when John and fellow co-creator, Aaron Swartz, wanted to be able to write for the web – think blogging – not using HTML but something more readable that could then, later, be turned into HTML.
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. – John Gruber, https://daringfireball.net/projects/markdown/
Nowadays, you’ll find Markdown everywhere and you may not have ever even noticed. Sometimes the syntax may vary slightly, but at its heart it’s Markdown. For example, you’ll find it in Slack. Have you ever done this
*Hello, world!* to make something bold? Or
_Hello, world!_ to italicize? Well, then, you’ve used Markdown.
Another popular place you’ll see it is Github. When you create a repository, there’s a default file called “readme.md”. Well, that “md” as the file extension stands for Markdown. If you want to have your text formatted in that file, you use the Markdown syntax.
Getting Started with Markdown
The general workflow from creation to viewing looks like this:
- Write a document using the Markdown syntax.
- Process the document to be converted to raw HTML.
- View in a browser (or other viewer).
I’m adding a forth item, which is save to PDF.
One thing you need to know is that Markdown has evolved since 2004. People have extended it. For example, adding support for math equations. There are also what are referred to as “Markdown Flavors”. These are slight variations on the Markdown syntax that add typography (like making text larger or smaller), styles (like alerts), or other features that might be useful in a certain context.
From this point forward, I am going to use GitHub’s version of the Markdown syntax.