[WNMGDS-3243] Upgraded Gatsby to v5 #3477

kim-cmsds · 2025-03-17T18:55:37Z

Summary

Jira Tickets (WNMGDS-3243 and WNMGDS-3285)
Upgraded the Docs Site to Gatsby version 5 and the related plugin dependencies to their latest versions
Gatsby config files are now written in ESM to support github-flavored markdown via remark-gfm now that gatsby-plugin-mdx no longer has support for that type of markdown baked in.
Various changes to mdx to account for mdx.js's adding an additional <p> tag around new lines with something called interleaving

How to test

Pull down the branch and run npm install
Run npm run start
Compare the docs site to the one deployed to production

Checklist

Prefixed the PR title with the Jira ticket number as [WNMGDS-####] Title or [NO-TICKET] if this is unticketed work.
Selected appropriate Type (only one) label for this PR, if it is a breaking change, label should only be Type: Breaking
Selected appropriate Impacts, multiple can be selected.
Selected appropriate release milestone

…tsby

build tools

…omponent

https://mdxjs.com/docs/what-is-mdx/#interleaving

…tsby

kim-cmsds · 2025-03-17T18:57:33Z

packages/docs/content/blog/release-7.0.mdx

The next set of markdown file changes have to do with preventing Interleaving

kim-cmsds · 2025-03-17T19:00:17Z

packages/docs/content/foundation/system-color-tokens.mdx

@@ -4,10 +4,29 @@ order: 70
 intro: System color tokens are the entire set of color tokens from which our themes are built.
 ---

-import ColorContrastGuidelines from '../../src/reusable-text-snippets/ColorContrastGuidelines.mdx';


I wasn't able to recreate this functionality in Gatsby v5, so instead of using the reusable text snippet, I've gone ahead and copied and pasted the contents into this markdown file, plus the other three locations where the content was changed. Another option would be to create a react component and import it accordingly.

I think the React component approach makes the most sense. Do you agree?

If so, we can spin up a ticket for that work.

@jack-ryan-nava-pbc agreed! New ticket -> https://jira.cms.gov/browse/WNMGDS-3287

kim-cmsds · 2025-03-17T19:01:06Z

packages/docs/content/patterns/utility-actions.mdx

-        <PrintIcon ariaHidden={false} className="ds-u-margin-right--1" />
-        Print
-      </Button>
+      <Button variation="ghost" size="small"><PrintIcon ariaHidden={false} className="ds-u-margin-right--1" />Print</Button>


These changes prevent interleaving, which affects the generated output and visual display

Oh, (I think) it's possible that someone could have auto formatting enabled in their IDE that wraps content to new lines on save or something. We should spin up a new confluence page documenting the nuts and bolts of the Doc Site so we can refer to why we need these things on one line and other miscellany.

@jack-ryan-nava-pbc that's a good call! The latest commit (de66bb7) runs the repository's prettier settings against the markdown file changes

packages/docs/content/utilities/float.mdx

kim-cmsds · 2025-03-17T19:09:19Z

packages/docs/gatsby-node.mjs

+export const onCreateNode = ({ node, getNode, actions }) => {
+  const { createNodeField } = actions;
+  if (node.internal.type === `Mdx`) {
+    const slug = createFilePath({ node, getNode, basePath: `pages`, trailingSlash: false });


We no longer get slug creation for free and need to apply it to each note

kim-cmsds · 2025-03-17T19:09:54Z

packages/docs/gatsby-node.mjs

+              title
+            }
+            fields {
+              slug


slug is no longer "top-level"

kim-cmsds · 2025-03-17T19:10:39Z

packages/docs/src/components/content/ContentRenderer.tsx

@@ -55,7 +54,10 @@ const CodeWithSyntaxHighlighting = ({
 // for preformatted text that has code as it's child, set language class on <pre> too
 // this allows scrolling in code block on small screens
 const PreformattedWithLanguageClass = (props: any) => {
-  if (props.children?.props?.mdxType === 'code' && props.children?.props?.className) {
+  if (
+    props.children?.type?.name === 'CodeWithSyntaxHighlighting' &&


this type changed and ensures styling for code blocks is unchanged

kim-cmsds · 2025-03-17T19:11:16Z

packages/docs/src/components/content/ContentRenderer.tsx

@@ -1,7 +1,6 @@
 import Prism from 'prismjs';
 import { ThirdPartyExternalLink } from '@cmsgov/design-system';

-import { MDXRenderer } from 'gatsby-plugin-mdx';


MDXRenderer is no longer available as part of gatsby-plugin-mdx at version 2 and higher

kim-cmsds · 2025-03-17T19:13:26Z

packages/docs/gatsby-node.mjs

+
+    createPage({
+      path: originalPage.path,
+      component: `${originalPage.component}?${contentFilePath}`,


This component argument ensures that the template .tsx file is "linked" to the content that is defined by contentFilePath. The "gatsby-plugin-mdx" plugin will then convert the markdown to HTML/CSS/JS that can be accessed with the children prop within the template component.

tamara-corbalt · 2025-03-18T14:00:51Z

packages/docs/gatsby-node.mjs

+      },
+    } = edge;
+    // Path for this page -- the slug with positioning markers removed
+    const path = edge.node.fields.slug.replace(/\d+_/g, '');


Is there ever a chance a slug might be missing, and should we check for it before processing? My assumption is no, since we create slugs for each Mdx node in onCreateNode, which presumably runs before this. Just checking my understanding of how these steps fit together.

@tamara-corbalt good question!

It's possible to explore the created nodes using the GraphiQL endpoint (http://localhost:8000/___graphql) when running npm run start and verify that the slugs and titles exist using this query.

All the slugs were created as intended as part of the earlier step onCreateNode (docs api reference)!

jack-ryan-nava-pbc · 2025-03-19T01:29:38Z

packages/docs/content/components/card.mdx

@@ -12,8 +12,9 @@ import { Alert } from '@cmsgov/design-system';
 <ThemeContent neverThemes={['medicare']}>
  <Alert variation="error">
    <p class="ds-c-alert__text">
-      This component is only used for Medicare. Please use the theme switcher to view the component
-      with Medicare styles.
+      {


Ok, so the brackets prevent a second <p> tag from being interleaved within the other <p> tag?

Yes, that's correct

jack-ryan-nava-pbc · 2025-03-19T01:31:16Z

packages/docs/content/foundation/layout-grid/layout-grid.mdx

@@ -180,19 +180,19 @@ Align columns horizontally or vertically using [flexbox utility classes](/utilit
    </div>
    <div
      class="ds-l-row ds-u-align-items--start ds-u-border--1 ds-u-padding--1 ds-u-margin-y--2"
-      style="height: 100px"
+      style={{ height: 100 }}


The lack of units here makes me nervous. PX is the default?

Yes, PX is the default

jack-ryan-nava-pbc · 2025-03-19T01:34:54Z

packages/docs/content/utilities/display.mdx

-      {' '}
-      .ds-u-display--inline-flex{' '}
-    </code>
+    <code class="ds-u-display--block ds-u-padding--1 ds-u-margin-bottom--2 utility-example"> .ds-u-display--block </code>


This is so much better than the interpolated spaces. Thank you!

jack-ryan-nava-pbc · 2025-03-19T01:40:40Z

packages/docs/src/components/layout/TableOfContents.tsx

@@ -72,7 +72,7 @@ export const TableOfContentsFeedback = ({ slug }: TableOfContentsFeedbackProps)
        <li>
          <a
            onClick={linkAnalytics}
-            href={`https://github.com/CMSgov/design-system/edit/main/packages/docs/content/${slug}.mdx`}
+            href={`https://github.com/CMSgov/design-system/edit/main/packages/docs/content${slug}.mdx`}


Is the / in the slug itself or is content not a folder anymore?

the / is in the slug now

jack-ryan-nava-pbc · 2025-03-19T01:41:43Z

packages/docs/src/pages/404.tsx

-      sendViewEvent(analyticsPayload);
-    }
-  }, []);
+import useSendViewEvent from '../helpers/useSendViewEvent';


Nice! Thank you for extracting this.

jack-ryan-nava-pbc · 2025-03-19T01:42:52Z

packages/docs/gatsby-node.mjs

@@ -0,0 +1,182 @@
+import express from 'express';


I'd love (another) walkthrough of these changes!

jack-ryan-nava-pbc

I think I need a walkthrough of the gatsby-node file changes, but pretty much everything else looks a-ok!

jack-ryan-nava-pbc

Walked through changes in call on 3/19/2025 Looks good!

kim-cmsds added 15 commits March 4, 2025 09:49

upgrades packages for gatsby v5

4875374

package updates

67b05f5

Merge branch 'jryan/react-18-upgrade' into kcn/WNMGDS-3243/upgrade-ga…

de3a7eb

…tsby

[for now] removes repeatable content import from markdown files

80c41a3

updates eslint

330f082

Updates graphql query based on warning from gatsby

b8c1fb2

build tools

creates new helper for sending view event

44f3dcd

upgrades to latest mdx plugin; updates queries and content renderer c…

2fe241a

…omponent

updates packages used in docs site

4497939

Use ES Modules format for gatsby config files

579062c

updates MdxQuery types

3925769

fixes missing slug

7027b83

fixes code and pre formatting

229d2ed

updates markdown files (WNMGDS-3285)

c639fed

https://mdxjs.com/docs/what-is-mdx/#interleaving

Merge branch 'jryan/react-18-upgrade' into kcn/WNMGDS-3243/upgrade-ga…

0814bcd

…tsby

kim-cmsds added Type: Internal This item relates to internal tooling/maintenance Impacts: Documentation Indicates that this item relates to documentation labels Mar 17, 2025

kim-cmsds added this to the 12.2.0 milestone Mar 17, 2025

kim-cmsds commented Mar 17, 2025

View reviewed changes

tamara-corbalt reviewed Mar 18, 2025

View reviewed changes

jack-ryan-nava-pbc reviewed Mar 19, 2025

View reviewed changes

kim-cmsds added 2 commits March 19, 2025 10:16

prettier and interleaving inconsistencies

de66bb7

fixes missing slug info

adabb3f

jack-ryan-nava-pbc approved these changes Mar 19, 2025

View reviewed changes

tamara-corbalt approved these changes Mar 19, 2025

View reviewed changes

kim-cmsds merged commit 1001cfb into jryan/react-18-upgrade Mar 19, 2025
1 check failed

kim-cmsds deleted the kcn/WNMGDS-3243/upgrade-gatsby branch March 19, 2025 19:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WNMGDS-3243] Upgraded Gatsby to v5 #3477

[WNMGDS-3243] Upgraded Gatsby to v5 #3477

kim-cmsds commented Mar 17, 2025

kim-cmsds Mar 17, 2025

kim-cmsds Mar 17, 2025

jack-ryan-nava-pbc Mar 18, 2025

kim-cmsds Mar 18, 2025

kim-cmsds Mar 17, 2025

jack-ryan-nava-pbc Mar 19, 2025

kim-cmsds Mar 19, 2025

kim-cmsds Mar 17, 2025

kim-cmsds Mar 17, 2025

kim-cmsds Mar 17, 2025

kim-cmsds Mar 17, 2025

kim-cmsds Mar 17, 2025

tamara-corbalt Mar 18, 2025

kim-cmsds Mar 19, 2025

kim-cmsds Mar 19, 2025

jack-ryan-nava-pbc Mar 19, 2025 •

edited

Loading

kim-cmsds Mar 19, 2025

jack-ryan-nava-pbc Mar 19, 2025

kim-cmsds Mar 19, 2025

jack-ryan-nava-pbc Mar 19, 2025

jack-ryan-nava-pbc Mar 19, 2025

kim-cmsds Mar 19, 2025

jack-ryan-nava-pbc Mar 19, 2025

jack-ryan-nava-pbc Mar 19, 2025

jack-ryan-nava-pbc left a comment

jack-ryan-nava-pbc left a comment

[WNMGDS-3243] Upgraded Gatsby to v5 #3477

[WNMGDS-3243] Upgraded Gatsby to v5 #3477

Conversation

kim-cmsds commented Mar 17, 2025

Summary

How to test

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jack-ryan-nava-pbc Mar 19, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jack-ryan-nava-pbc left a comment

Choose a reason for hiding this comment

jack-ryan-nava-pbc left a comment

Choose a reason for hiding this comment

jack-ryan-nava-pbc Mar 19, 2025 •

edited

Loading