Overview

The official MDX site describes MDX as 'an authorable format that lets you seamlessly write JSX in your Markdown documents.' This means you can import and embed React components right into your Markdown posts using JSX tags.

If you prefer not to use MDX, you can instead write regular Markdown. Elements such as code blocks and tables are automatically styled by the theme (and these styles are easily customized), so you can focus on writing great content.

JSX Syntax

One of the most powerful features of MDX is that it allows React components to be rendered alongside Markdown. React is written in JSX, which is a syntax extension to JavaScript. React components are added to MDX using JSX tags.

These JSX tags look like HTML tags, but they have slightly different syntax and terminology. JSX attributes are passed to the React component as props. In an MDX file, a block of Markdown text between JSX tags is a child, which also gets passed to the React component in a prop called children.

In the following example, the text 'Allo' is a child of the Box component, and p, color, and bg are props:

Allo

<Box
  p={3}
  color="primary"
  bg="white"
>

Allo

</Box>

<Box
  p={3}
  color="primary"
  bg="white"
>
Allo
</Box>

If a prop value is a string, it should be wrapped in quotation marks (""). If the prop value is a variable or a type other than a string, wrap it in curly braces ({}). To ensure proper rendering, add a blank line above and below the Markdown text, and don't indent it.

Frontmatter

Frontmatter contains data about the post, such as the title and description. It is written in YAML. Frontmatter is placed at the top of the MDX file between sets of three hyphens (---). Each frontmatter field should be placed on its own line.

See Configuration: Frontmatter for the available frontmatter fields in Chicago Docs.

---
title: The full title of your site
shortTitle: A shorter title
description: Use some key words here to help users find this post
---
## Secondary header
Write regular MDX here.

To learn more about how frontmatter fields are used in Gatsby themes, see Using Frontmatter in MDX.

Markdown Syntax

MDX is a combination of Markdown and JSX, and regular Markdown syntax can be used for most formatting. What follows is a guide to the Markdown syntax supported by Gatsby. Each section gives the Markdown syntax, the HTML element it creates, and a demonstration of the element.

Headings

