Community Plugin

@maiertech/gatsby-theme-tags-core

A Gatsby theme to add tagging support to MDX pages. This theme processes nodes of type Mdx only, which are created by gatsby-plugin-mdx. Only those Mdx nodes are processed, which fulfill the compatibility requirements described below.

Options

Option	Default	Description
`basePath`	`/`	Basepath for deployments at locations other than root.
`tagCollection`	tags	The tag collection is part of the path of tag pages.
`mdxCollections`	`[]`	Array of collections from which the theme collects tags. The theme looks at the `collection` field of `Mdx` nodes. If array is empty, no tag pages are generated.

When is a theme compatible?

A theme is compatible with @maiertech/gatsby-theme-tags-core if all of the following requirements are met:

It uses gatsby-plugin-mdx as parent theme.
It adds fields collection and path to Mdx nodes.
It supports a title and tags properties in the frontmatter of MDX pages it processes, i.e., template queries include frontmatter.tags and frontmatter.title.

Let’s start with the last requirement. Frontmatter of tagged MDX pages needs to include the following keys:

Key	Required	Description
`title`	✓
`tags`	✓	Array of tags. Think of tags as keys, not strings, that might be used for pulling localization strings later on. Therefore, tags should not contain spaces.

The frontmatter can also include optional date and description keys. date is optional, because tagging should also work for content types without a date, e.g., notes. description is optional to allow for alterantive ways of deriving a description, e.g., from the first paragraph.

The second requirement states that corresponding Mdx nodes need to contain the following fields:

Field	Required	Description
`collection`	✓	Collection to which a node belongs.
`path`	✓	Path to generated page.

All of above fields and frontmatter keys, including optional keys, are made availalbe via the TaggedItem fragment, which is used in the tag-query.js template.

Potential pitfalls

@maiertech/gatsby-theme-core-tags uses the following query in gatsby-config.js to retrieve all tags:

const result = await graphql(
  `
    query($mdxCollections: [String]!) {
      allMdx(filter: { fields: { collection: { in: $mdxCollections } } }) {
        group(field: frontmatter___tags) {
          tag: fieldValue
          count: totalCount
        }
      }
    }
  `,
  { mdxCollections }
);

This query uses Gatsby’s group on frontmatter___tags. This field is inferred by Gatsby and exists only when there is at least one tag in any tagged collection. You also need to be aware that the moment you add @maiertech/gatsby-theme-tags-core to your dependencies, Gatsby will extract and run the query exported in the tag-query.js template. This fails as well with error GraphQLError: Field “tags” is not defined by type MdxFrontmatterFilterInput. when there are no tags. It is not clear why Gatsby extracts and runs the query even when the theme is not configured in gatsby-config.js.

This means that you cannot add @maiertech/gatsby-theme-tags-core as dependency without also adding at least one tag to any tagged collection.