You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
See the Docusaurus 4.0 release notes. The documented Markdown syntax and @theme/Admonition props remain unchanged.
Custom @theme/MDXComponents mappings must provide Admonition instead of admonition: rename the key, keeping the same component.
Remark/rehype plugins inspecting admonitions must handle standard MDX JSX nodes instead of container directives or the invented mdxAdmonitionTitle node.
Rich titles arrive through the title prop. The exported processAdmonitionProps helper remains available for previously swizzled components.
If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.
Maintainer-requested implementation; no separate tracking issue.
Motivation
Replace the MDX v1 title wrapper with <Admonition type="..." title={...}>. Rich titles stay in the syntax tree through user remark/rehype plugins, then become JSX props before compilation, preserving link, image, emoji, JSX, and custom component processing. Update the theme entrypoint and MDX component registration accordingly.
Keep plain titles, attributes, nesting, legacy title syntax, and empty-label defaults. This also prevents CommonMark HTML processing from lowercasing the old title wrapper name.
Test Plan
pnpm test: 2,994 tests pass across 185 files.
Builds pass for @docusaurus/mdx-loader, @docusaurus/theme-common, and @docusaurus/theme-classic.
Repository-wide lint checks, dependency deduplication, and formatting pass.
pnpm build:website:fast passes, including the rich-title dogfooding page.
Compiler regressions cover Markdown/MDX titles, nested admonitions, title precedence, empty labels, local images, JSX/expressions, user plugins, and provider component overrides. Theme tests cover registration and rendering.
Added rich-title dogfooding examples and applied the Argos label. Screenshot comparison: 269 unchanged screenshots; the only change is the expanded admonition dogfooding page, awaiting visual approval. HTML snapshots pass. The deployed rich-title examples render correctly.
Both CI build-size reports show a 0 B size change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ArgosAdd this label to run UI visual regression tests. See argos.yml GH action.CLA SignedSigned Facebook CLApr: breaking changeExisting sites may not build successfully in the new version. Description contains more details.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Breaking Changes
(AI-assisted)
See the Docusaurus 4.0 release notes. The documented Markdown syntax and
@theme/Admonitionprops remain unchanged.@theme/MDXComponentsmappings must provideAdmonitioninstead ofadmonition: rename the key, keeping the same component.mdxAdmonitionTitlenode.titleprop. The exportedprocessAdmonitionPropshelper remains available for previously swizzled components.Pre-flight checklist
Maintainer-requested implementation; no separate tracking issue.
Motivation
Replace the MDX v1 title wrapper with
<Admonition type="..." title={...}>. Rich titles stay in the syntax tree through user remark/rehype plugins, then become JSX props before compilation, preserving link, image, emoji, JSX, and custom component processing. Update the theme entrypoint and MDX component registration accordingly.Keep plain titles, attributes, nesting, legacy title syntax, and empty-label defaults. This also prevents CommonMark HTML processing from lowercasing the old title wrapper name.
Test Plan
pnpm test: 2,994 tests pass across 185 files.@docusaurus/mdx-loader,@docusaurus/theme-common, and@docusaurus/theme-classic.pnpm build:website:fastpasses, including the rich-title dogfooding page.Argoslabel. Screenshot comparison: 269 unchanged screenshots; the only change is the expanded admonition dogfooding page, awaiting visual approval. HTML snapshots pass. The deployed rich-title examples render correctly.Test links
Deploy preview: https://deploy-preview-12459--docusaurus-2.netlify.app/
Related issues/PRs
None.