[CMSDS-3954] Add hosted Markdown equivalents for documentation pages by tamara-corbalt · Pull Request #3985 · CMSgov/design-system

tamara-corbalt · 2026-03-25T19:54:26Z

Summary

Adds hosted Markdown equivalents for each documentation page.
Converts .mdx content into pure Markdown output during build.

Jira ticket

How to test

Run docs tests

npm run test:unit:docs

Generate Hosted Markdown

cd packages/docs
npm run build
Inspect the public directory:
- Each page directory should now include a llms.txt file alongside index.html.
Run npm run start (from within packages/docs):
- Note: running npm run start from the repo root will run gatsby clean && gatsby develop, which clears the public directory and removes generated files.
Visit a page and its Markdown equivalent:
- Example:
  - HTML: http://localhost:8000/components/accordion/?theme=core
  - Markdown: http://localhost:8000/components/accordion/llms.txt

Checklist

Prefixed the PR title with the Jira ticket number as [CMSDS-####] 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

jack-ryan-nava-pbc

Mostly minor stuff. I would like to see some specs added, and I'm not sure if we need error handling in place given that most of these functions are find and replace operations, but maybe worth thinking about...

derek-cmsds

I left some questions about some of the Markdown generation. I have one other more general question though: Is there anything in the root LLMs.txt that references these other Markdown files? How do we prompt the chatbot to visit these other paths?

tamara-corbalt · 2026-03-26T16:15:08Z

I left some questions about some of the Markdown generation. I have one other more general question though: Is there anything in the root LLMs.txt that references these other Markdown files? How do we prompt the chatbot to visit these other paths?

Yes, good question. The change is a bit buried in this PR, but I updated the listed Urls in the root llms.txt to point to these hosted Markdown files instead of their HTML equivalents like so:

## Components

- [Accordion](https://design.cms.gov/components/accordion/llms.txt): An accordion is a list of headers that hide or reveal additional content when selected.
- [Alert](https://design.cms.gov/components/alert/llms.txt): Alerts give feedback to users, provide critical information, and/or offer key supplementary details about a task.

…eContentToAnnoations, fix casing logic and retain child text

- removeImportStatements, - stripMarkdownSections, - normalizeThemeContent, - normalizeMarkdownOutput - Adds logic to preserve code snippets

…rocessMdxForHostedMarkdown

tamara-corbalt · 2026-03-30T17:50:48Z

+
+  // Run this first on the whole document, since ThemeContent
+  // may wrap across fenced code blocks.
+  result = normalizeThemeContent(result);


With the new code-snippet-aware processing (above in processMdxOutsideCodeFences), the MDX body is split into fenced and non-fenced chunks so cleanup transforms only run on the non-fenced chunks.

Because ThemeContent can wrap both text and fenced code blocks, it must be normalized before this split. Otherwise the opening and closing tags would end up in separate chunks.

tamara-corbalt · 2026-03-30T17:58:17Z

+    .join('\n\n');
+};
+
+export function processMdxOutsideCodeFences(input, transform) {


We want to preserve non-interactive code snippets in the hosted markdown output. Otherwise, large portions of code-heavy pages like for-developers become almost meaningless.

The limitation here is that we don't yet have a reliable way to preserve interactive code examples such as <ThemeCodeBlock/>, whose rendered output changes based on the theme switcher, like this one.

derek-cmsds

No blockers, but I do have some questions about comments and the new doc site tests you added. Well done.

derek-cmsds · 2026-03-31T15:45:34Z

I love all of this.

derek-cmsds · 2026-03-31T17:47:18Z

+    // Unwraps simple components (e.g., Alerts, Badges) but keeps their text 
+    chunk = unwrapSimpleComponents(chunk);
+    // Final cleanup: removes any remaining JSX.


I'm glad these comments are here. Would it make sense to document the functions in mdxToMArkdown.mjs with JSDoc comments so that devs can mouse-over them for more details?

derek-cmsds · 2026-03-31T17:49:13Z

I appreciate these tests.

derek-cmsds · 2026-03-31T17:52:20Z

    "test:unit:coverage:wc": "npm run test:unit:wc -- --collectCoverage --coverageReporters='json-summary'",
    "test:unit:coverage:all": "npm run test:unit:coverage:react && npm run test:unit:coverage:wc && tsx ./tests/unit/combineTestCoverage.ts",
    "test:unit": "jest --config=tests/unit/jest.config.js",
+    "test:unit:docs": "npm --prefix ./packages/docs run test",


Should the docs tests be run when running a broader test command like npm run test or npm run test:unit? Are we adding these tests to our CI pipeline?

Yep, I think that's a good idea to fold the new tests into the npm run test:unit script

I may need to back out folding the docs tests into npm run test:unit and move that to a follow-up ticket. I forgot there are some downstream side effects: test:unit:coverage calls test:unit, and combineTestCoverage.ts expects a dedicated coverage artifact that no longer appears to be generated in CI.

Added this follow up ticket: https://jira.cms.gov/browse/CMSDS-3973

jack-ryan-nava-pbc

A few questions and observations, but over all this looks awesome! Well done and thank you!

jack-ryan-nava-pbc · 2026-03-31T16:40:28Z

+
+  result = processMdxOutsideCodeFences(result, (input) => {
+    let chunk = input;
+    // ⚠️ NOTE: Order matters — do not rearrange these steps.


Very helpful comment!

jack-ryan-nava-pbc · 2026-03-31T16:47:09Z


 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const require = createRequire(import.meta.url)
+const normalizePagePath = (slug) => slug.replace(/\d+_/g, '');


This function is actually duplicative of removePositioning, which is in the packages/docs/src/helpers/casingUtils.ts file. You should probably import and use that function instead of duplicating.

Agree this is duplicative but Node doesn’t love that removePositioning is being imported from a .ts file inside gatsby-node.mjs.

Does it throw an error or a type warning? I can live with a type warning (or even silence it).

No this looks like a hard runtime failure; the build fails because node can't resolve the .ts file extension

Alrighty, let's duplicate the function for now. Thanks for checking! Can you add a brief TODO comment pointing to the other function?

…3985) * Write md files into public folder * Add logic to strip out interative content and import lines. * Readability adjustment * Move buildMarkdownPage utility into llms-txt scripts * Refactor for readability * Small refinements to gatsby-node.mjs * Strip out Code, Examples & Maturity content sections. For convertTHemeContentToAnnoations, fix casing logic and retain child text * Rename function handling the ThemeContent logic * Fixes regex for stripMarkdoSections * Revert change to accordion.mdx * Add warning about order of operations * - Adds tests for: - removeImportStatements, - stripMarkdownSections, - normalizeThemeContent, - normalizeMarkdownOutput - Adds logic to preserve code snippets * Adds tests for unwrapSimpleComponents, normalizeMarkdownOutput, and processMdxForHostedMarkdown * Move all fixtures into dedicated fixture file * Standardize fixture variable names * Adds commands to run unit tests in docs package * Ensure html and css blocks are preserved as well * Remove extra semicolon * Adds jsdocs for mdxToMarkdown utilities * Fold docs tests into broader test command * Revert wrapping docs tests into broader test command * Adds todo

tamara-corbalt added 6 commits March 25, 2026 09:58

Write md files into public folder

b2e09c0

Add logic to strip out interative content and import lines.

1cee1a1

Readability adjustment

a5f53a3

Move buildMarkdownPage utility into llms-txt scripts

4640796

Refactor for readability

e96e8ca

Small refinements to gatsby-node.mjs

e2191c1

tamara-corbalt changed the title ~~[CMSDS-3954] Add hosted Markdown only pages~~ [CMSDS-3954] Add hosted Markdown equivalents for documentation pages Mar 25, 2026

tamara-corbalt marked this pull request as ready for review March 25, 2026 21:03

tamara-corbalt requested review from derek-cmsds and jack-ryan-nava-pbc March 25, 2026 21:03

tamara-corbalt self-assigned this Mar 25, 2026

tamara-corbalt added Impacts: Documentation Indicates that this item relates to documentation Type: Added Indicates a new feature. labels Mar 25, 2026

tamara-corbalt added this to the 🟢 Docsite Deployment (1.5 / 2.1) — Open for Changes milestone Mar 25, 2026

jack-ryan-nava-pbc reviewed Mar 26, 2026

View reviewed changes

derek-cmsds reviewed Mar 26, 2026

View reviewed changes

tamara-corbalt added 11 commits March 26, 2026 15:27

Strip out Code, Examples & Maturity content sections. For convertTHem…

e7f96ff

…eContentToAnnoations, fix casing logic and retain child text

Rename function handling the ThemeContent logic

c9de620

Fixes regex for stripMarkdoSections

e90d45a

Revert change to accordion.mdx

3afe94f

Add warning about order of operations

7f7568f

- Adds tests for:

86ba845

- removeImportStatements, - stripMarkdownSections, - normalizeThemeContent, - normalizeMarkdownOutput - Adds logic to preserve code snippets

Adds tests for unwrapSimpleComponents, normalizeMarkdownOutput, and p…

54cb05a

…rocessMdxForHostedMarkdown

Move all fixtures into dedicated fixture file

48a98e3

Standardize fixture variable names

58fae49

Adds commands to run unit tests in docs package

d8a5220

Ensure html and css blocks are preserved as well

ffb7ca7

tamara-corbalt commented Mar 30, 2026

View reviewed changes

tamara-corbalt requested review from derek-cmsds and jack-ryan-nava-pbc March 30, 2026 18:21

derek-cmsds approved these changes Mar 31, 2026

View reviewed changes

jack-ryan-nava-pbc approved these changes Mar 31, 2026

View reviewed changes

tamara-corbalt added 6 commits March 31, 2026 14:31

Remove extra semicolon

86e128d

Adds jsdocs for mdxToMarkdown utilities

8d99615

Fold docs tests into broader test command

dd00d50

Revert wrapping docs tests into broader test command

09658cd

Adds todo

92026e9

Merge branch 'main' into tdement/CMSDS-3954/add-markdown-only-pages

c206618

tamara-corbalt modified the milestones: 🟢 Docsite Deployment (1.5 / 2.1) — Open for Changes, 🛑 Docsite Deployment (2.1) — Approved & Locked Apr 1, 2026

tamara-corbalt merged commit c88e45b into main Apr 1, 2026
1 check passed

tamara-corbalt deleted the tdement/CMSDS-3954/add-markdown-only-pages branch April 1, 2026 15:34

Conversation

tamara-corbalt commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How to test

Run docs tests

Generate Hosted Markdown

Checklist

Uh oh!

jack-ryan-nava-pbc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

derek-cmsds left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tamara-corbalt commented Mar 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tamara-corbalt Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

derek-cmsds left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jack-ryan-nava-pbc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tamara-corbalt commented Mar 25, 2026 •

edited

Loading

tamara-corbalt Mar 30, 2026 •

edited

Loading