Learn what Markdown is, why you might use it, and how it fits into the Gatsby ecosystem.
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.
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.
# Markdown! You can use Markdown to create documents for [Gatsby](https://www.gatsbyjs.org/). <figure class="chart"> <object data="chart.svg" type="image/svg+xml"></object> <figcaption> Developers who love using Gatsby versus those who haven't tried it yet. </figcaption> </figure>
When converted to HTML, the preceding Markdown will become the markup below.
<h1>Markdown!</h1> <p> You can use Markdown to create documents for <a href="https://www.gatsbyjs.org/">Gatsby</a>. </p> <figure class="chart"> <object data="chart.svg" type="image/svg+xml"></object> <figcaption> Developers who love using Gatsby versus those who haven't tried it yet. </figcaption> </figure>
You can use Markdown files as a content source for your Gatsby site. To do so, you’ll need to install two plugins:
gatsby-transformer-remark. As with Gatsby itself, you can install both using npm.
npm install --save gatsby-source-filesystem gatsby-transformer-remark
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.