Markdown Syntax

When adding comments or suggesting questions, you can take advantage of Markdown syntax to add links, emphasis, and headers. Additionally, you can add mathematical equations via MathJax, which will convert LaTeX syntax into nicely typeset equations. We closely follow the official Markdown syntax, so that's the best place to look for a thorough explanation of how the system works. We provide a brief overview of the most common uses here.

Inline elements

Links can be produced using a [link title](http://and-link-address.com) or by surrounding a link 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**. 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 MathJax equation processing. Mathematical formatting works by placing your equation between \( and \) (for inline equations) or \[ and \] (for displayed equations). 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

Please use headers in comments sparingly!

Code

Big chunks of code can be wrapped in three back-ticks. For example:

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

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:

Embeds

We 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

Note that this means you can embed Metaculus questions:

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

will render as:

Note that for now this is only possible in question bodies, not in comments.

Images

We also allow <img> images:

<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 example, if you try to input an image using ![Alt text](/path/to/img.jpg) the output will look like <img alt="Alt text" src="/path/to/img.jpg"/>, and 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.