Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

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!


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

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
  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

Image without alt text

This pattern is appropriate for decorative or repetitive images:


  • Use > to declare a blockquote
  • Adding multiple > will create nested blockquotes
  • It is recommended to place > before each line
  • You can use other Markdown syntax inside blockquotes


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

Frontmatter + MDX example

Helpful resources

Start building today on Netlify!
Edit this page on GitHub
© 2023 Gatsby, Inc.