Skip to main content

Markdown Syntax

Markdown is a very common way to write content in Gatsby posts and pages. This guide contains tips for Markdown syntax and formatting that might come in handy!


# heading 1

## heading 2

### heading 3

#### heading 4

##### heading 5

###### heading 6

Here’s how those tags render in HTML:

heading 1

heading 2

heading 3

heading 4

heading 5
heading 6
  • each heading gets converted to their HTML equivalent
    • i.e. # heading 1 is <h1>heading 1</h1>
  • Correct usage of each heading should follow the accessibility guidelines set by the World Wide Web Consortium (W3C) Note: in the Gatsby docs, h1s are already included from title entries in frontmatter metadata, and contributions in Markdown should begin with h2.

Emphasized text

  • Italic

    • one asterisk or one underscore
      • *italic* or _italic_
      • italic!
  • Bold

    • two asterisks or two underscores
      • **bold** or __bold__
      • bold!
  • Italic and Bold

    • three asterisks or three underscore
      • ***italic and bold*** or ___italic and bold___
      • italic and bold!!



  • can use *, -, or + for each list item
* Gatsby
  * docs
- Gatsby
  - docs
+ Gatsby
  + docs

How unordered lists are rendered in HTML:

  • Gatsby
    • docs
  • Gatsby
    • docs
  • Gatsby
    • docs


  • number and period for each list item
  • using 1. for each item can automatically increment depending on the content
1. One
1. Two
1. Three
  1. One
  2. Two
  3. Three

Links in Markdown use this format. URLs can be relative or remote:


Example of a link rendering in HTML:

Gatsby site

Image with alt text

![alt text](path-to-image)

Image without alt text

This pattern is appropriate for decorative or repetitive images:



  • Use > to declare a blockquote
  • Adding multiple > with create nested blockquotes
  • It is recommended to place > before each line
  • You can use other Markdown syntax inside blockquotes
> blockquote
> > nested blockquote
> > **I'm bold!**
> more quotes


nested blockquote

I’m bold!

more quotes

Code comments


  • Enclose the text in backticks `code`
  • Inline code looks like this sentence

Code blocks

  • Indent a block by four spaces


  • MDX is a superset of Markdown. It allows you to write JSX inside markdown. This includes importing and rendering React components!

Processing Markdown and MDX in Gatsby:

  • In order to process and use Markdown or MDX in Gatsby, you can use the gatsby-source-filesystem plugin
  • You can check out the package README for more information on how it works!


  • Metadata for your Markdown
  • Variables that can later be injected into your components
  • Must be:
    • At the top of the file
    • Valid YAML
    • Between triple dashed lines
    title: My Frontmatter Title
    example_boolean: true

Frontmatter + MDX example

description: A simple example of a description in frontmatter

import { Chart } from "../components/chart"

# Here’s a chart

The chart is rendered inside our MDX document.

<Chart description={description} />

Helpful resources

Edit this page on GitHub