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	`c6180bd`
🔍 Latest deploy log	https://app.netlify.com/projects/v11-carbon-web-components/deploys/69e6a2384d52ef0008e5feb5
😎 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	`c6180bd`
🔍 Latest deploy log	https://app.netlify.com/projects/v11-carbon-react/deploys/69e6a238f76b30000889fa4b
😎 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.01%. Comparing base (df0693c) to head (c6180bd).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #22000      +/-   ##
==========================================
- Coverage   95.04%   95.01%   -0.03%     
==========================================
  Files         538      538              
  Lines       44982    44982              
  Branches     6459     6459              
==========================================
- Hits        42752    42739      -13     
- Misses       2101     2114      +13     
  Partials      129      129

Flag	Coverage Δ
main-packages	`89.03% <ø> (ø)`
web-components	`97.86% <ø> (-0.01%)`	⬇️

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

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

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
adamalston wants to merge 3 commits intocarbon-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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 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