Markdown mode

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 write in Markdown, you can drag and drop your image into the editor.

Once the image is uploaded, you can update the alt text by changing the contents of the text in the square brackets. This will look something like:

If you'd like to turn the image into a link you can with Markdown! To do this, you'll wrap all the image code inside a Markdown link, like so:

Markdown also supports LaTeX blocks. To add a LaTeX block in the editor, wrap your LaTeX expression inside a <div> tag with the class buttondown-block-math. For example, [ a^2 + b^2 = c^2 ] would be written as:

<div class='buttondown-block-math'>[ a^2 + b^2 = c^2 ]</div>

You can also switch between Markdown and Fancy Mode without losing your LaTeX block.

(Note that as of now, LaTeX is only renderable as a "block", and not inline with text.)

If you have existing content in other formats like HTML, Word documents, or Google Docs, you can convert it to Markdown before pasting it into Buttondown. Here are some tools that can help:

• Pandoc is a free, open-source command-line tool that converts between dozens of formats. It's the gold standard for document conversion. For example, to convert an HTML file to Markdown: pandoc -f html -t markdown input.html -o output.md
• Word to Markdown Converter converts .docx files to Markdown directly in your browser.
• Paste to Markdown lets you paste HTML or rich text and get Markdown back — handy for converting content from Google Docs, Notion, or web pages.
• Turndown is an HTML-to-Markdown converter you can try in your browser.

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.