"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([["80261"],{55732:function(e,n,s){s.d(n,{Z:()=>r});let r=s.p+"assets/images/social-card-1c688c53b51bdaa6e15ae532bf756276.png"},85345:function(e,n,s){s.d(n,{Z:()=>r});let r=s.p+"assets/images/mdx-checker-output-0f96cc19fd3ed4d55901ca90ad657c14.png"},51476:function(e,n,s){s.d(n,{Z:()=>r});let r=s.p+"assets/images/mdx2-playground-options-eab88e8328a6902759c4236ffc93d9c6.png"},32007:function(e,n,s){s.d(n,{Z:()=>r});let r=s.p+"assets/images/social-card-1c688c53b51bdaa6e15ae532bf756276.png"},27753:function(e,n,s){s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>a,default:()=>h,frontMatter:()=>t,metadata:()=>r,toc:()=>d});var r=s(24174),o=s(85893),i=s(80980);let t={title:"Preparing your site for Docusaurus v3",authors:["slorber"],tags:["maintenance"],slug:"/preparing-your-site-for-docusaurus-v3",image:"./img/social-card.png"},a=void 0,c={image:s(55732).Z,authorsImageUrls:[void 0]},d=[{value:"Preparatory work",id:"preparatory-work",level:2},{value:"Preparing content for MDX v3",id:"preparing-content-for-mdx-v3",level:2},{value:"Using the MDX playground",id:"using-the-mdx-playground",level:3},{value:"Using the MDX checker CLI",id:"using-the-mdx-checker-cli",level:3},{value:"Common MDX problems",id:"common-mdx-problems",level:3},{value:"Bad usage of {",id:"bad-usage-of-",level:4},{value:"Bad usage of <",id:"bad-usage-of--1",level:4},{value:"Bad usage of GFM Autolink",id:"bad-usage-of-gfm-autolink",level:4},{value:"Lower-case MDXComponent mapping",id:"lower-case-mdxcomponent-mapping",level:4},{value:"Unintended extra paragraphs",id:"unintended-extra-paragraphs",level:4},{value:"Unintended usage of directives",id:"unintended-usage-of-directives",level:4},{value:"Unsupported indented code blocks",id:"unsupported-indented-code-blocks",level:4},{value:"MDX plugins",id:"mdx-plugins",level:3},{value:"Other breaking changes",id:"other-breaking-changes",level:2},{value:"Node.js 18.0",id:"nodejs-180",level:3},{value:"React 18.0",id:"react-180",level:3},{value:"TypeScript 5.0",id:"typescript-50",level:3},{value:"TypeScript base config",id:"typescript-base-config",level:3},{value:"Admonition warning",id:"admonition-warning",level:3},{value:"Versioned sidebars",id:"versioned-sidebars",level:3},{value:"Try Docusaurus v3 today",id:"try-docusaurus-v3-today",level:2},{value:"Ask for help",id:"ask-for-help",level:2},{value:"Conclusion",id:"conclusion",level:2}];function l(e){let n={a:"a",admonition:"admonition",blockquote:"blockquote",code:"code",h2:"h2",h3:"h3",h4:"h4",img:"img",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,i.a)(),...e.components},{Details:r}=n;return r||function(e,n){throw Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}("Details",!0),(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.admonition,{type:"warning",children:(0,o.jsxs)(n.p,{children:["This blog post was written when Docusaurus v3 was in beta. There are some changes in dependency versions and upgrade steps you should be aware of if upgrading to Docusaurus v3 current stable releases. Use the ",(0,o.jsx)(n.a,{href:"https://docusaurus.io/docs/next/migration/v3",children:"upgrade guide"})," for the most up-to-date migration steps."]})}),"\n",(0,o.jsxs)(n.p,{children:[(0,o.jsx)(n.strong,{children:"Docusaurus v3"})," is now ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9312",children:(0,o.jsx)(n.strong,{children:"in beta"})})," and the official release is around the corner. This is the perfect time to start ",(0,o.jsx)(n.strong,{children:"preparing your site"})," for this new major version."]}),"\n",(0,o.jsxs)(n.p,{children:["Docusaurus v3 comes with a few ",(0,o.jsx)(n.strong,{children:"breaking changes"}),", many of which can be ",(0,o.jsx)(n.strong,{children:"handled today under Docusaurus v2"}),". Preparing your site ahead of time can be done incrementally, and will make it easier to upgrade to v3."]}),"\n",(0,o.jsxs)(n.p,{children:["The main breaking change is the upgrade from MDX v1 to MDX v3. Read the ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/blog/v2/",children:(0,o.jsx)(n.strong,{children:"MDX v2"})})," and ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/blog/v3/",children:(0,o.jsx)(n.strong,{children:"MDX v3"})})," release notes for details. MDX will now compile your Markdown content ",(0,o.jsx)(n.strong,{children:"more strictly"})," and with ",(0,o.jsx)(n.strong,{children:"subtle differences"}),"."]}),"\n",(0,o.jsx)(n.p,{children:"This article will mostly focus on how to prepare your content for this new MDX version, and will also list a few other breaking changes that you can handle today."}),"\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"Preparing your site for Docusaurus v3 - social card",src:s(32007).Z+"",width:"1040",height:"546"})}),"\n",(0,o.jsx)(n.admonition,{type:"warning",children:(0,o.jsxs)(n.p,{children:["This article mentions most Docusaurus v3 breaking changes, but is not exhaustive. Read the ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9312",children:"v3.0.0-beta.0 release notes"})," for an exhaustive list."]})}),"\n",(0,o.jsxs)(n.admonition,{title:"Don't be afraid",type:"tip",children:[(0,o.jsx)(n.p,{children:"There's a lot of content in this blog post, but many Docusaurus v2 sites can upgrade with very few changes."}),(0,o.jsxs)(n.p,{children:["If your site is relatively small, with only a few customizations, you can probably ",(0,o.jsx)(n.a,{href:"#try-docusaurus-v3-today",children:"upgrade to Docusaurus v3"})," immediately."]})]}),"\n",(0,o.jsx)(n.h2,{id:"preparatory-work",children:"Preparatory work"}),"\n",(0,o.jsxs)(n.p,{children:["Before preparing for the Docusaurus v3 upgrade, we recommend upgrading to the latest ",(0,o.jsx)(n.a,{href:"/versions",children:"Docusaurus v2 version"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["Depending on the complexity of your site, it may be a good idea to adopt the ",(0,o.jsx)(n.a,{href:"/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing",children:"visual regression testing workflow"})," that we recently presented. It could help you catch unexpected visual side effects occurring during the Docusaurus v3 upgrade."]}),"\n",(0,o.jsxs)(n.p,{children:["We also recommend using the ",(0,o.jsx)(n.code,{children:".mdx"})," extension whenever you use JSX, ",(0,o.jsx)(n.code,{children:"import"}),", or ",(0,o.jsx)(n.code,{children:"export"})," (i.e. MDX features) inside a Markdown file. It is semantically more correct and improves compatibility with external tools (IDEs, formatters, linters, etc.). In future versions of Docusaurus, ",(0,o.jsx)(n.code,{children:".md"})," files will be parsed as standard ",(0,o.jsx)(n.a,{href:"https://commonmark.org/",children:"CommonMark"}),", which does not support these features. In Docusaurus v3, ",(0,o.jsx)(n.code,{children:".md"})," files keep being compiled as MDX files, but it will be possible to ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/issues/3018",children:"opt-in for CommonMark"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"preparing-content-for-mdx-v3",children:"Preparing content for MDX v3"}),"\n",(0,o.jsxs)(n.p,{children:["MDX is a major dependency of Docusaurus responsible for compiling your ",(0,o.jsx)(n.code,{children:".md"})," and ",(0,o.jsx)(n.code,{children:".mdx"})," files to React components."]}),"\n",(0,o.jsxs)(n.p,{children:["MDX v3 is much better, but also comes with changes that probably require you to refactor your content a bit. MDX v3 is stricter, and some components that compiled fine under v1 might now fail to compile under v3, most likely because of ",(0,o.jsx)(n.code,{children:"{"})," and ",(0,o.jsx)(n.code,{children:"<"})," characters."]}),"\n",(0,o.jsxs)(n.p,{children:["Upgrading MDX comes with all the breaking changes documented on the ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/blog/v2/",children:"MDX v2"})," and ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/blog/v3/",children:"MDX v3"})," release blog posts. Most breaking changes come from MDX v2. The ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/migrating/v2/",children:"MDX v2 migration guide"})," has a section on how to ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/migrating/v2/#update-mdx-files",children:"update MDX files"})," that will be particularly relevant to us. Also make sure to read the ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/docs/troubleshooting-mdx/",children:"Troubleshooting MDX"})," page that can help you interpret common MDX error messages."]}),"\n",(0,o.jsxs)(n.p,{children:["Make sure to also read our updated ",(0,o.jsx)(n.a,{href:"/docs/markdown-features/react",children:(0,o.jsx)(n.strong,{children:"MDX and React"})})," documentation page."]}),"\n",(0,o.jsx)(n.admonition,{title:"Ask for help",type:"tip",children:(0,o.jsxs)(n.p,{children:["We have a dedicated ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9053",children:"MDX v3 - Upgrade Support"})," discussion."]})}),"\n",(0,o.jsx)(n.h3,{id:"using-the-mdx-playground",children:"Using the MDX playground"}),"\n",(0,o.jsxs)(n.p,{children:["The MDX playground is your new best friend. It permits to understand how your content is ",(0,o.jsx)(n.strong,{children:"compiled to React components"}),", and troubleshoot compilation or rendering issues in isolation."]}),"\n",(0,o.jsx)(n.p,{children:"Each MDX version comes with its own playground:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://mdxjs.com/playground/",children:"MDX playground - current version"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground/",children:"MDX playground - v1"})}),"\n"]}),"\n",(0,o.jsxs)(r,{children:[(0,o.jsx)("summary",{children:"Configuring the MDX playground options for Docusaurus"}),(0,o.jsxs)(n.p,{children:["To obtain a compilation behavior similar to what Docusaurus v2 uses, please turn on these options on the ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/playground/",children:"MDX playground"}),":"]}),(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["Use ",(0,o.jsx)(n.code,{children:"MDX"})]}),"\n",(0,o.jsxs)(n.li,{children:["Use ",(0,o.jsx)(n.code,{children:"remark-gfm"})]}),"\n",(0,o.jsxs)(n.li,{children:["Use ",(0,o.jsx)(n.code,{children:"remark-directive"})]}),"\n"]}),(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"Screenshot of the MDX playground's options panel, with only the "Use MDX", "Use remark-gfm", and "Use remark-directive" options checked",src:s(51476).Z+"",width:"1968",height:"1316"})})]}),"\n",(0,o.jsx)(n.p,{children:"Using the two MDX playgrounds side-by-side, you will soon notice that some content is compiled differently or fails to compile in v3."}),"\n",(0,o.jsx)(n.admonition,{title:"Making your content future-proof",type:"tip",children:(0,o.jsxs)(n.p,{children:["The goal will be to refactor your problematic content so that it ",(0,o.jsx)(n.strong,{children:"works fine with both versions of MDX"}),". This way, when you upgrade to Docusaurus v3, this content will already work out-of-the-box."]})}),"\n",(0,o.jsx)(n.h3,{id:"using-the-mdx-checker-cli",children:"Using the MDX checker CLI"}),"\n",(0,o.jsxs)(n.p,{children:["We provide a ",(0,o.jsx)(n.a,{href:"https://github.com/slorber/docusaurus-mdx-checker",children:"docusaurus-mdx-checker"})," CLI that permits to easily spot problematic content. Run this command today on your Docusaurus v2 site to obtain a list of files that will fail to compile under MDX v3."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-bash",children:"npx docusaurus-mdx-checker\n"})}),"\n",(0,o.jsx)(n.p,{children:"For each compilation issue, the CLI will log the file path and a line number to look at."}),"\n",(0,o.jsx)(n.p,{children:(0,o.jsx)(n.img,{alt:"Screenshot of the terminal showing an example MDX checker CLI output, with a few error messages",src:s(85345).Z+"",width:"1161",height:"417"})}),"\n",(0,o.jsx)(n.admonition,{type:"tip",children:(0,o.jsx)(n.p,{children:"Use this CLI to estimate of how much work will be required to make your content compatible with MDX v3."})}),"\n",(0,o.jsxs)(n.admonition,{type:"warning",children:[(0,o.jsx)(n.p,{children:"This CLI is a best effort, and will only report compilation errors."}),(0,o.jsxs)(n.p,{children:["It will not report subtle compilation changes that do not produce errors but can affect how your content is displayed. To catch these problems, we recommend using ",(0,o.jsx)(n.a,{href:"/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing",children:"visual regression tests"}),"."]})]}),"\n",(0,o.jsx)(n.h3,{id:"common-mdx-problems",children:"Common MDX problems"}),"\n",(0,o.jsx)(n.p,{children:"We upgraded a few Docusaurus sites to Docusaurus v3 and MDX v3:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/pull/8288",children:"Docusaurus PR"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://github.com/facebook/react-native-website/pull/3780",children:"React-Native PR"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://github.com/jestjs/jest/pull/14463",children:"Jest PR"})}),"\n"]}),"\n",(0,o.jsx)(n.p,{children:"These upgrades permitted us to aggregate the most common content problems, and document how to best handle them."}),"\n",(0,o.jsxs)(n.h4,{id:"bad-usage-of-",children:["Bad usage of ",(0,o.jsx)(n.code,{children:"{"})]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"{"})," character is used for opening ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/docs/what-is-mdx/#expressions",children:"JavaScript expressions"}),". MDX will now fail if what you put inside ",(0,o.jsx)(n.code,{children:"{expression}"})," is not a valid expression."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:"The object shape looks like {username: string, age: number}\n"})}),"\n",(0,o.jsx)(n.admonition,{title:"Error message",type:"danger",children:(0,o.jsxs)(n.blockquote,{children:["\n",(0,o.jsx)(n.p,{children:"Could not parse expression with acorn: Unexpected content after expression"}),"\n"]})}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsx)(n.p,{children:"Available options to fix this error:"}),(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["Use inline code: ",(0,o.jsx)(n.code,{children:"{username: string, age: number}"})]}),"\n",(0,o.jsxs)(n.li,{children:["Use the HTML code: ",(0,o.jsx)(n.code,{children:"{"})]}),"\n",(0,o.jsxs)(n.li,{children:["Escape it: ",(0,o.jsx)(n.code,{children:"\\{"})]}),"\n"]})]}),"\n",(0,o.jsxs)(n.h4,{id:"bad-usage-of--1",children:["Bad usage of ",(0,o.jsx)(n.code,{children:"<"})]}),"\n",(0,o.jsxs)(n.p,{children:["The ",(0,o.jsx)(n.code,{children:"<"})," character is used for opening ",(0,o.jsx)(n.a,{href:"https://mdxjs.com/docs/what-is-mdx/#jsx",children:"JSX tags"}),". MDX will now fail if it thinks your JSX is invalid."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:'Use Android version <5\n\nYou can use a generic type like Array\n\nFollow the template "Road to "\n'})}),"\n",(0,o.jsxs)(n.admonition,{title:"Error messages",type:"danger",children:[(0,o.jsxs)(n.blockquote,{children:["\n",(0,o.jsxs)(n.p,{children:["Unexpected character ",(0,o.jsx)(n.code,{children:"5"})," (U+0035) before name, expected a character that can start a name, such as a letter, ",(0,o.jsx)(n.code,{children:"$"}),", or ",(0,o.jsx)(n.code,{children:"_"})]}),"\n"]}),(0,o.jsxs)(n.blockquote,{children:["\n",(0,o.jsxs)(n.p,{children:["Expected a closing tag for ",(0,o.jsx)(n.code,{children:""})," (1:6-1:9) before the end of ",(0,o.jsx)(n.code,{children:"paragraph"})," end-tag-mismatch mdast-util-mdx-jsx"]}),"\n"]}),(0,o.jsxs)(n.blockquote,{children:["\n",(0,o.jsxs)(n.p,{children:["Expected a closing tag for ",(0,o.jsx)(n.code,{children:""})," (134:19-134:39) before the end of ",(0,o.jsx)(n.code,{children:"paragraph"})]}),"\n"]})]}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsx)(n.p,{children:"Available options to fix this error:"}),(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["Use inline code: ",(0,o.jsx)(n.code,{children:"Array"})]}),"\n",(0,o.jsxs)(n.li,{children:["Use the HTML code: ",(0,o.jsx)(n.code,{children:"<"})," or ",(0,o.jsx)(n.code,{children:"<"})]}),"\n",(0,o.jsxs)(n.li,{children:["Escape it: ",(0,o.jsx)(n.code,{children:"\\<"})," (unfortunately the ",(0,o.jsx)(n.code,{children:"\\"})," will be displayed under MDX v1)"]}),"\n"]})]}),"\n",(0,o.jsx)(n.h4,{id:"bad-usage-of-gfm-autolink",children:"Bad usage of GFM Autolink"}),"\n",(0,o.jsxs)(n.p,{children:["Docusaurus supports ",(0,o.jsx)(n.a,{href:"https://github.github.com/gfm/",children:"GitHub Flavored Markdown (GFM)"}),", but ",(0,o.jsx)(n.a,{href:"https://github.github.com/gfm/#autolinks",children:"autolink"})," using the ",(0,o.jsx)(n.code,{children:""})," syntax is not supported anymore by MDX."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:"\n\n\n"})}),"\n",(0,o.jsxs)(n.admonition,{title:"Error messages",type:"danger",children:[(0,o.jsxs)(n.blockquote,{children:["\n",(0,o.jsxs)(n.p,{children:["Unexpected character ",(0,o.jsx)(n.code,{children:"@"})," (U+0040) in name, expected a name character such as letters, digits, ",(0,o.jsx)(n.code,{children:"$"}),", or ",(0,o.jsx)(n.code,{children:"_"}),"; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use ",(0,o.jsx)(n.code,{children:"[text](url)"}),")"]}),"\n"]}),(0,o.jsxs)(n.blockquote,{children:["\n",(0,o.jsxs)(n.p,{children:["Unexpected character ",(0,o.jsx)(n.code,{children:"/"})," (U+002F) before local name, expected a character that can start a name, such as a letter, ",(0,o.jsx)(n.code,{children:"$"}),", or ",(0,o.jsx)(n.code,{children:"_"})," (note: to create a link in MDX, use ",(0,o.jsx)(n.code,{children:"[text](url)"}),")"]}),"\n"]})]}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsxs)(n.p,{children:["Use regular Markdown links, or remove the ",(0,o.jsx)(n.code,{children:"<"})," and ",(0,o.jsx)(n.code,{children:">"}),". MDX and GFM are able to autolink literals already."]}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:"sebastien@thisweekinreact.com\n[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)\n\nhttp://localhost:3000\n[http://localhost:3000](http://localhost:3000)\n"})})]}),"\n",(0,o.jsx)(n.h4,{id:"lower-case-mdxcomponent-mapping",children:"Lower-case MDXComponent mapping"}),"\n",(0,o.jsxs)(n.p,{children:["For users providing a ",(0,o.jsxs)(n.a,{href:"/docs/markdown-features/react#mdx-component-scope",children:["custom ",(0,o.jsx)(n.code,{children:"MDXComponent"}),"mapping"]}),', components are now "sandboxed":']}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["a ",(0,o.jsx)(n.code,{children:"MDXComponent"})," mapping for ",(0,o.jsx)(n.code,{children:"h1"})," only gets used for ",(0,o.jsx)(n.code,{children:"# hi"})," but not for ",(0,o.jsx)(n.code,{children:"
hi
"})]}),"\n",(0,o.jsxs)(n.li,{children:["a ",(0,o.jsx)(n.strong,{children:"lower-cased"})," custom element name will not be substituted by its respective ",(0,o.jsx)(n.code,{children:"MDXComponent"})," component anymore"]}),"\n"]}),"\n",(0,o.jsx)(n.admonition,{title:"visual difference",type:"danger",children:(0,o.jsxs)(n.p,{children:["Your ",(0,o.jsxs)(n.a,{href:"/docs/markdown-features/react#mdx-component-scope",children:[(0,o.jsx)(n.code,{children:"MDXComponent"})," component mapping"]})," might not be applied as before, and your custom components might no longer be used."]})}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsxs)(n.p,{children:["For native Markdown elements, you can keep using ",(0,o.jsx)(n.strong,{children:"lower-case"}),": ",(0,o.jsx)(n.code,{children:"p"}),", ",(0,o.jsx)(n.code,{children:"h1"}),", ",(0,o.jsx)(n.code,{children:"img"}),", ",(0,o.jsx)(n.code,{children:"a"}),"..."]}),(0,o.jsxs)(n.p,{children:["For any other element, ",(0,o.jsx)(n.strong,{children:"use upper-case names"}),"."]}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-diff",metastring:'title="src/theme/MDXComponents.js"',children:' import MDXComponents from \'@theme-original/MDXComponents\';\n\n export default {\n ...MDXComponents,\n p: (props) => \n- myElement: (props) => ,\n+ MyElement: (props) => ,\n };\n'})})]}),"\n",(0,o.jsx)(n.h4,{id:"unintended-extra-paragraphs",children:"Unintended extra paragraphs"}),"\n",(0,o.jsxs)(n.p,{children:["In MDX, it is now possible to interleave JSX and Markdown more easily without requiring extra line breaks. Writing content on multiple lines can also produce new expected ",(0,o.jsx)(n.code,{children:"
"})," tags."]}),"\n",(0,o.jsxs)(n.admonition,{title:"visual difference",type:"danger",children:[(0,o.jsx)(n.p,{children:"See how this content is rendered differently by MDX v1 and v3."}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:"
\n"})})]}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsxs)(n.p,{children:["If you don't want an extra ",(0,o.jsx)(n.code,{children:"
"})," tag, refactor content on a case by case basis to use a single-line JSX tag."]}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-diff",children:' \n \n- \n- My image caption\n- \n+ My image caption\n \n'})}),(0,o.jsxs)(n.p,{children:['If your content contains "Markdown inlines" (',(0,o.jsx)(n.code,{children:"**"}),", ",(0,o.jsx)(n.code,{children:"*"}),", ",(0,o.jsx)(n.code,{children:"_"}),", ",(0,o.jsx)(n.code,{children:"[link](/path)"}),"), you might not be able to refactor it ahead of time, and will have to do it alongside the Docusaurus v3 upgrade."]})]}),"\n",(0,o.jsx)(n.h4,{id:"unintended-usage-of-directives",children:"Unintended usage of directives"}),"\n",(0,o.jsxs)(n.p,{children:["Docusaurus v3 now uses ",(0,o.jsx)(n.a,{href:"https://talk.commonmark.org/t/generic-directives-plugins-syntax/444",children:"Markdown Directives"})," (implemented with ",(0,o.jsx)(n.a,{href:"https://github.com/remarkjs/remark-directive",children:"remark-directive"}),") as a generic way to provide support for admonitions, and other upcoming Docusaurus features."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:"This is a :textDirective\n\n::leafDirective\n\n:::containerDirective\n\nContainer directive content\n\n:::\n"})}),"\n",(0,o.jsxs)(n.admonition,{title:"Visual change",type:"danger",children:[(0,o.jsx)(n.p,{children:"Directives are parsed with the purpose of being handled by other Remark plugins. Unhandled directives will be ignored, and won't be rendered back in their original form."}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:"The AWS re:Invent conf is great\n"})}),(0,o.jsxs)(n.p,{children:["Due to ",(0,o.jsx)(n.code,{children:":Invent"})," being parsed as a text directive, this will now be rendered as:"]}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{children:"The AWS re\nconf is great\n"})})]}),"\n",(0,o.jsx)(n.admonition,{title:"How to prepare",type:"tip",children:(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:["Use the HTML code: ",(0,o.jsx)(n.code,{children:":"})]}),"\n",(0,o.jsxs)(n.li,{children:["Add a space after ",(0,o.jsx)(n.code,{children:":"})," (if it makes sense): ",(0,o.jsx)(n.code,{children:": text"})]}),"\n",(0,o.jsxs)(n.li,{children:["Escape it: ",(0,o.jsx)(n.code,{children:"\\:"})," (unfortunately the ",(0,o.jsx)(n.code,{children:"\\"})," will be displayed under MDX v1)"]}),"\n"]})}),"\n",(0,o.jsx)(n.h4,{id:"unsupported-indented-code-blocks",children:"Unsupported indented code blocks"}),"\n",(0,o.jsx)(n.p,{children:"MDX does not transform indented text as code blocks anymore."}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:' console.log("hello");\n'})}),"\n",(0,o.jsx)(n.admonition,{title:"Visual change",type:"danger",children:(0,o.jsx)(n.p,{children:"The upgrade does not generally produce new MDX compilation errors, but can lead to content being rendered in an unexpected way because there isn't a code block anymore."})}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsx)(n.p,{children:"Use the regular code block syntax instead of indentation:"}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-md",metastring:'title="example.md"',children:"```js\nconsole.log('hello');\n```\n"})})]}),"\n",(0,o.jsx)(n.h3,{id:"mdx-plugins",children:"MDX plugins"}),"\n",(0,o.jsxs)(n.p,{children:["All the official packages (Unified, Remark, Rehype...) in the MDX ecosystem are now ",(0,o.jsx)(n.a,{href:"https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c",children:(0,o.jsx)(n.strong,{children:"ES Modules only"})})," and do not support ",(0,o.jsx)(n.a,{href:"https://nodejs.org/api/modules.html#modules-commonjs-modules",children:"CommonJS"})," anymore."]}),"\n",(0,o.jsxs)(n.p,{children:["In practice this means that you can't do ",(0,o.jsx)(n.code,{children:'require("remark-plugin")'})," anymore."]}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsxs)(n.p,{children:["Docusaurus v3 now supports ",(0,o.jsx)(n.a,{href:"https://flaviocopes.com/es-modules/",children:(0,o.jsx)(n.strong,{children:"ES Modules"})})," configuration files. We recommend that you migrate your config file to ES module, that enables you to import the Remark plugins easily:"]}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-js",metastring:'title="docusaurus.config.js"',children:"import remarkPlugin from 'remark-plugin';\n\nexport default {\n title: 'Docusaurus',\n /* site config using remark plugins here */\n};\n"})}),(0,o.jsxs)(n.p,{children:["If you want to keep using CommonJS modules, you can use dynamic imports as a workaround that enables you to import ES modules inside a CommonJS module. Fortunately, the ",(0,o.jsx)(n.a,{href:"/docs/configuration#syntax-to-declare-docusaurus-config",children:"Docusaurus config supports the usage of an async function"})," to let you do so."]}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-js",metastring:'title="docusaurus.config.js"',children:"module.exports = async function () {\n const myPlugin = (await import('remark-plugin')).default;\n return {\n // site config...\n };\n};\n"})})]}),"\n",(0,o.jsx)(n.admonition,{title:"For plugin authors",type:"info",children:(0,o.jsxs)(n.p,{children:["If you created custom Remark or Rehype plugins, you may need to refactor those, or eventually rewrite them completely, due to how the new AST is structured. We have created a ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9337",children:"dedicated support discussion"})," to help plugin authors upgrade their code."]})}),"\n",(0,o.jsx)(n.h2,{id:"other-breaking-changes",children:"Other breaking changes"}),"\n",(0,o.jsx)(n.p,{children:"Apart from MDX, there are other breaking changes that you can already prepare your site for, notably major version upgrades of important dependencies."}),"\n",(0,o.jsx)(n.h3,{id:"nodejs-180",children:"Node.js 18.0"}),"\n",(0,o.jsxs)(n.p,{children:["Node.js 16 ",(0,o.jsx)(n.a,{href:"https://nodejs.org/en/blog/announcements/nodejs16-eol",children:"reached End-of-Life"}),", and Docusaurus v3 now requires ",(0,o.jsx)(n.strong,{children:"Node.js >= 18.0"}),"."]}),"\n",(0,o.jsx)(n.admonition,{title:"How to prepare",type:"tip",children:(0,o.jsx)(n.p,{children:"Upgrade your Docusaurus v2 site to Node.js 18 before upgrading to Docusaurus v3."})}),"\n",(0,o.jsx)(n.h3,{id:"react-180",children:"React 18.0"}),"\n",(0,o.jsxs)(n.p,{children:["Docusaurus v3 now requires ",(0,o.jsx)(n.strong,{children:"React >= 18.0"}),"."]}),"\n",(0,o.jsx)(n.p,{children:"React 18 comes with its own breaking changes that should be relatively easy to handle, depending on the amount of custom React code you created for your site."}),"\n",(0,o.jsx)(n.p,{children:"Simple Docusaurus sites that only use our official theme code without swizzling do not have anything to do."}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsxs)(n.p,{children:["Read the official ",(0,o.jsx)(n.a,{href:"https://react.dev/blog/2022/03/29/react-v18",children:"React v18.0"})," and ",(0,o.jsx)(n.a,{href:"https://react.dev/blog/2022/03/08/react-18-upgrade-guide",children:"How to Upgrade to React 18"}),", and look at your first-party React code to figure out which components might be affected this React 18 upgrade."]}),(0,o.jsx)(n.p,{children:"We recommend to particularly look for:"}),(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"Automatic batching for stateful components"}),"\n",(0,o.jsx)(n.li,{children:"New React hydration errors reported to the console"}),"\n"]})]}),"\n",(0,o.jsx)(n.h3,{id:"typescript-50",children:"TypeScript 5.0"}),"\n",(0,o.jsxs)(n.p,{children:["Docusaurus v3 now requires ",(0,o.jsx)(n.strong,{children:"TypeScript >= 5.0"}),"."]}),"\n",(0,o.jsx)(n.admonition,{title:"How to prepare",type:"tip",children:(0,o.jsx)(n.p,{children:"Upgrade your Docusaurus v2 site to TypeScript 5 before upgrading to Docusaurus v3."})}),"\n",(0,o.jsx)(n.h3,{id:"typescript-base-config",children:"TypeScript base config"}),"\n",(0,o.jsxs)(n.p,{children:["The official Docusaurus TypeScript config has been re-internalized from the external package ",(0,o.jsx)(n.a,{href:"https://www.npmjs.com/package/@tsconfig/docusaurus",children:(0,o.jsx)(n.code,{children:"@tsconfig/docusaurus"})})," to our new monorepo package ",(0,o.jsx)(n.a,{href:"https://www.npmjs.com/package/@docusaurus/tsconfig",children:(0,o.jsx)(n.code,{children:"@docusaurus/tsconfig"})}),"."]}),"\n",(0,o.jsx)(n.p,{children:"This new package is versioned alongside all the other Docusaurus core packages, and will be used to ensure TypeScript retro-compatibility and breaking changes on major version upgrades."}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsx)(n.p,{children:"The new Docusaurus v3 TypeScript config is sensibly the same as the former Docusaurus v2 TypeScript config. If you upgraded to TypeScript 5, using the Docusaurus v3 config on a v2 site is already possible:"}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-diff",metastring:'title="package.json"',children:' {\n "devDependencies": {\n- "@tsconfig/docusaurus": "^1.0.7",\n+ "@docusaurus/tsconfig": "^3.0.0-beta.0",\n }\n }\n'})}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-diff",metastring:'title="tsconfig.json"',children:' {\n- "extends": "@tsconfig/docusaurus/tsconfig.json",\n+ "extends": "@docusaurus/tsconfig",\n "compilerOptions": {\n "baseUrl": "."\n }\n }\n'})})]}),"\n",(0,o.jsx)(n.h3,{id:"admonition-warning",children:"Admonition warning"}),"\n",(0,o.jsxs)(n.p,{children:["For historical reasons, we support an undocumented admonition ",(0,o.jsx)(n.code,{children:":::warning"})," that renders with a red color."]}),"\n",(0,o.jsx)(n.admonition,{title:"Warning",type:"danger",children:(0,o.jsxs)(n.p,{children:["This is a Docusaurus v2 ",(0,o.jsx)(n.code,{children:":::warning"})," admonition."]})}),"\n",(0,o.jsxs)(n.p,{children:["However, the color and icon is historically wrong. Docusaurus v3 re-introduces ",(0,o.jsx)(n.code,{children:":::warning"})," admonition officially, documents it, and fix the color and icon."]}),"\n",(0,o.jsx)(n.admonition,{type:"warning",children:(0,o.jsxs)(n.p,{children:["This is a Docusaurus v3 ",(0,o.jsx)(n.code,{children:":::warning"})," admonition."]})}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsxs)(n.p,{children:["If you previously used the undocumented ",(0,o.jsx)(n.code,{children:":::warning"})," admonition, make sure to verify for each usage if yellow is now an appropriate color. If you want to keep the red color, use ",(0,o.jsx)(n.code,{children:":::danger"})," instead."]}),(0,o.jsxs)(n.p,{children:["Docusaurus v3 also ",(0,o.jsxs)(n.a,{href:"https://github.com/facebook/docusaurus/pull/9308",children:["deprecated the ",(0,o.jsx)(n.code,{children:":::caution"})]})," admonition. Please refactor ",(0,o.jsx)(n.code,{children:":::caution"})," (yellow) to either ",(0,o.jsx)(n.code,{children:":::warning"})," (yellow) or ",(0,o.jsx)(n.code,{children:":::danger"})," (red)."]})]}),"\n",(0,o.jsx)(n.h3,{id:"versioned-sidebars",children:"Versioned sidebars"}),"\n",(0,o.jsxs)(n.p,{children:["This breaking change will only affect ",(0,o.jsx)(n.strong,{children:"Docusaurus v2 early adopters"})," who versioned their docs before ",(0,o.jsx)(n.code,{children:"v2.0.0-beta.10"})," (December 2021)."]}),"\n",(0,o.jsxs)(n.p,{children:["When creating version ",(0,o.jsx)(n.code,{children:"v1.0.0"}),", the sidebar file contained a prefix ",(0,o.jsx)(n.code,{children:"version-v1.0.0/"})," that ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/pull/9310",children:"Docusaurus v3 does not support anymore"}),"."]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-json",metastring:'title="versioned_sidebars/version-v1.0.0-sidebars.json"',children:'{\n "version-v1.0.0/docs": [\n "version-v1.0.0/introduction",\n "version-v1.0.0/prerequisites"\n ]\n}\n'})}),"\n",(0,o.jsxs)(n.admonition,{title:"How to prepare",type:"tip",children:[(0,o.jsx)(n.p,{children:"Your Docusaurus v2 site is able to handle the 2 sidebar formats similarly."}),(0,o.jsx)(n.p,{children:"You can remove the useless versioned prefix from your versioned sidebars."}),(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-json",metastring:'title="versioned_sidebars/version-v1.0.0-sidebars.json"',children:'{\n "docs": ["introduction", "prerequisites"]\n}\n'})})]}),"\n",(0,o.jsx)(n.h2,{id:"try-docusaurus-v3-today",children:"Try Docusaurus v3 today"}),"\n",(0,o.jsxs)(n.p,{children:["Docusaurus v3 is now ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9312",children:"in beta"}),", and already used in production by ",(0,o.jsx)(n.a,{href:"https://reactnative.dev",children:"React-Native"}),", ",(0,o.jsx)(n.a,{href:"https://jestjs.io",children:"Jest"}),", and ",(0,o.jsx)(n.a,{href:"https://docusaurus.io/",children:"our own website"}),"."]}),"\n",(0,o.jsxs)(n.p,{children:["We think this new Docusaurus version is ",(0,o.jsx)(n.strong,{children:"robust and ready to be deployed in production"}),". It should be released officially soon, after receiving a positive feedback from early adopters of our community."]}),"\n",(0,o.jsxs)(n.p,{children:["We would really appreciate it if you try upgrading and report issues on the ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9312",children:"3.0.0-beta.0 release discussion thread"}),"."]}),"\n",(0,o.jsx)(n.p,{children:"For most sites, the upgrade should be easy. If you prepared your site ahead of time as documented here, upgrading the following dependencies should be enough:"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-diff",metastring:'title="package.json"',children:' {\n "dependencies": {\n- "@docusaurus/core": "2.4.3",\n- "@docusaurus/preset-classic": "2.4.3",\n- "@mdx-js/react": "^1.6.22",\n+ "@docusaurus/core": "3.0.0-beta.0",\n+ "@docusaurus/preset-classic": "3.0.0-beta.0",\n+ "@mdx-js/react": "^3.0.0",\n "clsx": "^2.0.0",\n "prism-react-renderer": "^1.3.5",\n- "react": "^17.0.2",\n- "react-dom": "^17.0.2"\n+ "react": "^18.2.0",\n+ "react-dom": "^18.2.0"\n },\n "devDependencies": {\n- "@docusaurus/module-type-aliases": "2.4.3"\n+ "@docusaurus/module-type-aliases": "3.0.0-beta.0"\n }\n }\n'})}),"\n",(0,o.jsx)(n.h2,{id:"ask-for-help",children:"Ask for help"}),"\n",(0,o.jsx)(n.p,{children:"We will be there to help you upgrade through the following support channels:"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9336",children:"Docusaurus v3 - Upgrade Support"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://discord.com/channels/398180168688074762/1154771869094912090",children:"Docusaurus v3 - Discord channel #migration-v2-to-v3"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9053",children:"MDX v3 - Upgrade Support"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9337",children:"MDX v3 - Remark/Rehype Plugins Support"})}),"\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"https://discord.com/channels/398180168688074762/1116724556976111616",children:"MDX v3 - Discord channel #migration-mdx-v3"})}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["Alternatively, you can look for a paid ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9281",children:"Docusaurus Service Provider"})," to execute this upgrade for you. If your site is open source, you can also ask our community for ",(0,o.jsx)(n.a,{href:"https://github.com/facebook/docusaurus/discussions/9283",children:"free, benevolent help"}),"."]}),"\n",(0,o.jsx)(n.h2,{id:"conclusion",children:"Conclusion"}),"\n",(0,o.jsx)(n.p,{children:"Docusaurus v3 is ready to try, and will be released soon. This article already gives you a good idea of all the major changes required to upgrade."}),"\n",(0,o.jsx)(n.p,{children:"The initial 3.0 release is focusing on dependency and infrastructure upgrades that will permit us to implement new exciting features. It also comes with a few useful features that we will detail in the final release notes."})]})}function h(e={}){let{wrapper:n}={...(0,i.a)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(l,{...e})}):l(e)}},80980:function(e,n,s){s.d(n,{Z:()=>a,a:()=>t});var r=s(67294);let o={},i=r.createContext(o);function t(e){let n=r.useContext(i);return r.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:t(e.components),r.createElement(i.Provider,{value:n},e.children)}},24174:function(e){e.exports=JSON.parse('{"permalink":"/blog/preparing-your-site-for-docusaurus-v3","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2023/09-29-preparing-your-site-for-docusaurus-v3/index.mdx","source":"@site/blog/2023/09-29-preparing-your-site-for-docusaurus-v3/index.mdx","title":"Preparing your site for Docusaurus v3","description":"This blog post was written when Docusaurus v3 was in beta. There are some changes in dependency versions and upgrade steps you should be aware of if upgrading to Docusaurus v3 current stable releases. Use the upgrade guide for the most up-to-date migration steps.","date":"2023-09-29T00:00:00.000Z","tags":[{"inline":false,"label":"Maintenance","permalink":"/blog/tags/maintenance"}],"readingTime":13.975,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Preparing your site for Docusaurus v3","authors":["slorber"],"tags":["maintenance"],"slug":"/preparing-your-site-for-docusaurus-v3","image":"./img/social-card.png"},"unlisted":false,"lastUpdatedAt":1743765771000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Announcing Docusaurus 3.0","permalink":"/blog/releases/3.0"},"nextItem":{"title":"Upgrading frontend dependencies with confidence","permalink":"/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing"}}')}}]);
\n-