docs: format MD and MDX docs by adamalston · Pull Request #22000 · carbon-design-system/carbon

adamalston · 2026-04-11T15:54:07Z

No issue.

Formatted MD and MDX docs.

Changelog

New

Added MDX formatting to lint-staged.

Changed

Formatted MD and MDX docs.
Fixed markdown alerts.
Fixed doc issues.

Removed

Deleted the invalid max_line_length property in .editorconfig. That property isn't supported per https://editorconfig.org/#supported-properties.

Testing / Reviewing

yarn format
yarn format:diff

An example of an issue the changes in this pull request fix is in https://github.com/carbon-design-system/carbon/blob/597001a9b6710da9531883b65a0852fde9ff199d/docs/guides/reviewing-pull-requests.md. The alert at the top of the file isn't rendered due to an issue with the way it's written.

I left a TODO with a question. I'm curious if anyone has any input. If there is no clear answer, I can try removing the component in a follow-up to determine whether it's still needed.

PR Checklist

As the author of this PR, before marking ready for review, confirm you:

Reviewed every line of the diff
Updated documentation and storybook examples
~~Wrote passing tests that cover this change~~
~~Addressed any impact on accessibility (a11y)~~
~~Tested for cross-browser consistency~~
Validated that this code is ready for review and status checks should pass

More details can be found in the pull request guide

netlify · 2026-04-11T15:57:07Z

✅ Deploy Preview for v11-carbon-web-components ready!

Name	Link
🔨 Latest commit	`1e14667`
🔍 Latest deploy log	https://app.netlify.com/projects/v11-carbon-web-components/deploys/69efe28d787e33000898a625
😎 Deploy Preview	https://deploy-preview-22000--v11-carbon-web-components.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-04-11T15:57:12Z

✅ Deploy Preview for v11-carbon-react ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`1e14667`
🔍 Latest deploy log	https://app.netlify.com/projects/v11-carbon-react/deploys/69efe28d0012e400083cfa2b
😎 Deploy Preview	https://deploy-preview-22000--v11-carbon-react.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

codecov · 2026-04-11T16:01:01Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.05%. Comparing base (6898a87) to head (1e14667).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #22000      +/-   ##
==========================================
- Coverage   95.07%   95.05%   -0.03%     
==========================================
  Files         539      539              
  Lines       45139    45139              
  Branches     6512     6539      +27     
==========================================
- Hits        42918    42905      -13     
- Misses       2092     2105      +13     
  Partials      129      129

