A quick tour of Markdown — where it came from, why I love it, how to use it.

What is Markdown?

Markdown is a markup DSL designed to be human-readable that can also be rendered into semantically correct XHTML.

Readability, however, is emphasized above all else. 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.

Due to its concise yet natural syntax it’s become the defacto standard in community forums (Reddit, StackOverflow), blogging platforms (Hugo, Jekyll), and every online wiki.

Why I Love Markdown

I find great joy in tools that have been paired down to their simplest form, at an abstraction level that’s not condescending, that’s internally consistent, while remaining highly composable.

Spend More Time Editing, Less Time Formatting

Most online rich-text/HTML editors inject massive amounts of garbage HTML, which I take personally. To the point where I’ll spend hours cleaning up rarely referenced wiki pages.

Tips

Format With Intent

Never break your user’s trust with UX inconsistencies. Feature adoption drops when a feature isn’t consistent.

  • Pick a formatting style and stick with it
  • Pay special attention to inline code references like CosmosDbFailover
  • Common drift areas:
    • Mixing bullet style (* vs - — pick one)
    • Forgetting space between hash and text (#Title vs # Title)

Don’t Fight the Constraints

  • Trust in the content, not the formatting
  • Simplify the design instead of hacking around Markdown
  • Rarely need to mix HTML with Markdown
  • Write for the content, not the render

Code Blocks

Use triple ticks with language hints:

  {
    "userId": "1234-ABCD-9876-DCBA"
}
  
  # Convert Date and Time To UTC Time
$a = Get-Date
$a.ToUniversalTime()

Inline Code

Code can be inline, such as “class Zuul has a dependency on GateKeeper”.

Avoid Too Many Call-Outs

Call-outs (bolded IMPORTANT, block quoted tips) used sparingly hold the line well. Add too many and nothing’s important.

If more than “some percentage” of a document is call-outs, the issue is often mixing tones — exposition, extemporization, detailed steps. Pick a single tone or group similar tones.

General Tips

  • Use emoji with intent and purpose
  • Don’t be scared of white-space
  • Think in terms of outline/TOC
  • Use citation references for link-heavy documents
  • Don’t worry about ordered list numbering:
    1. this
    2. much better
    3. works

References

Imported from shawn-notebook