What’s up with Markdown?

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.

Photo by Jan Kahánek on Unsplash

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

# A Title Header
## A Subtitle Header
#### And So On…
##### And So On…

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

 


Markdown Syntax: NORMAL TEXT
This is some normal text.                               White space is ignored by Markdown
until an empty line break.

Output – Normal Text

This is some normal text. White space is ignored by Markdown
until an empty line break.

Markdown Syntax – BULLET LIST
Use or + or *
+ Item A
* Item B
    * Item B1

–  Item C

Output: BULLET LIST

  • Item A
  • Item B
    • Item B1
  • Item C

Markdown Syntax: NUMBERED LIST

1. Item One
2. Item Two

3. Item Three

Output: NUMBERED LIST

  1. Item One
  2. Item Two
  3. Item Three

Markdown Syntax: BLOCK QUOTE

> Note: This is an important point so
> it needs to stand out.
>

> **FREE BEER!**

Output: BLOCK QUOTE

Note: This is an important point so it needs to stand out.

FREE BEER!


Markdown Syntax: CODE BLOCK

//Code blocks via indenting:
int main(string args[]) { `
writeln(“Hello World!”);`

}

Output: CODE BLOCK

//Code blocks via indenting:
int main(string args[]) {  ` 
    writeln("Hello World!");`
}

Markdown Syntax: INLINE HYPERLINK

This is an inline [hyperlink](https://daringfireball.net/projects/markdown).

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

Reference [hyperlinks][1] use a tag for the address which can be used in multiple places to use the same [link][1] [over][2] and [over][2]
[1]: https://en.wikipedia.org/wiki/Markdown

[2]: https://en.wikipedia.org/wiki/Hyperlink

Output: REFERENCE HYPERLINK

Reference hyperlinks use a tag for the address which can be used in multiple places to use the same link over and over
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!

4 thoughts on “What’s up with Markdown?”

  1. 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.

  2. “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.

  3. 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!

Leave a Reply to Ravi J Cancel reply

Your email address will not be published. Required fields are marked *