Markdown in MDN

Warning

This document is a work-in-progress draft at the moment.

It's not actually possible, yet, to write MDN documentation using Markdown, so at the moment this document is used to record the decisions we've made about how we will expect Markdown to be written, when it is supported.

This page describes how we use Markdown to write documentation on MDN. We have chosen GitHub-Flavored Markdown (GFM) as a baseline, and added some extensions to support some of the things we need to do on MDN that aren't readily supported in GFM.

Baseline: GitHub-Flavored Markdown

The baseline for MDN Markdown is GitHub-Flavored Markdown (GFM): https://github.github.com/gfm/. This means that for anything not otherwise specified in this page, you can refer to the GFM specification. GFM in turn is a superset of CommonMark (http://spec.commonmark.org/).

GFM and CommonMark describe some extensions to the original Markdown description). We'll highlight two that are going to be important to us.

Code fences and info strings

In GFM and CommonMark, authors can use "code fences" to demarcate <pre> blocks. The opening code fence may be followed by some text that is called the "info string". From the spec:

The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag.

It's permissible for the info string to contain multiple words, like:

```fee fi fo fum
// some example code
```

Tables

In GFM (but not CommonMark) there is a syntax for tables: https://github.github.com/gfm/#tables-extension-. We will make use of this but it should be noted that this syntax imposes limitations on the kinds of tables we can write, so in many cases this syntax will not be appropriate and we will need alternative ways of authoring tables.

In particular:

  • GFM tables must have a header row.
  • GFM tables may not have a header column.
  • GFM won't parse GFM block elements in table cells.

This last point means that if you write:

--------------------------------------
|  i'm a test    | yes i am          |
|----------------|-------------------|
| `inline` is ok | * lists aren't    |
--------------------------------------

...then the attempt to write a list in the bottom-right cell will just generate <td>* lists aren't</td> in the output.

Extensions to GFM

In this section we'll outline ways in which writers will be able to go beyond the syntax defined in the GFM spec.

Example code blocks

Writers will use code fences for example code blocks. They must specify the language of the code sample using the first word of the info string, and this will be used to provide syntax highlighting for the block. The following words will be supported:
  • bash
  • cpp (for C/C++)
  • css
  • html
  • java
  • js (for JavaScript)
  • json
  • php
  • python
  • sql
  • xml
  • wasm (for WebAssembly text format)
For example:
```js
const greeting = "I will get syntax highlighting";
```

Writers will be able to supply any one of the following additional words, which must come after the language word:

  • example-good: style this example as a good example (one to follow)
  • example-bad: style this example as a bad example (one to avoid)
  • hidden: don't render this code block in the page. This is for use in live samples.
For example:
```js example-good
const greeting = "I'm a good example";
```

Notes, warnings, and callouts

Sometimes writers want to call special attention to some piece of content. To do this, they will use a GFM blockquote with a special first paragraph. There are three types of these: notes, warnings, and callouts.

  • To add a note, create a GFM blockquote whose first paragraph starts with **Note:**.
  • To add a warning, create a GFM blockquote whose first paragraph starts with **Warning:**.
  • To add a callout, create a GFM blockquote whose first paragraph starts with **Callout:**.

Notes and warnings will render the Note: or Warning: text in the output, while callouts will not. This makes callouts a good choice when an author wants to provide a custom title.

Processing of the markup works on the AST it produces, not on the exact characters provided. This means that providing <strong>Note:</strong> will also generate a note. However, the Markdown syntax is required as a matter of style.

Multiple lines are produced by an empty block quote line in the same way as normal paragraphs. Further, multiple lines without a space are also treated like normal markdown lines, and concatenated.

The blockquote can contain code blocks or other block elements.

Because the text "Note:" or "Warning:" also appears in the rendered output, it has to be sensitive to translations. In practice this means that every locale supported by MDN must supply its own translation of these strings, and the platform must recognize them as indicating that the construct needs special treatment.

Examples

Note
> **Note:** This is how you write a note.
>
> It can have multiple lines.

This will produce the following HTML:

<div class="notecard note">
  <p><strong>Note:</strong> This is how you write a note.</p>
  <p>It can have multiple lines.</p>
</div>

This HTML will be rendered as a highlighted box, like:

Note: This is how you write a note.

It can have multiple lines.

Warnings
> **Warning: This is how you write a warning.
>
> It can have multiple paragraphs.

This will produce the following HTML:

<div class="notecard warning">
  <p><strong>Warning:</strong> This is how you write a warning.</p>
  <p>It can have multiple paragraphs.</p>
</div>

This HTML will be rendered as a highlighted box, like:

Warning: This is how you write a warning.

It can have multiple paragraphs.

Callouts
> **Callout:** **This is how you write a callout**.
>
> It can have multiple paragaphs.

This will produce the following HTML:

<div class="callout">
  <p><strong>This is how you write a callout.</strong></p>
  <p>It can have multiple paragraphs.</p>
</div>

This HTML will be rendered as a highlighted box, like:

This is how you write a callout.

It can have multiple paragraphs.

Translated warning

For example, if we want to use "Warnung" for "Warning" in German, then in German pages we would write:

> Warnung: So schreibt man eine Warnung.

...and this will produce:

<div class="notecard warning">
  <p><strong>Warnung:</strong> So schreibt man eine Warnung.</p>
</div>
Note containing a code block

This example contains a code block.

> **Note:** This is how you write a note.
>
> It can contain code blocks.
>
> ```js
> const s = "I'm in a code block";
> ```
> Like that.

This will produce the following HTML:

<div class="notecard note">
  <p><strong>Note:</strong> This is how you write a note.</p>
  <p>It can contain code blocks.</p>
  <pre class="brush: js">const s = "I'm in a code block";</pre>
  <p>Like that.</p>
</div>

This HTML will be rendered as with a code block, like:

Note: This is how you write a note.

It can contain code blocks.

const s = "I'm in a code block";

Like that.

Definition lists

Tables

Heading IDs

Live samples

Inline styles

KumaScript

Writers will be able to include KumaScript macro calls in prose content:

The **`margin`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) property sets the [margin area](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model) on all four sides of an element. It is a shorthand for margin-top, margin-right, margin-bottom, and margin-left.

{{EmbedInteractiveExample("pages/css/margin.html")}}

The top and bottom margins have no effect on replaced inline elements, such as <span> or <code>.