Markdown is a lightweight markup language that makes it easy to add things like links, images, lists, and styles to plain text.

It was created by John Gruber back in 2004 and has quickly become nigh-ubiquitous thanks to its simple goal:

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.

There's a good chance that, even if you haven't heard of Markdown, you've used it before! It powers applications like Reddit and GitHub.

Using Markdown is different than using a WYSIWYG editor. In an application like Microsoft Word, you click buttons to format words and phrases, and the changes are visible immediately. Markdown isn’t like that. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different

For example, to denote a heading, you add a number sign before it (e.g., # Heading One). Or to make a phrase bold, you add two asterisks before and after it (e.g., this text is bold). It may take a while to get used to seeing Markdown syntax in your text, but it's very quick to learn.

Markdown doesn’t have all the bells and whistles of word processors like Microsoft Word or other WYSIWYG editors, but it shines at creating simple, elegant documents — which is what Buttondown is all about.

Markdown syntax guide

Heading

Bold

Italic

Ordered List

Unordered List

Code

Horizontal Rule

Link

Image


If you're looking for a in-depth guide for more Markdown tips and tricks, I highly recommend the unofficial but authoritative Markdown Guide.

Buttondown's Markdown rendering engine

Buttondown's Markdown rendering engine is Python-Markdown. Some details about the gnarly implementation below: feel free to ignore this unless you're a Buttondown (and/or Markdown) power user!

Extensions

In addition, Buttondown uses a handful of extensions:

• smarty, to convert ASCII characters into HTML entities
• tables, to allow basic tables
• footnotes, to allow basic footnotes. (These are rendered in your online archives using littlefoot.js)
• fenced_code, to allow a more common approach for embedding code snippets
• pymdownx.tilde, for allowing of deletions and subscripts
• CodeHilite, for syntax highlighting of code snippets

Embeds

In addition to all of those, Buttondown uses some proprietary extensions for embedding things like tweets, YouTube videos, and gifs — but none of these should affect your general rendering experience.

Embeds can be invoked by putting the URL of the resource (Tweet, post, image, etc.) on its own line. Only the URL should be on the line. Any additional whitespace or characters will intercept the magic of embeds.

Embeds support URLs from the following sources:

• Bandcamp
• Gist
• Giphy
• Instagram
• Spotify
• SoundCloud
• Twitter
• Vimeo
• YouTube

Play around with it!

Escaping

Embeds only trigger on their own self-contained lines. If you're looking for an escape hatch out of these embeds, you can simply wrap the link in an HTML tag, like so:

Tables of contents

If you're interested in creating a table of contents in your Buttondown newsletter, be sure to use names (such as <a name='heading'>) rather than ids (such as <a id='heading'>)! Gmail and many other email clients strip id tags from emails, which will break internal links.