Markdown
Learn what Markdown is, why you might use it, and how it fits into the Gatsby ecosystem.
What is Markdown?
Markdown is a plain text syntax for writing text documents that can be transformed to HTML. Markdown uses punctuation characters to indicate HTML elements. That punctuation then gets converted to HTML tags during a transformation or export process.
Markdown dates back to 2004, when John Gruber published the original Markdown syntax guide. Gruber, along with Aaron Swartz, created Markdown with two goals:
- to make Markdown
as easy-to-read and easy-to-write as is feasible.
; and - to support inline HTML within Markdown-formatted text.
Text-to-HTML filters such as Textile define a syntax that replaces a wide range of HTML elements. Other filters, such as reStructuredText, do not support inline HTML tags.
Markdown, by contrast, only defines a syntax for a small subset of HTML elements. For other elements, you use the corresponding HTML tag. In other words, Markdown makes it possible to write documents without knowing HTML, but HTML is available if you need it. A Markdown document might look like the example that follows.
When converted to HTML, the preceding Markdown will become the markup below.
You can use Markdown files as a content source for your Gatsby site. To do so, you’ll need to install two plugins: gatsby-source-filesystem and gatsby-transformer-remark. As with Gatsby itself, you can install both using npm.
The gatsby-source-filesystem plugin reads files from your computer. The gatsby-transformer-remark plugin makes the contents of your Markdown files available to GraphQL.
You can also try a Gatsby starter package that has Markdown support already included.
Learn more about Markdown
- Markdown syntax from the Gatsby docs
- CommonMark, a proposed Markdown specification
- Sourcing from the Filesystem from the Gatsby docs
- Adding Markdown Pages from the Gatsby docs