feat(www): add ability to limit table of contents depth (#16818)

Author: gillkyle

docs/docs/recipes.md

@@ -1,5 +1,6 @@
 ---
 title: Recipes
+tableOfContentsDepth: 2
 ---
 
 <!-- Basic template for a Gatsby recipe:

www/src/components/docs-table-of-contents.js

@@ -9,7 +9,18 @@ import {
   transition,
 } from "../utils/presets"
 
-function createItems(items, location) {
+function isUnderDepthLimit(depth, maxDepth) {
+  if (maxDepth === null) {
+    // if no maxDepth is passed in, continue to render more items
+    return true
+  } else {
+    return depth < maxDepth
+  }
+}
+
+// depth and maxDepth are used to figure out how many bullets deep to render in the ToC sidebar, if no
+// max depth is set via the tableOfContentsDepth field in the frontmatter, all headings will be rendered
+function createItems(items, location, depth, maxDepth) {
   return (
     items &&
     items.map(item => (
@@ -49,13 +60,13 @@ function createItems(items, location) {
         >
           {item.title}
         </Link>
-        {item.items && (
+        {item.items && isUnderDepthLimit(depth, maxDepth) && (
           <ul
             css={{
               marginLeft: space[6],
             }}
           >
-            {createItems(item.items, location)}
+            {createItems(item.items, location, depth + 1, maxDepth)}
           </ul>
         )}
       </li>
@@ -85,7 +96,12 @@ function TableOfContents({ page, location }) {
           },
         }}
       >
-        {createItems(page.tableOfContents.items, location)}
+        {createItems(
+          page.tableOfContents.items,
+          location,
+          1,
+          page.frontmatter.tableOfContentsDepth
+        )}
       </ul>
     </nav>
   ) : null

www/src/templates/template-docs-markdown.js

@@ -170,6 +170,7 @@ export const pageQuery = graphql`
         overview
         issue
         disableTableOfContents
+        tableOfContentsDepth
       }
       ...MarkdownPageFooterMdx
     }