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

Markdown has a few implementations. Buttondown starts from Python-Markdown, and we add a handful of extensions & tools to make your editing experience even better.


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

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

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!

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:

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.