Building composable themes requires a slightly different mindset than building a conventional site. Consider the following cases with one Gatsby theme and one site.
Our site is built as usual, with whatever tech we prefer, etc. We also specify a theme as such:
A typical query on a site can look like this. Note that
there's nothing inherently wrong with this query, it sorts
by the publish date, filters out draft posts. When using the
same query in a site however, there's one main aspect of
this query that becomes problematic quickly:
To understand why
allMdx is problematic in a themes
setting, consider the scenario where you have blog posts in
content/posts and pages that you've written using MDX in
src/pages. The blog posts need to be pulled into the
Gatsby node system using
gatsby-source-filesystem and to
add a table of contents to our
src/pages pages, we put
src/pages. So we end
up with a config like this in our
So the query we've written collects all of the
across both filesystem sources, which is not likely to be
what we want. The problem gets worse when you introduce
which generate Mdx nodes into the Gatsby system. This causes
even more content to match our query.
To fix this, we can take a variety of different paths. One
is to change the query to an
allFile query. Functionally,
this is a similar query as our original
allMdx query. The
main differences are that we end up fetching drafts as well
and we have to programmatically sort after we fetch as well.
One unfortunate consequence of this is that it locks us into using files as our data source. If someone is using a headless CMS then they can't use our theme with this query because we are now querying the source of our content instead of the format.
We can solve this problem by adding a new field to our
isNote. This is the ultimate in flexibility
because it allows us to define whatever we want as the
criteria for what constitutes a Note.
Then if we have a
title field in our
Mdx files, we can
filter the result set:
This is very flexible in that it allows us to access every
field as we're used to on
Mdx or any other type. It is
restricting in that we can't combine multiple types to
provide notes. To do that, we'll have to look in to
Constructing Query Types in Themes.