Markdown Syntax

When writing comments or questions, you can use Markdown syntax to add links, emphasis, and headers. You can also add mathematical equations via LaTeX (rendered with KaTeX), which will convert LaTeX syntax into nicely typeset equations. We closely follow standard Markdown syntax, so the official documentation is the best place to look for a thorough explanation. Below is a brief overview of the most common features.

Inline elements

Links can be produced using [link title](http://and-link-address.com) or by surrounding a URL with < and >, like <http://www.example.com>. There are a number of shortcuts to make your life easier if you keep repeating the same link (see the docs), but these will cover 90% of the use cases.

Asterisks (*) and underscores (_) will both _italicize_ text, and two asterisks will make the text **bold**. The editor toolbar also supports underline formatting. Back-ticks denote fixed-width text. If you want small text, you can wrap it in a literal <small>html tag</small>. Special characters (*_#+-.!\) can be escaped using a backslash, like \*, if they would otherwise be converted into a markdown element.

We also allow a limited subset of HTML tags, which you can mix with markdown syntax if you want. These include: <a>, <p>, <em>, <strong>, <small>, <ol>, <ul>, <li>, <br>, <code>, <pre>, <blockquote>, <aside>, <div>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <math-inline>, <math-display>, <hr>, <table>, <thead>, <tbody>, <tr>, <th>, <td>, <del>, <sup>, <sub>.

Math

We supplement Markdown with LaTeX equation processing (rendered via KaTeX). Mathematical formatting works by placing your equation between $ and $ (for inline equations) or $$ and $$ (for displayed equations). You can also insert equations using the equation button in the editor toolbar. More complicated equations can be put in an align environment, like so

\begin{align}
  \log_2 \left ( \frac{p}{0.5} \right ) &= \log_2 \left ( p \right ) + 1 \\
  \log_2 \left ( \frac{p}{0.5} \right ) &= \frac{\log(p) - \log(0.5)}{\log(1) - \log(0.5)}
\end{align}

producing

Headers

Headers are easiest to add using hash marks, for example

# Primary header
## Secondary header
##### Fifth-level header

You can also select heading levels from the block type dropdown in the editor toolbar. Please use headers in comments sparingly!

Code

Inline code can be wrapped in single back-ticks, like `code`. Larger blocks of code can be wrapped in three back-ticks, optionally followed by a language name for syntax highlighting. For example:

```python
def hello_world():
    print('hello!')
```

Supported languages for syntax highlighting include: Plain text, TypeScript, TSX, JavaScript, JSX, Bash, Python, JSON, and SQL.

Quotes

If you want to quote someone, precede each line with a >:

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
> id sem consectetuer libero luctus adipiscing.

which would produce:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Lists

Markdown can handle both ordered and unordered lists. For example,

1. First item
2. Second item

    Another paragraph in the second item. (Note the 4-spaces indentation.)

    - Sublist item 1. (Note the 4-spaces indentation.)
    - Sublist item 2.

3. Third item.

produces:

1. First item
2. Second item

   Another paragraph in the second item. (Note the 4-spaces indentation.)

   • Sublist item 1. (Note the 4-spaces indentation.)
   • Sublist item 2.
3. Third item.

Unordered lists behave similarly, but use * or + or - to denote new items.

Tables

We support simple tables of the form:

| Header 1 | Header 2 |   ← headers
|----------|----------|   ← mandatory header separator
| Cell 1   | Cell 2   |   ← line 1
| Cell 3   | Cell 4   |   ← line 2

Columns are separated by the pipe character |, and each line is a row. For example, this:

|Year | Predictions |  Total |
|-----|-------------|--------|
|2015 |         500 |    500 |
|2016 |       25500 |  26000 |
|2017 |       21000 |  47000 |
|2018 |       63000 | 110000 |
|2019 |       50000 | 160000 |
|2020 |      220000 | 380000 |

Will render as:

You can also insert tables using the table button in the editor toolbar.

Horizontal rules

You can create a horizontal rule (thematic break) by typing three or more hyphens on a line:

---

This will render as a horizontal line across the page. You can also insert one using the toolbar button.

Mentions

In comments, you can mention other users by typing @ followed by their username. As you type, an autocomplete menu will appear with matching users. The following group mentions are also available:

• @moderators — notify the moderation team
• @admins — notify the admin team
• @predictors — notify predictors (available to curators and admins)

Embeds

Embedded questions

You can embed Metaculus questions directly in your content using the "+ Question" button in the editor toolbar. This lets you search for and select a question, which will be displayed as an interactive embed.

Twitter / X embeds

Links to tweets are automatically rendered as embedded tweets. Simply paste a tweet URL (from twitter.com or x.com) and it will be displayed as an embed when viewed.

Iframe embeds

We also allow <iframe> embeds from a limited list of trusted sites, currently including:

• afdc.energy.gov
• data.worldbank.org
• fred.stlouisfed.org
• ourworldindata.org
• www.eia.gov
• metaculus.com

For example, you can embed a Metaculus question via iframe:

<iframe src="https://www.metaculus.com/questions/embed/8/" height="320" width="550"></iframe>

will render as:

Images

You can upload images directly using the image button in the editor toolbar. Images up to 3 MB are supported.

Alternatively, you can use an <img> HTML tag:

<img src="https://upload.wikimedia.org/wikipedia/commons/4/48/Markdown-mark.svg" alt="markdown logo">

will render as:

Differences and limitations

The official Markdown specification lets users input raw HTML, but we limit users to the elements described above. For security reasons, something like <script>doSomethingEvil()</script> certainly won't work. We also employ a few markdown extensions that handle fenced code blocks (described above) and make lists and bolded text a little easier to manage.

The editor provides both a rich-text mode and a source mode. In source mode, you can write raw Markdown directly. A link to this help page is available at the top of the editor when in source mode.