Transformer plugins

This tutorial is part of a series about Gatsby’s data layer. Make sure you’ve gone through part 4 and part 5 before continuing here.

What’s in this tutorial?

The previous tutorial showed how source plugins bring data into Gatsby’s data system. In this tutorial, you’ll learn how transformer plugins transform the raw content brought by source plugins. The combination of source plugins and transformer plugins can handle all data sourcing and data transformation you might need when building a Gatsby site.

Transformer plugins

Often, the format of the data you get from source plugins isn’t what you want touse to build your website. The filesystem source plugin lets you query dataabout files but what if you want to query data inside files?

To make this possible, Gatsby supports transformer plugins which take rawcontent from source plugins and transform it into something more usable.

For example, markdown files. Markdown is nice to write in but when you build apage with it, you need the markdown to be HTML.

Add a markdown file to your site atsrc/pages/sweet-pandas-eating-sweets.md (This will become your first markdownblog post) and learn how to transform it to HTML using transformer plugins andGraphQL.

Once you save the file, look at /my-files/ again—the new markdown file is inthe table. This is a very powerful feature of Gatsby. Like the earliersiteMetadata example, source plugins can live-reload data.gatsby-source-filesystem is always scanning for new files to be added and whenthey are, re-runs your queries.

Add a transformer plugin that can transform markdown files:

Then add it to the gatsby-config.js like normal:

Restart the development server then refresh (or open again) GraphiQL and lookat the autocomplete:

Select allMarkdownRemark again and run it as you did for allFile. You’llsee there the markdown file you recently added. Explore the fields that areavailable on the MarkdownRemark node.

Ok! Hopefully, some basics are starting to fall into place. Source plugins bringdata into Gatsby’s data system and transformer plugins transform raw contentbrought by source plugins. This pattern can handle all data sourcing anddata transformation you might need when building a Gatsby site.

Create a list of your site’s markdown files in src/pages/index.js

Now you’ll have to create a list of your markdown files on the front page. Like manyblogs, you want to end up with a list of links on the front page pointing to eachblog post. With GraphQL you can query for the current list of markdown blogposts so you won’t need to maintain the list manually.

Like with the src/pages/my-files.js page, replace src/pages/index.js withthe following to add a GraphQL query with some initial HTML and styling.

Now the frontpage should look like:

But your one blog post looks a bit lonely. So let’s add another one atsrc/pages/pandas-and-bananas.md

Which looks great! Except… the order of the posts is wrong.

But this is easy to fix. When querying a connection of some type, you can pass avariety of arguments to the GraphQL query. You can sort and filter nodes, set howmany nodes to skip, and choose the limit of how many nodes to retrieve. Withthis powerful set of operators, you can select any data you want—in the format youneed.

In your index page’s GraphQL query, change allMarkdownRemark toallMarkdownRemark(sort: { fields: [frontmatter__date], order: DESC }). _Note: There are 3 underscores between frontmatter and date. Savethis and the sort order should be fixed.

Try opening GraphiQL and playing with different sort options. You can sort theallFile connection along with other connections.

For more documentation on our query operators, explore our GraphQL reference guide.

Challenge

Try creating a new page containing a blog post and see what happens to the list of blog posts on the homepage!

What’s coming next?

This is great! You’ve just created a nice index page where you’re querying your markdownfiles and producing a list of blog post titles and excerpts. But you don’t want to just see excerpts, you want actual pages for your markdown files.

You could continue to create pages by placing React components in src/pages. However, you’llnext learn how to programmatically create pages from data. Gatsby is not_limited to making pages from files like many static site generators. Gatsby letsyou use GraphQL to query your _data and map the query results to pages—all at buildtime. This is a really powerful idea. You’ll be exploring its implications andways to use it in the next tutorial, where you’ll learn how to programmatically create pages from data.