feat(docs): Table of Contents component (#15251)

* Initial progress on Table of Contents

* Apply suggestions from code review

Co-Authored-By: gillkyle <kylerobertgill@gmail.com>

* updating header to h2

* Merging Flo's work in and added frontmatter field to disable TOC

Co-authored-by: Florian Kissling <21834+fk@users.noreply.github.com>

* Moved h2 into nav component

* Bring back `sizes` token additions, fixes tests

* Revert changes in `packages/gatsby-design-tokens`

* Prevent ToC content becoming inaccessible

…when exceeding the viewport height via `max-height` and `overflow: auto`

* fix: prettier fix and disabling one missing ToC field

docs/contributing/gatsby-style-guide.md

@@ -7,49 +7,6 @@ will be full of relevant articles written to be easily understood by the many pe
 
 The community plans, writes, and maintains these Docs on GitHub.
 
-## Table of Contents
-
-- [Welcome!](#welcome)
-- [What kinds of docs can I write?](#what-kinds-of-docs-can-i-write)
-- [Writing process](#writing-process)
-  - [Think of your audience](#think-of-your-audience)
-  - [Research](#research)
-  - [Write drafts and get feedback](#write-drafts-and-get-feedback)
-- [Word choice](#word-choice)
-  - [Use "you" as the pronoun](#use-you-as-the-pronoun)
-  - [Avoid "easy" and "simple"](#avoid-easy-and-simple)
-  - [Avoid emojis, slang, and metaphors](#avoid-emojis-slang-and-metaphors)
-  - [Define jargon](#define-jargon)
-- [Writing style](#writing-style)
-  - [Write concisely](#write-concisely)
-  - [Use clear hyperlinks](#use-clear-hyperlinks)
-  - [Indicate when something is optional](#indicate-when-something-is-optional)
-  - [Abbreviate terms](#abbreviate-terms)
-  - [Use SEO optimized titles](#use-seo-optimized-titles)
-- [Grammar & formatting](#grammar-and-formatting)
-  - [Format titles and headers](#format-titles-and-headers)
-  - [Format code blocks, inline code, and images](#format-code-blocks-inline-code-and-images)
-  - [Capitalize proper nouns](#capitalize-proper-nouns)
-  - [Use active voice](#use-active-voice)
-  - [Make lists clear with the Oxford Comma](#make-lists-clear-with-the-oxford-comma)
-  - [Use apps that help you edit](#use-apps-that-help-you-edit)
-- [Best practices](#best-practices)
-  - [Support software versions](#software-versions)
-  - [Share best practices whenever possible](#share-best-practices-whenever-possible)
-- [The difference between tutorials, recipes, and docs](#the-difference-between-tutorials-recipes-and-docs)
-- [Tutorials](#tutorials)
-  - [Tutorials Audience](#tutorials-audience)
-  - [Tutorials Purpose](#tutorials-purpose)
-  - [Tutorials Tone and style](#tutorials-tone-and-style)
-- [Recipes](#recipes)
-  - [Recipes Audience](#recipes-audience)
-  - [Recipes Purpose](#recipes-purpose)
-  - [Recipes Tone and style](#recipes-tone-and-style)
-- [Docs](#docs)
-  - [Docs Audience](#docs-audience)
-  - [Docs Purpose](#docs-purpose)
-  - [Docs Tone and style](#docs-tone-and-style)
-
 ## Welcome!
 
 You don't have to be an expert in a

docs/docs/creating-a-source-plugin.md

@@ -12,22 +12,6 @@ and "transformer" plugins.
 
 This doc focuses on source plugins and uses `gatsby-source-filesystem` to explain how source plugins work.
 
-# Table of Contents
-
-- [What do source plugins do?](#what-do-source-plugins-do)
-- [What fields are required?](#what-fields-are-required)
-- [`media type` is not required, yet necessary to work with transformer plugins](#media-type-is-not-required-yet-necessary-to-work-with-transformer-plugins)
-- [What does the code look like?](#what-does-the-code-look-like)
-- [What are the jobs of a source plugin?](#what-are-the-jobs-of-a-source-plugin)
-- [Getting helper functions](#getting-helper-functions)
-- [Advanced](#advanced)
-- [Two ways of adding relationships between nodes](#two-ways-of-adding-relationships-between-nodes)
-  - [Option 1: transformation relationships](#option-1-transformation-relationships)
-  - [Option 2: foreign-key relationships](#option-2-foreign-key-relationships)
-    - [Creating the relationship](#creating-the-relationship)
-    - [Creating the reverse relationship](#creating-the-reverse-relationship)
-  - [Union types](#union-types)
-
 ## What do source plugins do?
 
 The [`gatsby-source-filesystem`](/packages/gatsby-source-filesystem/) plugin

docs/docs/glossary.md

@@ -1,5 +1,6 @@
 ---
 title: Glossary
+disableTableOfContents: true
 ---
 
 import HorizontalNavList from "../../www/src/components/horizontal-nav-list.js"

docs/docs/mdx/plugins.md

@@ -2,11 +2,6 @@
 title: MDX Plugins
 ---
 
-## Table of contents
-
-- [Gatsby remark plugins](#gatsby-remark-plugins)
-- [remark plugins](#remark-plugins)
-
 ## Gatsby remark plugins
 
 `gatsby-plugin-mdx` is compatible with all of the [gatsby-remark

docs/docs/mdx/programmatically-creating-pages.md

@@ -12,14 +12,6 @@ support for MDX so you can start your blog. The posts will live in
 `gatsby-source-filesystem` and [`createPages`](/docs/node-apis/#createPages) in
 `gatsby-node.js`.
 
-## Table of contents
-
-- [Source from the filesystem](#source-mdx-pages-from-the-filesystem)
-- [Add MDX files](#add-mdx-files)
-- [Generate slugs](#generate-slugs)
-- [Create pages](#create-pages-from-sourced-mdx-files)
-- [Make a template](#make-a-template-for-your-posts)
-
 ## Source MDX pages from the filesystem
 
 To let Gatsby know that you'll be working with MDX content you need to

docs/docs/recipes.md

@@ -30,18 +30,6 @@ See [docs templates](/docs/docs-templates/) in the contributing docs for more he
 
 Craving a happy medium between [full-length tutorials](/tutorial/) and crawling the [docs](/docs/)? Here's a cookbook of guiding recipes on how to build things, Gatsby style.
 
-## Table of Contents
-
-1. [Pages and Layouts](#1-pages-and-layouts)
-2. [Styling with CSS](#2-styling-with-css)
-3. [Working with starters](#3-working-with-starters)
-4. [Working with themes](#4-working-with-themes)
-5. [Sourcing data](#5-sourcing-data)
-6. [Querying data](#6-querying-data)
-7. [Working with images](#7-working-with-images)
-8. [Transforming data](#8-transforming-data)
-9. [Deploying your site](#9-deploying-your-site)
-
 ## 1. Pages and Layouts
 
 ### Project structure

docs/docs/theme-api.md

@@ -2,13 +2,6 @@
 title: Themes API Reference
 ---
 
-## Table of contents
-
-- [Core Gatsby APIs](#core-gatsby-apis)
-- [Configuration](#configuration)
-- [Theme composition](#theme-composition)
-- [Shadowing](#shadowing)
-
 ## Core Gatsby APIs
 
 Themes are packaged Gatsby sites shipped as plugins, so you have access to all of Gatsby's APIs for modifying default configuration settings and functionality.

docs/docs/themes/conventions.md

@@ -4,15 +4,6 @@ title: Themes Conventions
 
 As we begin to formalize and standardize the methodologies for building Gatsby Themes, we're documenting them all here. These aren't intended to be the only way to solve things, but are recommended approaches. If you have other ideas and best practices please open up a PR to update this page.
 
-## Table of Contents
-
-- [Naming](#naming)
-- [Initializing required directories](#initializing-required-directories)
-- [Separating queries and presentational components](#separating-queries-and-presentational-components)
-  - [Page queries](#page-queries)
-  - [Static queries](#static-queries)
-- [Site metadata](#site-metadata)
-
 ## Naming
 
 It's recommended to prefix themes with `gatsby-theme-`. So if you'd like to name your theme "awesome" you

docs/tutorial/ecommerce-tutorial/index.md

@@ -2,39 +2,24 @@
 title: "Gatsby E-Commerce Tutorial"
 ---
 
-# Table of Contents
-
-- [Table of Contents](#table-of-contents)
-- [Why use Gatsby for an e-commerce site?](#why-use-gatsby-for-an-e-commerce-site)
-- [Prerequisites](#prerequisites)
-  - [How does Gatsby work with Stripe?](#how-does-gatsby-work-with-stripe)
-- [Setting up a Gatsby site](#setting-up-a-gatsby-site)
-- [Installing the StripeJS plugin](#installing-the-stripejs-plugin)
-  - [See your site hot reload in the browser!](#see-your-site-hot-reload-in-the-browser)
-  - [How does the StripeJS plugin work?](#how-does-the-stripejs-plugin-work)
-  - [Getting your Stripe test keys](#getting-your-stripe-test-keys)
-- [Examples](#examples)
-  - [Easy: One Button](#easy-one-button)
-  - [Advanced: Import SKUs via source plugin](#advanced-import-skus-via-source-plugin)
-  - [Custom: Fully custom checkout flow (requires backend component)](#custom-fully-custom-checkout-flow-requires-backend-component)
-- [Testing Payments](#testing-payments)
-
-# Why use Gatsby for an e-commerce site?
-
-In this advanced tutorial, you’ll learn how to use Gatsby to build the UI for a basic e-commerce site that can accept payments, with [Stripe](https://stripe.com) as the backend for processing payments. Benefits of using Gatsby for e-commerce sites include the following:
+In this advanced tutorial, you’ll learn how to use Gatsby to build the UI for a basic e-commerce site that can accept payments, with [Stripe](https://stripe.com) as the backend for processing payments.
+
+## Why use Gatsby for an e-commerce site?
+
+Benefits of using Gatsby for e-commerce sites include the following:
 
 - Security inherent in static sites
 - Blazing fast performance when your pages are converted from React into static files
 - Easy to host
 
 You can see the working demo hosted here: https://gatsby-ecommerce.netlify.com/
 
-# Prerequisites
+## Prerequisites
 
 - Since this is a more advanced tutorial, building a site with Gatsby before will likely make this tutorial less time-consuming ([see the main tutorial here](/tutorial/))
 - Stripe account: [register for an account here](https://dashboard.stripe.com/register)
 
-## How does Gatsby work with Stripe?
+### How does Gatsby work with Stripe?
 
 Stripe is a payment processing service that allows you to securely collect and process payment information from your customers. To try out Stripe for yourself, go to [Stripe’s Quick Start Guide](https://stripe.com/docs/payments/checkout#tryout).
 
@@ -44,7 +29,7 @@ Stripe offers a [hosted checkout](https://stripe.com/docs/payments/checkout) tha
 
 > **NOTE**: Stripe Checkout is currently in beta. You can sign up to receive updates on the [Stripe website](https://stripe.com/docs/payments/checkout). In the meantime, if you're looking to build more custom checkout flows, you might need to set up a simple function that your Gatsby project can POST to in order to handle the payment. See the ["custom example"](#custom-fully-custom-checkout-flow-requires-backend-component) section below for more details.
 
-# Setting up a Gatsby site
+## Setting up a Gatsby site
 
 Create a new Gatsby project by running the `gatsby new` command in the terminal and change directories into the new project you just started:
 
@@ -53,7 +38,7 @@ gatsby new ecommerce-gatsby-tutorial
 cd ecommerce-gatsby-tutorial
 ```
 
-# Installing the StripeJS plugin
+## Installing the StripeJS plugin
 
 You can extend the functionality of this default starter with plugins. One such plugin is `gatsby-plugin-stripe`, which you’ll install in this project:
 
@@ -72,13 +57,13 @@ module.exports = {
 }
 ```
 
-## See your site hot reload in the browser!
+### See your site hot reload in the browser!
 
 Run `npm run develop` in the terminal, which starts a development server and reloads changes you make to your site so you can preview them in the browser. Open up your browser to [localhost:8000](http://localhost:8000/) and you should see a default homepage.
 
 > **NOTE**: If you have already started your Gatsby development server using `npm run develop`, you will need to restart the server by pressing CTRL + C in the terminal where the command was run and running `npm run develop` again to see changes in your `gatsby-config.js` reflected on [localhost:8000](http://localhost:8000/)
 
-## How does the StripeJS plugin work?
+### How does the StripeJS plugin work?
 
 Stripe provides a JavaScript library the allows you to securely redirect your customer to the Stripe hosted checkout page. The Gatsby plugin, `gatsby-plugin-stripe`, will add this snippet:
 
@@ -90,7 +75,7 @@ to the end of the `<body>` tag across all of your pages. This helps facilitate S
 
 If you want to further customise the checkout process or pull Stripe data into your site, check out [Gatsby's plugin library for more Stripe plugins](https://www.gatsbyjs.org/plugins/?=stripe).
 
-## Getting your Stripe test keys
+### Getting your Stripe test keys
 
 View your API credentials by logging into your Stripe account, and then going to Developers > API Keys.
 
@@ -103,19 +88,19 @@ You have 2 keys in both test mode and production mode:
 
 While testing, you must use the key(s) that include _test_. For production code, you will need to use the live keys. As the names imply, your publishable key may be included in code that you share publicly (for example, on the frontend, and in GitHub), whereas your secret key should not be shared with anyone or committed to any public repo. It’s important to restrict access to this secret key because anyone who has it could potentially read or send requests from your Stripe account and see information about charges or purchases or even refund customers.
 
-# Examples
+## Examples
 
 You can find an implementation of these examples [on GitHub](https://github.com/thorsten-stripe/ecommerce-gatsby-tutorial).
 
-## Easy: One Button
+### Easy: One Button
 
 If you're selling a simple product, like an eBook for example, you can create a single button that will perform a redirect to the Stripe Checkout page:
 
-### Create a product and SKU
+#### Create a product and SKU
 
 For Stripe Checkout to work without any backend component, you need to create a product listing in the Stripe Dashboard. This is required for Stripe to validate that the request coming from the frontend is legitimate and to charge the right amount for the selected product/SKU. To set this up, simply follow the steps in the [Stripe docs](https://stripe.com/docs/payments/checkout#configure).
 
-### Create a checkout component that loads StripeJS and redirects to the checkout
+#### Create a checkout component that loads StripeJS and redirects to the checkout
 
 Create a new file at `src/components/checkout.js`. Your `checkout.js` file should look like this:
 
@@ -172,7 +157,7 @@ const Checkout = class extends React.Component {
 export default Checkout
 ```
 
-### What did you just do?
+#### What did you just do?
 
 You imported React, added a button with some styles, and introduced some React functions. The `componentDidMount()` and `redirectToCheckout()` functions are most important for the Stripe functionality. The `componentDidMount()` function is a React lifecycle method that launches when the component is first mounted to the DOM, making it a good place to initialise the Stripe.js client. It looks like this:
 
@@ -218,7 +203,7 @@ The `redirectToCheckout()` function validates your checkout request and either r
 
 The `render()` function applies our styles to the button and binds the `redirectToCheckout()` function to the button's onclick event.
 
-### Importing the checkout component into the homepage
+#### Importing the checkout component into the homepage
 
 Now go to your `src/pages/index.js` file. This is your homepage that shows at the root URL. Import your new checkout component in the file underneath the other imports and add your `<Checkout />` component within the `<Layout>` element. Your `index.js` file should now look like similar to this:
 
@@ -251,11 +236,11 @@ export default IndexPage
 
 If you go back to [localhost:8000](http://localhost:8000/) in your browser and you have `npm run develop` running, you should now see a big, enticing "BUY MY BOOK" button. C'mon and give it a click!
 
-## Advanced: Import SKUs via source plugin
+### Advanced: Import SKUs via source plugin
 
 Instead of hardcoding the SKU IDs, you can use the [gatsby-source-stripe plugin](https://www.gatsbyjs.org/packages/gatsby-source-stripe/) to retrieve your SKUs at build time.
 
-### Add the Stripe source plugin
+#### Add the Stripe source plugin
 
 Add the [gatsby-source-stripe plugin](https://www.gatsbyjs.org/packages/gatsby-source-stripe/) which you can use to pull in the SKUs from your Stripe account.
 
@@ -311,7 +296,7 @@ Lastly, make sure that your `.gitignore` file excludes all of your `.env.*` file
 .env.production
 ```
 
-### Create a component that lists your SKUs
+#### Create a component that lists your SKUs
 
 In your components folder add a new `Products` folder. This folder will include the components that interact with the Stripe SKUs. First, you need a component that queries and lists your SKUs:
 
@@ -374,7 +359,7 @@ export default AdvancedExamplePage
 
 When navigating to http://localhost:8000/advanced/ you should now see a list of paragraphs with your SKU names.
 
-### Create a component that presents a single SKU
+#### Create a component that presents a single SKU
 
 To make your SKUs more visually appealing and interactive, create a new `SkuCard` component in your `Products` folder:
 
@@ -512,14 +497,14 @@ class Skus extends Component {
 export default Skus
 ```
 
-### Adding a cart component
+#### Adding a cart component
 
 You can call `redirectToCheckout()` providing an array of SKUs and their quantities to charge for multiple items at the same time. Instead of each "BUY ME" button redirecting to the checkout page, you can therefore provide a central "GO TO CHECKOUT" button that uses the state of a cart component. You can see the necessary changes for this example [on GitHub](https://github.com/thorsten-stripe/ecommerce-gatsby-tutorial/tree/cart-example).
 
-## Custom: Fully custom checkout flow (requires backend component)
+### Custom: Fully custom checkout flow (requires backend component)
 
 Stripe Checkout is currently in beta. You can sign up to receive updates on the [Stripe website](https://stripe.com/docs/payments/checkout). In the meantime, if you're looking to build more custom checkout flows, you can set up a simple function that your Gatsby project can POST to in order to handle the payment. See the previous version of [this tutorial](https://github.com/gatsbyjs/gatsby/blob/6b3c08782d0898719b61181638b6a0967da49dd6/docs/tutorial/ecommerce-tutorial/index.md) for detailed steps.
 
-# Testing Payments
+## Testing Payments
 
 In test mode (when using the API key that includes _test_) Stripe provides [test cards](https://stripe.com/docs/testing#cards) for you to test different checkout scenarios.

docs/tutorial/index.md

@@ -1,5 +1,6 @@
 ---
 title: Gatsby.js Tutorials
+disableTableOfContents: true
 ---
 
 Welcome to Gatsby! We’re glad you’re here. The goal of this tutorial is to guide you through setting up and deploying your first Gatsby site using a starter template. As we walk through that process, we’ll introduce some more general web development topics, and go over the underlying structure of a Gatsby site.

docs/tutorial/part-eight/index.md

@@ -1,6 +1,7 @@
 ---
 title: Preparing a site to go live
 typora-copy-images-to: ./
+disableTableOfContents: true
 ---
 
 Wow! You've come a long way! You've learned how to:

docs/tutorial/part-five/index.md

@@ -1,6 +1,7 @@
 ---
 title: Source plugins
 typora-copy-images-to: ./
+disableTableOfContents: true
 ---
 
 > This tutorial is part of a series about Gatsby’s data layer. Make sure you’ve gone through [part 4](/tutorial/part-four/) before continuing here.

docs/tutorial/part-four/index.md

@@ -1,6 +1,7 @@
 ---
 title: Data in Gatsby
 typora-copy-images-to: ./
+disableTableOfContents: true
 ---
 
 Welcome to Part Four of the tutorial! Halfway through! Hope things are starting

docs/tutorial/part-one/index.md

@@ -1,6 +1,7 @@
 ---
 title: Get to know Gatsby building blocks
 typora-copy-images-to: ./
+disableTableOfContents: true
 ---
 
 In the [**previous section**](/tutorial/part-zero/), you prepared your local development environment by installing the necessary software and creating your first Gatsby site using the [**“hello world” starter**](https://github.com/gatsbyjs/gatsby-starter-hello-world). Now, take a deeper dive into the code generated by that starter.

docs/tutorial/part-seven/index.md

@@ -1,6 +1,7 @@
 ---
 title: Programmatically create pages from data
 typora-copy-images-to: ./
+disableTableOfContents: true
 ---
 
 > This tutorial is part of a series about Gatsby’s data layer. Make sure you’ve gone through [part 4](/tutorial/part-four/), [part 5](/tutorial/part-five/), and [part 6](/tutorial/part-six/) before continuing here.

docs/tutorial/part-six/index.md

@@ -1,6 +1,7 @@
 ---
 title: Transformer plugins
 typora-copy-images-to: ./
+disableTableOfContents: true
 ---
 
 > This tutorial is part of a series about Gatsby’s data layer. Make sure you’ve gone through [part 4](/tutorial/part-four/) and [part 5](/tutorial/part-five/) before continuing here.