From b3beb26ff45148a726f8c22b531b5b265f3fac98 Mon Sep 17 00:00:00 2001 From: axe312ger Date: Tue, 6 Jul 2021 14:12:01 +0100 Subject: [PATCH] add documentation for tags and a table of content to readme --- packages/gatsby-source-contentful/README.md | 96 +++++++++++++++++++-- 1 file changed, 87 insertions(+), 9 deletions(-) diff --git a/packages/gatsby-source-contentful/README.md b/packages/gatsby-source-contentful/README.md index 155c0be52065a..b54cf221df7ac 100644 --- a/packages/gatsby-source-contentful/README.md +++ b/packages/gatsby-source-contentful/README.md @@ -1,11 +1,42 @@ # gatsby-source-contentful -Source plugin for pulling content types, entries, and assets into Gatsby from -Contentful spaces. It creates links between entry types and asset so they can be -queried in Gatsby using GraphQL. - -An example site for using this plugin is at -https://using-contentful.gatsbyjs.org/ +> Source plugin for pulling content types, entries, and assets into Gatsby from +> Contentful spaces. It creates links between entry types and asset so they can be +> queried in Gatsby using GraphQL. +> +> An example site for using this plugin is at https://using-contentful.gatsbyjs.org/ + +
+Table of contents + +- [gatsby-source-contentful](#gatsby-source-contentful) + - [Install](#install) + - [How to use](#how-to-use) + - [Restrictions and limitations](#restrictions-and-limitations) + - [Using Delivery API](#using-delivery-api) + - [Using Preview API](#using-preview-api) + - [Offline](#offline) + - [Configuration options](#configuration-options) + - [How to query for nodes](#how-to-query-for-nodes) + - [Query for all nodes](#query-for-all-nodes) + - [Query for a single node](#query-for-a-single-node) + - [A note about LongText fields](#a-note-about-longtext-fields) + - [Duplicated entries](#duplicated-entries) + - [Query for Assets in ContentType nodes](#query-for-assets-in-contenttype-nodes) + - [More on Queries with Contentful and Gatsby](#more-on-queries-with-contentful-and-gatsby) + - [Using the new Gatsby image plugin](#using-the-new-gatsby-image-plugin) + - [Contentful Tags](#contentful-tags) + - [List available tags](#list-available-tags) + - [Filter content by tags](#filter-content-by-tags) + - [Contentful Rich Text](#contentful-rich-text) + - [Query Rich Text content and references](#query-rich-text-content-and-references) + - [Rendering](#rendering) + - [Download assets for static distribution](#download-assets-for-static-distribution) + - [Enable the feature with the `downloadLocal: true` option.](#enable-the-feature-with-the-downloadlocal-true-option) + - [Updating Queries for downloadLocal](#updating-queries-for-downloadlocal) + - [Sourcing From Multiple Contentful Spaces](#sourcing-from-multiple-contentful-spaces) + +
## Install @@ -136,6 +167,12 @@ Additional config which will get passed to [Contentfuls JS SDK](https://github.c Use this with caution, you might override values this plugin does set for you to connect to Contentful. +**`enableTags`** [boolean][optional] [default: `false`] + +Enable the new [tags feature](https://www.contentful.com/blog/2021/04/08/governance-tagging-metadata/). This will disallow the content type name `tags` till the next major version of this plugin. + +Learn how to use them at the [Contentful Tags](#contentful-tags) section. + ## How to query for nodes Two standard node types are available from Contentful: `Asset` and `ContentType`. @@ -298,6 +335,11 @@ To get **all** the `CaseStudy` nodes with `ShortText` fields `id`, `slug`, `titl When querying images you can use the `fixed`, `fluid` or `resize` nodes to get different sizes for the image (for example for using [`gatsby-image`](https://www.gatsbyjs.org/packages/gatsby-image/)). Their usage is documented at the [`gatsby-plugin-sharp`](https://www.gatsbyjs.org/packages/gatsby-plugin-sharp/) package. The only difference is that `gatsby-source-contentful` also allows setting only the `width` parameter for these node types, the height will then automatically be calculated according to the aspect ratio. +### More on Queries with Contentful and Gatsby + +It is strongly recommended that you take a look at how data flows in a real Contentful and Gatsby application to fully understand how the queries, Node.js functions and React components all come together. Check out the example site at +[using-contentful.gatsbyjs.org](https://using-contentful.gatsbyjs.org/). + ## Using the new Gatsby image plugin You can now use the beta [gatsby-plugin-image](https://gatsbyjs.com/plugins/gatsby-plugin-image/) to display high-performance, responsive images from Contentful. This plugin is the replacement for gatsby-image, and is currently in beta, but can help deliver improved performance, with a cleaner API. Support in gatsby-source-contentful is still experimental. @@ -336,10 +378,46 @@ module.exports = { } ``` -## More on Queries with Contentful and Gatsby +## [Contentful Tags](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/content-tags) -It is strongly recommended that you take a look at how data flows in a real Contentful and Gatsby application to fully understand how the queries, Node.js functions and React components all come together. Check out the example site at -[using-contentful.gatsbyjs.org](https://using-contentful.gatsbyjs.org/). +You need to set the `enableTags` flag to `true` to use this new feature. + +### List available tags + +This example lists all available tags. The sorting is optional. + +```graphql +query TagsQuery { + allContentfulTag(sort: { fields: contentful_id }) { + nodes { + name + contentful_id + } + } +} +``` + +### Filter content by tags + +This filters content entries that are tagged with the `numberInteger` tag. + +```graphql +query FilterByTagsQuery { + allContentfulNumber( + sort: { fields: contentful_id } + filter: { + metadata: { + tags: { elemMatch: { contentful_id: { eq: "numberInteger" } } } + } + } + ) { + nodes { + title + integer + } + } +} +``` ## [Contentful Rich Text](https://www.contentful.com/developers/docs/concepts/rich-text/)