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.