Using Markdown

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

Element	Syntax	Output
Heading	# H1 ## H2 ### H3	H1 H2 H3
Bold	**bold text**	bold text
Italic	*italic text*	italic text
Ordered list	1. Foo 2. Bar 3. Baz	Foo Bar Baz
Unordered list	- Foo - Baz - Bar	Foo Bar Baz
Code	`code`	code
Horizontal rule	---
Link	[link](https://google.com)	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

If you're looking for an escape hatch out of these embeds, they only trigger on links that are on self-contained lines, like the following:

Here is a tweet I liked!

https://twitter.com/rachsyme/status/1352057677359288321

So you can avoid it by simply doing something like:

Here is a tweet I liked!

<div>https://twitter.com/rachsyme/status/1352057677359288321</div>

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.