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!

Headings

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

Lists

Unordered

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

How unordered lists are rendered in HTML:

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

Ordered

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

Blockquote

  • 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

Code comments

Inline

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

Code blocks

  • Indent a block by four spaces

MD vs MDX

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

Frontmatter

  • 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

Edit this page on GitHub