This plugin dynamically creates and updates table of content (toc) for all articles in a series.
yarn add gatsby-remark-series
In your gatsby-config.js file
resolve: "gatsby-transformer-remark"options:plugins:resolve: "gatsby-remark-series"options:render:// The location where the toc should be rendered.// Default: bottom// Optionalplaceholder: "both" | "top" | "bottom" | string// Provides a way to customize the output of the toc.// Default: check utils/DefaultTemplate for details// Optionalstring// Indicates a landing page is required.// This will render the toc using template and will generate// a landing page for the series with all articles listed.// Default: false// OptionaluseLandingPage: boolean// This can only be used in conjunction with useLandingPage=true.// Provides a way to specify a prefix for the slug of the series.// This prefix is independent of the pathPrefix provided by gatsby.// Default: null// OptionallandingPagePathPrefix: string// This can only be used in conjunction with useLandingPage=true.// Provides the path to the template layout (react component)// to be used to render the external toc.// This component receives the series articles in the pageContext.// For more information please refer to examples/series.jsx// Defaults: null// Required!landingPageComponent: stringresolvers:// Locates and resolves the slug on the node.// Default: node.frontmatter.slug// Returns: string// Optionalstring// Locates and resolves the date on the node.// Default: node.frontmatter.date// Returns: string// Optionalstring// Locates and resolves the draft flag on the node.// Indicates the post is a draft, default behavior is to show the title,// but without a link to the post. This can be overridden with a new template.// Default: node.frontmatter.draft// Returns: boolean// Optionalboolean// Locates and resolves the order on the node.// Indicates the position of the post in the series.// Default: node.frontmatter.order// Returns: number// Optionalnumber// Locates and resolves the name of the series on the node.// Default: node.frontmatter.series// Returns: string// Optionalstring// Takes a string and converts it to a slug representation.// This is used to calculate the path for the external landing page.// In theory, should match the algorithm you are using to generate// your urls.// Default: converts the string to kebab-case using lodash.kebabCase.string
In your markdown files
---title: **article title**series: **series name**order: **number**draft: **true | false**---<!-- **placeholder** -->
- series is required to identify the articles.
- order and draft are optional, just in case you want to reorder things or make people aware there are more articles coming.
<!-- placeholder -->is only required when the
render.placeholdersetting has a value other than both, top or bottom. In those case, the placeholder has to be expressed as a comment in the code using
Given the following configuration
resolve: "gatsby-transformer-remark"options:plugins:resolve: "gatsby-remark-series"render:placeholder: "toc"
Will turn this
---title: My Titleseries: CSS and HTML tricks---# My Title<!-- toc -->Content
Into this (approximately)
My TitleOther posts in the CSS and HTML tricks seriesMy Title<!-- more <li> with all articles that match the series name -->Content
- The plugin does not provide any default styling for the toc.
- The plugin does not provide a default layout for series landing pages, but it provides a concrete example in examples/series.jsx
MIT, by Patricio Trevino