Basic markup

Design philosophy

“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.” - from John Gruber’s philosophy for Markdown.

Take a moment to view the simple-example.md file in GitHub for a simple example of Markdown and how it’s rendered.

By design, Markdown syntax elements are comprised of punctuation characters. The characters were carefully chosen to convey meaning. For example:

  • Asterisks around a word actually look like emphasis

  • Markdown lists look like lists

  • Blockquotes look like quoted passages of text

    “… assuming you’ve ever used email”

Compare the plaintext (Raw) view to the syntax-highlighted view (Code) to the rendered view (Preview).