gatsby-transformer-remark-rehype

Parses Markdown files using Remark & Rehype.

This package is a mod of gatsby-transformer-remark

Install

npm install gatsby-transformer-remark

How to use

// 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,
      // Gatsby flavor plugins configs
      plugins: [],
      // Remark plugins
      remarkPlugins: [],
      // Rehype plugins
      rehypePlugins: []
    },
  },
],

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.

Parsing algorithm

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.

How to query

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

Getting table of contents

// todo

Excerpts

Length

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)
      }
    }
  }
}

Format

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 excerpt contains markdown content—e.g. header, link, etc.—and you want these links to render as HTML.

{
  allMarkdownRemark {
    edges {
      node {
        excerpt(format: HTML)
      }
    }
  }
}

You can also get excerpts in Markdown format.

{
  allMarkdownRemark {
    edges {
      node {
        excerpt(format: MARKDOWN)
      }
    }
  }
}

gray-matter options

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.

Example: Excerpts

If you don’t want to use pruneLength for excerpts but a custom separator, you can specify an excerpt_separator in the gatsby-config.js file:

{
  "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.

Troubleshooting

Excerpts for non-latin languages

By default, excerpt uses underscore.string/prune which doesn’t handle non-latin characters (https://github.com/epeli/underscore.string/issues/418).

If that is the case, you can set truncate option on excerpt field, like:

{
  markdownRemark {
    excerpt(truncate: true)
  }
}

Excerpts for HTML embedded in Markdown files

If your Markdown file contains HTML, excerpt will not return a value.

In that case, you can set an excerpt_separator in the gatsby-config.js file:

{
  "resolve": `gatsby-transformer-remark`,
  "options": {
    "excerpt_separator": `<!-- endexcerpt -->`
  }
}

Edit your Markdown files to include that HTML tag after the text you’d like to appear in the excerpt:

---
title: "my little pony"
date: "2017-09-18T23:19:51.246Z"
---

<p>Where oh where is that pony?</p>
<!-- endexcerpt -->
<p>Is he in the stable or down by the stream?</p>

Then specify MARKDOWN as the format in your GraphQL query:

{
  markdownRemark {
    excerpt(format: MARKDOWN)
  }
}