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

One
Two
Three

Links and images

Link

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!