A tour of Markdown

Welcome! This email is a quick walkthrough of everything you can do when writing in Buttondown — from standard Markdown to features unique to the platform.

Text formatting

Markdown makes it easy to add emphasis to your writing:

• Bold text draws attention to key points
• Italic text adds subtle emphasis
• Strikethrough is handy for corrections or humor

You can also combine them: bold and italic work together just fine.

Headings

You've already seen a few headings in this email. They range from large (#) to small (######), and they're great for giving your newsletter structure:

This is a third-level heading

And a fourth-level heading

Most newsletters stick to two or three levels — that's usually plenty.

Blockquotes

Use blockquotes to highlight a passage or call out something important:

The single biggest problem in communication is the illusion that it has taken place.

— George Bernard Shaw

You can nest them, too:

A reader wrote in to say:

This is the best newsletter I've ever subscribed to.

Lists

Unordered lists are great for features, tips, or anything without a natural order:

• Keep your paragraphs short
• Use images to break up long sections
• Always preview before you send

Ordered lists work well for step-by-step instructions:

1. Write your draft in Markdown
2. Preview it in the editor
3. Send a test email to yourself
4. Hit publish when you're happy with it

Links

Linking is one of the things Markdown does best:

Visit Buttondown to learn more about building your newsletter.

You can also add a title that appears on hover: Markdown Guide is a great resource.

Images

Images make your newsletter more engaging. Here's how they work:

Code

For technical newsletters, inline code like git commit -m "first post" is invaluable.

Fenced code blocks with syntax highlighting work too:

def send_newsletter(subject, body):
    """Send a newsletter to all subscribers."""
    for subscriber in get_active_subscribers():
        deliver(subscriber.email, subject, body)

Tables

Tables are useful for comparisons or structured data:

Footnotes

Sometimes you want to add context without interrupting the flow. That's what footnotes are for¹.

You can use them for citations², asides, or any supplementary detail.

Buttondown-specific features

Everything above is standard Markdown. Below are features unique to Buttondown.

Template tags

You can personalize emails using template variables like or .

Conditionals work too:

Hey there, thanks for being a subscriber!

Premium content

If you have paid subscribers, you can gate content with premium blocks:

This paragraph is only visible to free subscribers — a great place to include an upgrade nudge.

Buttons

Add a styled call-to-action button anywhere in your email:

Snippets

Snippets let you reuse content across emails. If you've saved a snippet, insert it like this:

Embeds

Paste a URL on its own line and Buttondown will automatically embed it for supported platforms — YouTube, Twitter/X, Spotify, Vimeo, and more.

Comments

Finally, you can leave internal notes that your subscribers will never see:

That's a wrap! You now have a reference for every major feature. Happy writing.