Switch branches/tags
Find file History
pieh chore(release): Publish
 - gatsby-cli@2.4.5
 - gatsby-codemods@1.0.7
 - gatsby-dev-cli@2.4.7
 - gatsby-image@2.0.20
 - gatsby-plugin-catch-links@2.0.7
 - gatsby-plugin-cxs@2.0.2
 - gatsby-plugin-google-gtag@1.0.4
 - gatsby-plugin-layout@1.0.8
 - gatsby-plugin-manifest@2.0.8
 - gatsby-plugin-netlify-cms@3.0.7
 - gatsby-plugin-netlify@2.0.4
 - gatsby-plugin-offline@2.0.13
 - gatsby-plugin-page-creator@2.0.4
 - gatsby-plugin-remove-trailing-slashes@2.0.5
 - gatsby-plugin-sass@2.0.4
 - gatsby-remark-autolink-headers@2.0.11
 - gatsby-source-contentful@2.0.13
 - gatsby-source-drupal@3.0.8
 - gatsby-source-filesystem@2.0.8
 - gatsby-source-mongodb@2.0.8
 - gatsby-source-wordpress@3.0.13
 - gatsby-transformer-csv@2.0.4
 - gatsby-transformer-javascript-frontmatter@2.0.4
 - gatsby-transformer-pdf@1.0.14
 - gatsby-transformer-remark@2.1.12
 - gatsby-transformer-screenshot@2.0.7
 - gatsby-transformer-xml@2.0.4
 - gatsby-transformer-yaml@2.1.5
 - gatsby@2.0.41
Latest commit f9714a5 Nov 8, 2018
Permalink
..
Failed to load latest commit information.
src
.babelrc
.gitignore
.npmignore
CHANGELOG.md
README.md
index.js
package.json

README.md

gatsby-transformer-remark

Parses Markdown files using Remark.

Install

npm install --save gatsby-transformer-remark

How to use

// In your gatsby-config.js
plugins: [`gatsby-transformer-remark`]

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

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.

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

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