Headings are usually created in Markdown with a set of hash (#) characters placed before the text for the heading, with a space in between (this space is required in Gatsby). The number of hashes corresponds to the level of the heading (i.e., # corresponds to a first-level heading, or the <h1> HTML tag).

There is alternative syntax for <h1> and <h2> headings:

Emphasis

Italics

To mark text in italics, add an asterisk (*) or underscore (_) before and after the text to be formatted.

Bold

To mark text in boldface, add two asterisks (**) or two underscores (__) before and after the text to be formatted.

Bold and italics together

To emphasize text with both boldface and italics, use three asterisks (***) or three underscores (___) before and after the text to be formatted.

Line breaks

To create a line break, follow a line with two spaces and then hit enter. An alternative that is easier to see is the <br /> tag; add this tag between the two lines of text to be separated with a line break.

This is the first line. <br /> This is the second line.

This is the first line.<br />
This is the second line.

Both of these render as

This is the first line.
This is the second line.

Block quotes

A block quote is a piece of text that is indented from the rest of the text. Block quotes are created by placing a greater-than sign (>) before each line in the quote.

> So we beat on, boats against the current, borne back ceaselessly into the past.

This renders as

So we beat on, boats against the current, borne back ceaselessly into the past.

A block quote can contain other Markdown formatting as well as blank lines and nested block quotes. Nested block quotes are created using additional greater-than signs (>>).

> *Dear Mr. Carraway.*
>
> *This has been one of the most terrible shocks of my life to me I hardly can believe it that it is true at all. Such a mad act as that man did should make us all think. I cannot come down now as I am tied up in some very important business and cannot get mixed up in this thing now. If there is anything I can do a little later let me know in a letter by Edgar. I hardly know where I am when I hear about a thing like this and am completely knocked down and out.*
>
>> *Yours truly*
>>> **MEYER WOLFSHIEM**
>
> and then hasty addenda beneath:
>> *Let me know about the funeral etc do not know his family at all.*

This renders as

Dear Mr. Carraway.

This has been one of the most terrible shocks of my life to me I hardly can believe it that it is true at all. Such a mad act as that man did should make us all think. I cannot come down now as I am tied up in some very important business and cannot get mixed up in this thing now. If there is anything I can do a little later let me know in a letter by Edgar. I hardly know where I am when I hear about a thing like this and am completely knocked down and out.

Yours truly

MEYER WOLFSHIEM

and then hasty addenda beneath:

Let me know about the funeral etc do not know his family at all.

Lists

There are several ways to organize related items into ordered and unordered lists in Markdown.

Unordered lists

To create an unordered list, place an asterisk (*), minus sign (-), or plus sign (+) followed by a space before each item:

* Oranges
* Apples
+ Oranges
+ Apples
- Oranges
- Apples

This creates an unordered list in HTML:

<ul>
    <li>Oranges</li>
    <li>Apples</li>
</ul>

This renders as

• Oranges
• Apples

Ordered lists

To create an ordered list, place a numeral followed by a period (.) and a space before each item in the list:

1. Oranges
2. Apples

This creates an ordered list in HTML:

<ol>
    <li>Oranges</li>
    <li>Apples</li>
</ol>

This renders as

1. Oranges
2. Apples

A fun fact here is that only the starting number matters. The numbers after it can be any number and will still render in numerical order from the first number.

2. Oranges
4. Apples
55. Berries
0. Bananas

This renders as

2. Oranges
3. Apples
4. Berries
5. Bananas

Nested lists

To create a nested list, indent the nested items.

* Apples
* Oranges
* Berries
    * Strawberries
    * Raspberries

This renders as

• Apples
• Oranges
• Berries
  • Strawberries
  • Raspberries

Tables

Table columns are created by surrounding text in pipe (|) characters. To create a table header, place sets of three or more hyphens (---) between pipe characters in the second row (the first row then becomes the header). You can use most Markdown syntax inside the table.

Note that the cell widths don't need to be even in Markdown. They will render evenly in the browser.

| Name | Type | Description |
| ---- | ---- | ----------- |
| `name` | string | Name of the resource |
| `path` | string | Path to the resource |

This renders as

You can align items inside table cells (cells are left aligned by default) by combining colons (:) with the hyphens (-) in the second row:

| Left | Center | Right |
| :--- | :----: | ----: |
| Left-aligned text | Center-aligned text | Right-aligned text |

This renders as

For a table component designed for API docs, see the PropertyTable React component from Chicago Docs.

Images

To add an image, first add an exclamation mark (!) followed by the alt text for the image in square brackets (e.g., ![Image alt text]) and the filename of the image in parentheses [e.g., (filename.jpg)].

![The cat trap in action](sahand-babali-unsplash.jpg)

The equivalent HTML element is the following:

<img alt="The cat trap in action" src="../src/assets/sahand-babali-unsplash.jpg" />

This renders a cute cat pic:

For a fluid image (one that adjusts its size in response to the screen size), use the Image component. This component uses gatsby-image to optimize and lazy load your images.

Links

To create an external link in Markdown, write the link text in square brackets (e.g., [eBay]) followed by the URL in parentheses [e.g., (https://ebay.com)].

A URL on its own is automatically converted into an HTML link. For example, https://github.com renders as https://github.com.

See Components and Hooks: External and Internal Links to see how Chicago Docs creates internal and external links from your Markdown links.

Code

Inline code

Inline code refers to text in the middle of a sentence that is formatted in a different font (such as Monospace). It is used for things like variable and function names. It can also be used to print text literally without having to escape special characters.

To mark text as inline code, enclose it in backticks (`).

Code blocks

Create a code block by adding three or more backticks (`) on the lines above and below the block. This is referred to as a fenced code block.

```
plugins: [
  'gatsby-plugin-mdx',
]
```

Alternatively, indent the block by four spaces:

    plugins: [
      'gatsby-plugin-mdx',
    ]

This creates something like the following HTML:

<pre>
  <code>plugins: [ 'gatsby-plugin-mdx', ]</code>
</pre>

This renders as

plugins: [
  'gatsby-plugin-mdx',
]

To add line hightlighting, line numbers, and live preview, see Components and Hooks: Code.

````
outer code block
```
inner code block
```
````

outer code block
```
inner code block
```