Flag	Coverage Δ
main-packages	`89.10% <ø> (ø)`
web-components	`97.87% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

devadula-nandan

Thanks for this pr 🎉
1 question

devadula-nandan · 2026-04-13T10:47:38Z

+    <Button
+      renderIcon={(props) => <Add size={24} {...props} />}
+      iconDescription="Add">
+      Add
+    </Button>
+    <Button
+      renderIcon={(props) => <TrashCan size={24} {...props} />}
+      kind="danger"
+      iconDescription="TrashCan">
+      Delete
+    </Button>


Do you have any idea why formatting this mdx file is messing up the buttons content placing them in p tag?

Screen.Recording.2026-04-13.at.4.01.34.PM.mov

I have observed this in an other pr and avoided formatting the mdx there.
#21390 (comment)
I am not sure if there are any more cases like this in other mdx files.

Will wrapping them in storybook unstyled fixes them? could be related to these efforts 🤔

This could be an issue with storybook mdx parsing too. But need to verify.

There's a rendering issue with MDX parsing. Newline separated text within JSX can be interpreted as Markdown, causing it to render as p elements. I updated the code to use JavaScript expression children so the content is treated as plain text nodes.

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

I am not sure if there are any more cases like this in other mdx files.

There are. Would you like me to fix them here or in a separate pull request? Adding an MDX lint rule for multiline text children in JSX may help prevent similar issues in the future.

carbon/packages/react/src/components/Button/Button.mdx

Lines 288 to 292 in c6180bd

<Unstyled>

<Button as="div" role="button">

a11y Button

</Button>

</Unstyled>

carbon/packages/react/src/components/ClassPrefix/ClassPrefix.mdx

Lines 67 to 69 in c6180bd

<LinkTo title="Hooks/usePrefix" name="Overview">

usePrefix

</LinkTo>

carbon/packages/react/src/components/ComposedModal/ComposedModal.mdx

Lines 122 to 137 in c6180bd

<Unstyled>

<InlineNotification

kind="warning"

title="Warning"

className="sb-notification">

<CodeSnippet type="inline" hideCopyButton>

Modal

</CodeSnippet>

and

<CodeSnippet type="inline" hideCopyButton>

ComposedModal

</CodeSnippet>

have to be put at the top level in a React tree. The easiest way to ensure

that is using a React portal, as shown in the example above.

</InlineNotification>

</Unstyled>

carbon/packages/react/src/components/ComposedModal/ComposedModal.mdx

Lines 257 to 273 in c6180bd

<Unstyled>

<InlineNotification

kind="warning"

title="Warning"

className="sb-notification">

As the instructions for the three buttons imply,

<CodeSnippet type="inline" hideCopyButton>

ModalFooter

</CodeSnippet>

is flexible with the buttons you render using

<CodeSnippet type="inline" hideCopyButton>

Button

</CodeSnippet>

components. In this case, your application code is responsible for handling

button actions, such as closing the modal.

</InlineNotification>

</Unstyled>

carbon/packages/react/src/components/Modal/Modal.mdx

Lines 125 to 140 in c6180bd

<Unstyled>

<InlineNotification

kind="warning"

title="Warning"

className="sb-notification">

<CodeSnippet type="inline" hideCopyButton>

Modal

</CodeSnippet>

and

<CodeSnippet type="inline" hideCopyButton>

ComposedModal

</CodeSnippet>

have to be put at the top level in a React tree. The easiest way to ensure

that is using a React portal, as shown in the example above.

</InlineNotification>

</Unstyled>

carbon/packages/react/src/components/Modal/Modal.mdx

Lines 260 to 276 in c6180bd

<Unstyled>

<InlineNotification

kind="warning"

title="Warning"

className="sb-notification">

As the instructions for the three buttons imply,

<CodeSnippet type="inline" hideCopyButton>

ModalFooter

</CodeSnippet>

is flexible with the buttons you render using

<CodeSnippet type="inline" hideCopyButton>

Button

</CodeSnippet>

components. In this case, your application code is responsible for handling

button actions, such as closing the modal.

</InlineNotification>

</Unstyled>

Great findings!
thanks for looking into this.

fixing the lint rules in a seperate pr makes sense to me

#22162
#22147

tay1orjones

Appreciate you 🙏

docs: format MD and MDX docs

0904885

adamalston marked this pull request as ready for review April 13, 2026 00:43

adamalston requested review from a team as code owners April 13, 2026 00:43

adamalston requested review from devadula-nandan and tay1orjones April 13, 2026 00:43

adamalston deployed to @carbon/react storybook preview April 13, 2026 00:56 — with GitHub Actions View deployment

devadula-nandan reviewed Apr 13, 2026

View reviewed changes

adamalston added 2 commits April 20, 2026 18:00

Merge branch 'main' into n/a-mdx

cc73e02

fix: prevent mdx paragraph wrapping in jsx children

c6180bd

adamalston deployed to @carbon/react storybook preview April 20, 2026 22:15 — with GitHub Actions View deployment

adamalston requested a review from devadula-nandan April 20, 2026 22:24

devadula-nandan approved these changes Apr 21, 2026

View reviewed changes

devadula-nandan added the status: one more review 👀 label Apr 21, 2026

adamalston mentioned this pull request Apr 23, 2026

chore(agents): clarify pr template use, add experimental validation #21967

Merged

3 tasks

tay1orjones reviewed Apr 27, 2026

View reviewed changes

Comment thread .editorconfig

tay1orjones reviewed Apr 27, 2026

View reviewed changes

Comment thread packages/react/src/components/ComboBox/ComboBox.mdx Outdated

adamalston added 2 commits April 27, 2026 18:24

Merge branch 'main' into n/a-mdx

c651c89

docs: remove ComboBox shouldFilterItem example

1e14667

adamalston requested a review from tay1orjones April 27, 2026 22:26

adamalston deployed to @carbon/react storybook preview April 27, 2026 22:41 — with GitHub Actions View deployment

tay1orjones approved these changes Apr 28, 2026

View reviewed changes

tay1orjones added this pull request to the merge queue Apr 28, 2026

Merged via the queue into carbon-design-system:main with commit 51624f6 Apr 28, 2026
38 of 39 checks passed

adamalston deleted the n/a-mdx branch April 29, 2026 01:28

adamalston removed the status: one more review 👀 label Apr 29, 2026

This was referenced Apr 29, 2026

Add linting for MDX #22147

Open

fix: prevent mdx docs from wrapping jsx text in p tags #22162

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: format MD and MDX docs#22000

docs: format MD and MDX docs#22000
tay1orjones merged 5 commits into
carbon-design-system:mainfrom
adamalston:n/a-mdx

adamalston commented Apr 11, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Apr 11, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Apr 11, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Apr 11, 2026 •

edited

Loading

Uh oh!

devadula-nandan left a comment

Uh oh!

devadula-nandan Apr 13, 2026

Uh oh!

devadula-nandan Apr 13, 2026

Uh oh!

adamalston Apr 20, 2026

Uh oh!

devadula-nandan Apr 21, 2026

Uh oh!

adamalston May 2, 2026

Uh oh!

Uh oh!

Uh oh!

tay1orjones left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	<Unstyled>
	<Button as="div" role="button">
	a11y Button
	</Button>
	</Unstyled>

	<LinkTo title="Hooks/usePrefix" name="Overview">
	usePrefix
	</LinkTo>

	<Unstyled>
	<InlineNotification
	kind="warning"
	title="Warning"
	className="sb-notification">
	<CodeSnippet type="inline" hideCopyButton>
	Modal
	</CodeSnippet>
	and
	<CodeSnippet type="inline" hideCopyButton>
	ComposedModal
	</CodeSnippet>
	have to be put at the top level in a React tree. The easiest way to ensure
	that is using a React portal, as shown in the example above.
	</InlineNotification>
	</Unstyled>

Conversation

adamalston commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

Testing / Reviewing

PR Checklist

Uh oh!

netlify Bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for v11-carbon-web-components ready!

Uh oh!

netlify Bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for v11-carbon-react ready!

Uh oh!

codecov Bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

devadula-nandan left a comment

Choose a reason for hiding this comment

Uh oh!

devadula-nandan Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

devadula-nandan Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

adamalston Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

devadula-nandan Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

adamalston May 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tay1orjones left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adamalston commented Apr 11, 2026 •

edited

Loading

netlify Bot commented Apr 11, 2026 •

edited

Loading

netlify Bot commented Apr 11, 2026 •

edited

Loading

codecov Bot commented Apr 11, 2026 •

edited

Loading