Ever heard of Markdown? The odds you have are slim unless you are a web developer and/or frequent GitHub.com. In short, Markdown is a simple way to format text using very terse markup symbols. The result is an easy-to-read, easy-to-write document which is then converted to HTML or PDF for display to it’s intended audience.
GITHUB.COM MAKES MARKDOWN A STAR
Created in 2004 by John Gruber, Markdown’s popularity has exploded over the last several years. This is due mainly to the aforementioned GitHub.com, who utilize it to format the release notes (README.md) of projects hosted on the site. As a locus for developers of all stripes, GitHub raised Markdown’s profile tremendously by exposing it the 31 million users (as of Nov. 2018) using the site. This has led to Markdown’s inclusion in many of the tools developers use to create software.
End Users Benefit
Markdown’s sudden ubiquity is actually good news for software users. Why? It is difficult to convey exactly how demotivated your average developer is when faced with the task of creating release notes. The fun is in the coding not the documentation. This reluctance has resulted in less-than-stellar documentation efforts over the years in a myriad of applications. The simplicity of Markdown has made it much easier to produce quality documentation with minimal effort.
Generating Content
None of the major web browsers convert Markdown for display directly – if wrong, please correct me – so this necessitates an intermediary step to convert it to HTML or PDF. The good news is there are a plethora of tools, usually written in JavaScript, which perform the conversion with many offering an array of output styles from which to choose.
Markdown Syntax
So what does Markdown actually look like? Below is a brief tutorial which demonstrates many of the symbols used to create a Markdown document. The sections in blue show the actual Markdown syntax followed by the final output section in red.
I’ll provide several links at the end if you are interested in learning more.
Markdown Syntax: HEADERS
###### And So On…
Output: HEADERS
A Title Header
A Subtitle Header
And So On…
And So On…
And So On…
Markdown Syntax:: HORIZONTAL LINE
***
Output: HORIZONTAL LINE
Output – Normal Text
– Item C
Output: BULLET LIST
- Item A
- Item B
- Item B1
- Item C
Markdown Syntax: NUMBERED LIST
3. Item Three
Output: NUMBERED LIST
- Item One
- Item Two
- Item Three
Markdown Syntax: BLOCK QUOTE
> **FREE BEER!**
Output: BLOCK QUOTE
Note: This is an important point so it needs to stand out.
FREE BEER!
Markdown Syntax: CODE BLOCK
}
Output: CODE BLOCK
//Code blocks via indenting:
int main(string args[]) { `
writeln("Hello World!");`
}
Markdown Syntax: INLINE HYPERLINK
A hyperlink with the actual address: <http://example.com/>
Output: INLINE HYPERLINK
This is an inline hyperlink.
A hyperlink with the actual address: http://example.com/
Markdown Syntax: REFERENCE HYPERLINK
[2]: https://en.wikipedia.org/wiki/Hyperlink
Output: REFERENCE HYPERLINK
Additional Resources
While this tutorial is over, there are plenty of additional resource on the web to continue your journey in mastering Markdown. Good Luck!
Thanks for the concise and helpful introduction to Markdown.
I code in HTML and CSS for web development but have been using a variant of Markdown for publishing my ebooks. It doesn’t give me full typographical control over my material, but that’s a small price to pay for its simplicity. I can concentrate on writing. Sometimes simple is best.
“I’m not aware of any major web browser that parses Markdown directly – please correct me – so this necessitates an intermediary step to convert it to HTML.”
There is a “Markdown view” button in Vivaldi’s Notes. This probably is the closest implementation right now. Of course it would be great to have online markdown documents to be visually rendered, too, and with “Save as” option to a number of formats.
Hi. Thank you for this: a step in the right direction.
When Markdown was introduced into back into the browser recently I raised the issue on the news forum, that not many users would know what Markdown was or how to use it, and that Team Vivaldi were missing an opportunity to be friendly and provide local help, instead asking users to trawl the web and learn themselves.
Team Vivaldi were strangely resistant to the concept, trying to argue that Markdown was commonplace, despite the fact that their chosen example of this, Reddit, actually provided a handy help (?) to click that explained the syntax right next to the comment box and weren’t making the same assumption Vivaldi was.
I was therefore pleased to see that your own article starts with the opposite assumption and then grasps the opportunity to help out – kudos!
Just like hefty XML became JSON, it’s now HTML that’s making way for MARKDOWN.