feat: Add support for next_steps in front matter in PageGrid (#9434)

* fix: don't show next steps if node has no children

* feat: add support for `next_steps` array in mdx frontmatter

* update pageGrid component docs

* fix: remove useless PageGrid laravel/other-versions

* improve pageGrid docs

* fix: make TS happy

* rename isTruthy util to isNotNil

Author: a-hariti

docs/contributing/pages/components.mdx

@@ -195,16 +195,28 @@ See also the [Alert component](#alert).
 
 ## PageGrid
 
-Render all child pages of this document, including their `description` if available.
+Render all `next_steps` of this document or default child pages, including their `description` if available.
+
+You can specify `next_steps` in the frontmatter of a page to include them in the grid. It supports relative paths and will automatically resolve them.
 
 ```markdown {tabTitle:Example}
+---
+# in the frontmatter of a page:
+next_steps:
+  - ./child-one
+  - ./child-two
+  - ../parent/child-three
+---
+
 <PageGrid />
 ```
 
 Attributes:
 
 - `header` (string) - optional header value to include, rendered as an H2
+
 - `nextPages` (boolean) - only render pages which come next based on sidebar ordering
+
 - `exclude` (string[]) - an array of pages to exclude from the grid. Specify the file name of the page, for example, `"index"` for `index.mdx`.
 
 ## PlatformContent

docs/platforms/php/guides/laravel/other-versions/laravel4.mdx

@@ -63,5 +63,3 @@ If you wish to wire up Sentry anywhere outside of the standard error handlers, o
 ```php
 $app['sentry']->setRelease(Git::sha());
 ```
-
-<PageGrid nextPages header="Next Steps" />

docs/platforms/php/guides/laravel/other-versions/laravel5.mdx

@@ -99,5 +99,3 @@ You most likely don't want errors to be sent to Sentry when you are developing o
 You can also do this by not defining `SENTRY_LARAVEL_DSN` in your `.env` or by defining it as `SENTRY_LARAVEL_DSN=null`.
 
 If you do leave Sentry enabled when developing or running tests, it's possible for it to have a negative effect on the performance of your application or test suite.
-
-<PageGrid nextPages header="Next Steps" />

docs/platforms/php/guides/laravel/other-versions/laravel6-7.mdx

@@ -93,5 +93,3 @@ You most likely don't want errors to be sent to Sentry when you are developing o
 You can also do this by not defining `SENTRY_LARAVEL_DSN` in your `.env` or by defining it as `SENTRY_LARAVEL_DSN=null`.
 
 If you do leave Sentry enabled when developing or running tests, it's possible for it to have a negative effect on the performance of your application or test suite.
-
-<PageGrid nextPages header="Next Steps" />

docs/platforms/php/guides/laravel/other-versions/lumen.mdx

@@ -87,5 +87,3 @@ You most likely don't want errors to be sent to Sentry when you are developing o
 You can also do this by not defining `SENTRY_LARAVEL_DSN` in your `.env` or by defining it as `SENTRY_LARAVEL_DSN=null`.
 
 If you do leave Sentry enabled when developing or running tests, it's possible for it to have a negative effect on the performance of your application or test suite.
-
-<PageGrid nextPages header="Next Steps" />

src/components/docPage/index.tsx

@@ -4,7 +4,7 @@ import {getCurrentGuide, getCurrentPlatform, nodeForPath} from 'sentry-docs/docT
 import {serverContext} from 'sentry-docs/serverContext';
 import {FrontMatter} from 'sentry-docs/types';
 import {PaginationNavNode} from 'sentry-docs/types/paginationNavNode';
-import {isTruthy} from 'sentry-docs/utils';
+import {isNotNil} from 'sentry-docs/utils';
 import {getUnversionedPath} from 'sentry-docs/versioning';
 
 import './type.scss';
@@ -50,7 +50,7 @@ export function DocPage({
 
   const pathname = serverContext().path.join('/');
 
-  const searchPlatforms = [currentPlatform?.name, currentGuide?.name].filter(isTruthy);
+  const searchPlatforms = [currentPlatform?.name, currentGuide?.name].filter(isNotNil);
 
   const unversionedPath = getUnversionedPath(path, false);
 

src/components/pageGrid.tsx

@@ -1,33 +1,36 @@
+import path from 'path';
+
 import Link from 'next/link';
 
-import {nodeForPath} from 'sentry-docs/docTree';
+import {DocNode, nodeForPath} from 'sentry-docs/docTree';
 import {serverContext} from 'sentry-docs/serverContext';
-import {sortPages} from 'sentry-docs/utils';
+import {isNotNil, sortPages} from 'sentry-docs/utils';
 
 type Props = {
-  nextPages: boolean;
-  /**
-   * A list of pages to exclude from the grid.
-   * Specify the file name of the page, for example, "index" for "index.mdx"
-   */
   exclude?: string[];
   header?: string;
 };
 
 export function PageGrid({header, exclude}: Props) {
-  const {rootNode, path} = serverContext();
+  const {rootNode, path: nodePath} = serverContext();
 
-  const parentNode = nodeForPath(rootNode, path);
-  if (!parentNode) {
+  const parentNode = nodeForPath(rootNode, nodePath);
+  if (!parentNode || parentNode.children.length === 0) {
     return null;
   }
 
+  const children: DocNode[] = parentNode.frontmatter.next_steps?.length
+    ? (parentNode.frontmatter.next_steps
+        .map(p => nodeForPath(rootNode, path.join(parentNode.path, p)))
+        .filter(isNotNil) ?? [])
+    : parentNode.children;
+
   return (
     <nav>
       {header && <h2>{header}</h2>}
       <ul>
         {sortPages(
-          parentNode.children.filter(
+          children.filter(
             c =>
               !c.frontmatter.sidebar_hidden &&
               c.frontmatter.title &&

src/components/tableOfContents/index.tsx

@@ -2,7 +2,7 @@
 
 import {useEffect, useState} from 'react';
 
-import {isTruthy} from 'sentry-docs/utils';
+import {isNotNil} from 'sentry-docs/utils';
 
 import styles from './style.module.scss';
 
@@ -104,7 +104,7 @@ export function TableOfContents() {
           isActive: false,
         };
       })
-      .filter(isTruthy);
+      .filter(isNotNil);
     setTocItems(tocItems_);
   }, []);
 

src/mdx.ts

@@ -28,7 +28,7 @@ import remarkImageSize from './remark-image-size';
 import remarkTocHeadings, {TocNode} from './remark-toc-headings';
 import remarkVariables from './remark-variables';
 import {FrontMatter, Platform, PlatformConfig} from './types';
-import {isTruthy} from './utils';
+import {isNotNil} from './utils';
 import {isVersioned, VERSION_INDICATOR} from './versioning';
 
 const root = process.cwd();
@@ -145,7 +145,7 @@ export function getDevDocsFrontMatter(): FrontMatter[] {
         sourcePath: path.join(folder, fileName),
       };
     })
-    .filter(isTruthy);
+    .filter(isNotNil);
   return fmts;
 }
 

src/types/frontmatter.ts

@@ -32,10 +32,16 @@ export interface FrontMatter {
    * The next page in the bottom pagination navigation.
    */
   nextPage?: PaginationNavNode;
+  /**
+   * relative links to use in the "next steps" section of the page grid
+   * takes precendence over children when present
+   */
+  next_steps?: string[];
   /**
    * Set this to true to disable indexing (robots, algolia) of this content.
    */
   noindex?: boolean;
+
   /**
    * Specific guides that this page is not relevant to.
    */