Parses Markdown files using Remark.
npm install --save gatsby-transformer-remark
// In your gatsby-config.js
plugins: [
{
resolve: `gatsby-transformer-remark`,
options: {
// CommonMark mode (default: true)
commonmark: true,
// Footnotes mode (default: true)
footnotes: true,
// Pedantic mode (default: true)
pedantic: true,
// GitHub Flavored Markdown mode (default: true)
gfm: true,
// Plugins configs
plugins: [],
},
},
],
The following parts of options
are passed down to Remark as options:
options.commonmark
options.footnotes
options.pedantic
options.gfm
The details of the Remark options above could be found in remark-parse
's documentation
A full explanation of how to use markdown in Gatsby can be found here: Creating a Blog with Gatsby
There are many Gatsby Remark plugins which you can install to customize how Markdown is processed. Many of them are demoed at https://using-remark.gatsbyjs.org/. See also the source code for using-remark.
It recognizes files with the following extensions as Markdown:
- md
- markdown
Each Markdown file is parsed into a node of type MarkdownRemark
.
All frontmatter fields are converted into GraphQL fields. TODO link to docs on auto-inferring types/fields.
This plugin adds additional fields to the MarkdownRemark
GraphQL type
including html
, excerpt
, headings
, etc. Other Gatsby plugins can also add
additional fields.
A sample GraphQL query to get MarkdownRemark nodes:
{
allMarkdownRemark {
edges {
node {
html
headings {
depth
value
}
frontmatter {
# Assumes you're using title in your frontmatter.
title
}
}
}
}
}
Using the following GraphQL query you'll be able to get the table of contents
{
allMarkdownRemark {
edges {
node {
html
tableOfContents(pathToSlugField: "frontmatter.path")
frontmatter {
# Assumes you're using path in your frontmatter.
path
}
}
}
}
}
By default the tableOfContents is using the field slug
to generate URLs. You can however provide another field using the pathToSlugField parameter. Note that providing a non existing field will cause the result to be null.
By default, excerpts have a maximum length of 140 characters. You can change the default using the pruneLength
argument. For example, if you need 500 characters, you can specify:
{
allMarkdownRemark {
edges {
node {
html
excerpt(pruneLength: 500)
}
}
}
}
By default, Gatsby will return excerpts as plain text. This might be useful for populating opengraph HTML tags for SEO reasons. You can also explicitly specify a PLAIN
format like so:
{
allMarkdownRemark {
edges {
node {
excerpt(format: PLAIN)
}
}
}
}
It's also possible to ask Gatsby to return excerpts formatted as HTML. You might use this if you have a blog post whose an excerpt contains markdown content--e.g. header, link, etc.--and you want these links to render as HTML.
{
allMarkdownRemark {
edges {
node {
excerpt(format: HTML)
}
}
}
}
gatsby-transformer-remark
uses gray-matter to parse markdown frontmatter, so you can specify any of the options mentioned here in the gatsby-config.js
file.
If you don't want to use pruneLength
for excerpts but a custom seperator, you can specify an excerpt_separator
:
{
"resolve": `gatsby-transformer-remark`,
"options": {
"excerpt_separator": `<!-- end -->`
}
}
Any file that does not have the given excerpt_separator
will fall back to the default pruning method.
By default, excerpt
uses underscore.string/prune
which doesn't handle non-latin characters (esamattis/underscore.string#418).
If that is the case, you can set truncate
option on excerpt
field, like:
{
markdownRemark {
excerpt(truncate: true)
}
}