mirror of
https://github.com/facebook/docusaurus.git
synced 2025-12-31 07:32:53 +00:00
334 lines
209 KiB
HTML
334 lines
209 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-migration/v3" data-has-hydrated="false">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v3.2.1">
|
||
<title data-rh="true">Upgrading to Docusaurus v3 | Docusaurus</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://docusaurus.io/img/docusaurus-social-card.jpg"><meta data-rh="true" name="twitter:image" content="https://docusaurus.io/img/docusaurus-social-card.jpg"><meta data-rh="true" property="og:url" content="https://docusaurus.io/docs/migration/v3"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" property="og:locale:alternate" content="fr"><meta data-rh="true" property="og:locale:alternate" content="pt_BR"><meta data-rh="true" property="og:locale:alternate" content="ko"><meta data-rh="true" property="og:locale:alternate" content="zh_CN"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Upgrading to Docusaurus v3 | Docusaurus"><meta data-rh="true" name="description" content="This documentation will help you upgrade your site from Docusaurus v2 to Docusaurus v3."><meta data-rh="true" property="og:description" content="This documentation will help you upgrade your site from Docusaurus v2 to Docusaurus v3."><link data-rh="true" rel="icon" href="/img/docusaurus.ico"><link data-rh="true" rel="canonical" href="https://docusaurus.io/docs/migration/v3"><link data-rh="true" rel="alternate" href="https://docusaurus.io/docs/migration/v3" hreflang="en"><link data-rh="true" rel="alternate" href="https://docusaurus.io/fr/docs/migration/v3" hreflang="fr"><link data-rh="true" rel="alternate" href="https://docusaurus.io/pt-BR/docs/migration/v3" hreflang="pt-BR"><link data-rh="true" rel="alternate" href="https://docusaurus.io/ko/docs/migration/v3" hreflang="ko"><link data-rh="true" rel="alternate" href="https://docusaurus.io/zh-CN/docs/migration/v3" hreflang="zh-CN"><link data-rh="true" rel="alternate" href="https://docusaurus.io/docs/migration/v3" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://X1Z85QJPUV-dsn.algolia.net" crossorigin="anonymous"><link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="Docusaurus RSS Feed">
|
||
<link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="Docusaurus Atom Feed">
|
||
<link rel="alternate" type="application/json" href="/blog/feed.json" title="Docusaurus JSON Feed">
|
||
|
||
|
||
<link rel="preconnect" href="https://www.google-analytics.com">
|
||
<link rel="preconnect" href="https://www.googletagmanager.com">
|
||
<script async src="https://www.googletagmanager.com/gtag/js?id=G-E5CR2Q1NRE"></script>
|
||
<script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","G-E5CR2Q1NRE",{})</script>
|
||
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml" title="Docusaurus" href="/opensearch.xml">
|
||
<link rel="alternate" type="application/rss+xml" href="/changelog/rss.xml" title="Docusaurus changelog RSS Feed">
|
||
<link rel="alternate" type="application/atom+xml" href="/changelog/atom.xml" title="Docusaurus changelog Atom Feed">
|
||
<link rel="alternate" type="application/json" href="/changelog/feed.json" title="Docusaurus changelog JSON Feed">
|
||
|
||
|
||
|
||
<link rel="icon" href="/img/docusaurus.png">
|
||
<link rel="manifest" href="/manifest.json">
|
||
<meta name="theme-color" content="rgb(37, 194, 160)">
|
||
<meta name="apple-mobile-web-app-capable" content="yes">
|
||
<meta name="apple-mobile-web-app-status-bar-style" content="#000">
|
||
<link rel="apple-touch-icon" href="/img/docusaurus.png">
|
||
<link rel="mask-icon" href="/img/docusaurus.png" color="rgb(62, 204, 94)">
|
||
<meta name="msapplication-TileImage" content="/img/docusaurus.png">
|
||
<meta name="msapplication-TileColor" content="#000">
|
||
|
||
|
||
|
||
<link rel="alternate" type="application/rss+xml" href="/tests/blog/rss.xml" title="Docusaurus Tests Blog RSS Feed">
|
||
<link rel="alternate" type="application/atom+xml" href="/tests/blog/atom.xml" title="Docusaurus Tests Blog Atom Feed">
|
||
<link rel="alternate" type="application/json" href="/tests/blog/feed.json" title="Docusaurus Tests Blog JSON Feed">
|
||
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="/katex/katex.min.css"><link rel="stylesheet" href="/assets/css/styles.76313542.css">
|
||
<script src="/assets/js/runtime~main.e1b4125a.js" defer="defer"></script>
|
||
<script src="/assets/js/main.5c3bbcf1.js" defer="defer"></script>
|
||
</head>
|
||
<body class="navigation-with-keyboard">
|
||
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return localStorage.getItem("theme")}catch(t){}}();null!==e?t(e):window.matchMedia("(prefers-color-scheme: dark)").matches?t("dark"):(window.matchMedia("(prefers-color-scheme: light)").matches,t("light"))}(),function(){try{const n=new URLSearchParams(window.location.search).entries();for(var[t,e]of n)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}(),document.documentElement.setAttribute("data-announcement-bar-initially-dismissed",function(){try{return"true"===localStorage.getItem("docusaurus.announcement.dismiss")}catch(t){}return!1}())</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_UHvc" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><div class="announcementBar_cTOO" role="banner"><div class="announcementBarPlaceholder_Lqfg"></div><div class="content_ttnW announcementBarContent_PjqA">🎉️ <b><a target="_blank" href="https://docusaurus.io/blog/releases/3.2">Docusaurus v3.2</a> is out!</b> 🥳️</div><button type="button" aria-label="Close" class="clean-btn close closeButton_nmpN announcementBarClose_UFLi"><svg viewBox="0 0 15 15" width="14" height="14"><g stroke="currentColor" stroke-width="3.1"><path d="M.75.75l13.5 13.5M14.25.75L.75 14.25"></path></g></svg></button></div><nav aria-label="Main" class="navbar navbar--fixed-top navbarHideable_uAgx"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/docusaurus.svg" alt="" class="themedComponent_bJGS themedComponent--light_LEkC" height="32" width="32"><img src="/img/docusaurus_keytar.svg" alt="" class="themedComponent_bJGS themedComponent--dark_jnGk" height="32" width="32"></div><b class="navbar__title text--truncate">Docusaurus</b></a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs">Docs</a><a class="navbar__item navbar__link" href="/docs/cli">API</a><a class="navbar__item navbar__link" href="/blog">Blog</a><a class="navbar__item navbar__link" href="/showcase">Showcase</a><a class="navbar__item navbar__link" href="/community/support">Community</a></div><div class="navbar__items navbar__items--right"><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a class="navbar__link" aria-haspopup="true" aria-expanded="false" role="button" href="/docs">Canary 🚧</a><ul class="dropdown__menu"><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/docs/migration/v3">Canary 🚧</a></li><li><hr class="dropdown-separator"></li><li class="dropdown-archived-versions"><b>Archived versions</b></li><li><a href="https://docusaurus-archive-october-2023.netlify.app/docs/2.3.1" target="_blank" rel="noopener noreferrer" class="dropdown__link">2.3.1<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://docusaurus-archive-october-2023.netlify.app/docs/2.2.0" target="_blank" rel="noopener noreferrer" class="dropdown__link">2.2.0<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://docusaurus-archive-october-2023.netlify.app/docs/2.1.0" target="_blank" rel="noopener noreferrer" class="dropdown__link">2.1.0<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://docusaurus-archive-october-2023.netlify.app/docs/2.0.1" target="_blank" rel="noopener noreferrer" class="dropdown__link">2.0.1<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://v1.docusaurus.io" target="_blank" rel="noopener noreferrer" class="dropdown__link">1.x.x<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><hr class="dropdown-separator"></li><li><a class="dropdown__link" href="/versions">All versions</a></li></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link"><svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" class="iconLanguage_tqOs"><path fill="currentColor" d="M12.87 15.07l-2.54-2.51.03-.03c1.74-1.94 2.98-4.17 3.71-6.53H17V4h-7V2H8v2H1v1.99h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"></path></svg>English</a><ul class="dropdown__menu"><li><a href="/docs/migration/v3" target="_self" rel="noopener noreferrer" class="dropdown__link dropdown__link--active" lang="en">English</a></li><li><a href="/fr/docs/migration/v3" target="_self" rel="noopener noreferrer" class="dropdown__link" lang="fr">Français</a></li><li><a href="/pt-BR/docs/migration/v3" target="_self" rel="noopener noreferrer" class="dropdown__link" lang="pt-BR">Português (Brasil)</a></li><li><a href="/ko/docs/migration/v3" target="_self" rel="noopener noreferrer" class="dropdown__link" lang="ko">한국어</a></li><li><a href="/zh-CN/docs/migration/v3" target="_self" rel="noopener noreferrer" class="dropdown__link" lang="zh-CN">中文（中国）</a></li><li><hr style="margin: 0.3rem 0;"></li><li><a href="https://github.com/facebook/docusaurus/issues/3526" target="_blank" rel="noopener noreferrer" class="dropdown__link">Help Us Translate<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><a href="https://github.com/facebook/docusaurus" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link header-github-link" aria-label="GitHub repository"></a><div class="toggle_bT41 colorModeToggle_UolE"><button class="clean-btn toggleButton_x9TT toggleButtonDisabled_Dj8q" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_dnYY"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_OBbf"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="navbarSearchContainer_dDCC"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_PEsc"><div class="docsWrapper_lLmf"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_PuQw" type="button"></button><div class="docRoot_kBZ6"><aside class="theme-doc-sidebar-container docSidebarContainer_S51O"><div class="sidebarViewport_K3q9"><div class="sidebar_vtcw sidebarWithHideableNavbar_tZ9s"><a tabindex="-1" class="sidebarLogo_UK0N" href="/"><img src="/img/docusaurus.svg" alt="" class="themedComponent_bJGS themedComponent--light_LEkC" height="32" width="32"><img src="/img/docusaurus_keytar.svg" alt="" class="themedComponent_bJGS themedComponent--dark_jnGk" height="32" width="32"><b>Docusaurus</b></a><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_rWGR menuWithAnnouncementBar_Pf08"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs">Introduction</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/category/getting-started">Getting Started</a><button aria-label="Collapse sidebar category 'Getting Started'" aria-expanded="true" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/installation">Installation</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/configuration">Configuration</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/playground">Playground</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/typescript-support">TypeScript Support</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/category/guides">Guides</a><button aria-label="Expand sidebar category 'Guides'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/advanced">Advanced Guides</a><button aria-label="Expand sidebar category 'Advanced Guides'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--active" href="/docs/migration">Upgrading</a><button aria-label="Collapse sidebar category 'Upgrading'" aria-expanded="true" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/migration/v3">To Docusaurus v3</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" tabindex="0" href="/docs/migration/v2">To Docusaurus v2</a></div></li></ul></li></ul></nav><button type="button" title="Collapse sidebar" aria-label="Collapse sidebar" class="button button--secondary button--outline collapseSidebarButton_PUyN"><svg width="20" height="20" aria-hidden="true" class="collapseSidebarButtonIcon_DI0B"><g fill="#7a7a7a"><path d="M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0"></path><path d="M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0"></path></g></svg></button></div></div></aside><main class="docMainContainer_EfwR"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_n6xZ"><div class="docItemContainer_RhpI"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Wvrh" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_uaSn"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item"><a class="breadcrumbs__link" itemprop="item" href="/docs/migration"><span itemprop="name">Upgrading</span></a><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">To Docusaurus v3</span><meta itemprop="position" content="2"></li></ul></nav><div class="tocCollapsible_BEWm theme-doc-toc-mobile tocMobile_NSfz"><button type="button" class="clean-btn tocCollapsibleButton_IbtT">On this page</button></div><div class="theme-doc-markdown markdown"><h1>Upgrading to Docusaurus v3</h1>
|
||
<p>This documentation will help you upgrade your site from Docusaurus v2 to Docusaurus v3.</p>
|
||
<p>Docusaurus v3 is a new <strong>major version</strong>, including <strong>breaking changes</strong> requiring you to adjust your site accordingly. We will guide to during this process, and also mention a few optional recommendations.</p>
|
||
<p>This is not a full rewrite, and the breaking changes are relatively easy to handle. The simplest sites will eventually upgrade by simply updating their npm dependencies.</p>
|
||
<p>The main breaking change is the upgrade from MDX v1 to MDX v3. Read the <a href="https://mdxjs.com/blog/v2/" target="_blank" rel="noopener noreferrer"><strong>MDX v2</strong></a> and <a href="https://mdxjs.com/blog/v3/" target="_blank" rel="noopener noreferrer"><strong>MDX v3</strong></a> release notes for details. MDX will now compile your Markdown content <strong>more strictly</strong> and with <strong>subtle differences</strong>.</p>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>Before upgrading</div><div class="admonitionContent_Knsx"><p>Before upgrading, we recommend <a href="/blog/preparing-your-site-for-docusaurus-v3"><strong>preparing your site for Docusaurus v3</strong></a>. There are changes that you can already <strong>handle incrementally, under Docusaurus v2</strong>. Doing so will help reduce the work needed to finally upgrade to Docusaurus v3.</p><p>For complex sites, we also recommend to set up <a href="/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing"><strong>visual regression tests</strong></a>, a good way to ensure your site stays visually identical. Docusaurus v3 mainly upgrades dependencies, and is not expected to produce any visual changes.</p></div></div>
|
||
<div class="theme-admonition theme-admonition-note admonition_o5H7 alert alert--secondary"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_Knsx"><p>Check the release notes for <a href="https://github.com/facebook/docusaurus/releases/tag/v3.0.0" target="_blank" rel="noopener noreferrer"><strong>Docusaurus v3.0.0</strong></a>, and browse the pull-requests for additional useful information and the motivation behind each change mentioned here.</p></div></div>
|
||
<h2 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="upgrading-dependencies">Upgrading Dependencies<a href="#upgrading-dependencies" class="hash-link" aria-label="Direct link to Upgrading Dependencies" title="Direct link to Upgrading Dependencies"></a></h2>
|
||
<p>Upgrading to Docusaurus v3 requires upgrading core Docusaurus dependencies (<code>@docusaurus/name</code>), but also other related packages.</p>
|
||
<p>Docusaurus v3 now uses the following dependencies:</p>
|
||
<ul>
|
||
<li>Node.js v18.0+</li>
|
||
<li>React v18.0+</li>
|
||
<li>MDX v3.0+</li>
|
||
<li>TypeScript v5.0+</li>
|
||
<li>prism-react-renderer v2.0+</li>
|
||
<li>react-live v4.0+</li>
|
||
<li>remark-emoji v4.0+</li>
|
||
<li>mermaid v10.4+</li>
|
||
</ul>
|
||
<div class="theme-admonition theme-admonition-warning admonition_o5H7 alert alert--warning"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>Upgrading community plugins</div><div class="admonitionContent_Knsx"><p>If your site uses third-party community plugins and themes, you might need to upgrade them.</p><p>Make sure those plugins are compatible with Docusaurus v3 before attempting an upgrade.</p></div></div>
|
||
<p>A typical <code>package.json</code> dependency upgrade example:</p>
|
||
<div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">package.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "dependencies": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // upgrade to Docusaurus v3</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "@docusaurus/core": "2.4.3",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "@docusaurus/preset-classic": "2.4.3",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "@docusaurus/core": "3.0.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "@docusaurus/preset-classic": "3.0.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // upgrade to MDX v3</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "@mdx-js/react": "^1.6.22",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "@mdx-js/react": "^3.0.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // upgrade to prism-react-renderer v2.0+</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "prism-react-renderer": "^1.3.5",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "prism-react-renderer": "^2.1.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // upgrade to React v18.0+</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "react": "^17.0.2",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "react-dom": "^17.0.2"</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "react": "^18.2.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "react-dom": "^18.2.0"</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> },</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "devDependencies": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // upgrade Docusaurus dev dependencies to v3</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "@docusaurus/module-type-aliases": "2.4.3",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "@docusaurus/types": "2.4.3"</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "@docusaurus/module-type-aliases": "3.0.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "@docusaurus/types": "3.0.0"</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "engines": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // require Node.js 18.0+</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "node": ">=16.14"</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "node": ">=18.0"</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<p>For TypeScript users:</p>
|
||
<div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">package.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "devDependencies": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // swap the external TypeScript config package for the new official one</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "@tsconfig/docusaurus": "^1.0.7",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "@docusaurus/tsconfig": "3.0.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // upgrade React types to v18.0+</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "@types/react": "^17.0.69",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "@types/react": "^18.2.29",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> // upgrade TypeScript to v5.0+</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "typescript": "~4.7.4"</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "typescript": "~5.2.2"</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<h2 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="upgrading-mdx">Upgrading MDX<a href="#upgrading-mdx" class="hash-link" aria-label="Direct link to Upgrading MDX" title="Direct link to Upgrading MDX"></a></h2>
|
||
<p>MDX is a major dependency of Docusaurus responsible for compiling your <code>.md</code> and <code>.mdx</code> files to React components.</p>
|
||
<p>The transition from MDX v1 to MDX v3 is the <strong>main challenge</strong> to the adoption of Docusaurus v3. Most breaking changes come from MDX v2, and MDX v3 is a relatively small release.</p>
|
||
<p>Some documents that compiled successfully under Docusaurus v2 might now <strong>fail to compile</strong> under Docusaurus v3.</p>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>Find problematic content ahead of time</div><div class="admonitionContent_Knsx"><p>Run <a href="https://github.com/slorber/docusaurus-mdx-checker" target="_blank" rel="noopener noreferrer"><code>npx docusaurus-mdx-checker</code></a> on your site to get a list of files that will now fail to compile under Docusaurus v3.</p><p>This command is also a good way to estimate the amount of work to be done to make your content compatible. Remember most of this work can be executed ahead of the upgrade by <a href="/blog/preparing-your-site-for-docusaurus-v3">preparing your content for Docusaurus v3</a>.</p></div></div>
|
||
<p>Other documents might also <strong>render differently</strong>.</p>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>Use visual regression tests</div><div class="admonitionContent_Knsx"><p>For large sites where a manual review of all pages is complicated, we recommend you to setup <a href="https://docusaurus.io/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing" target="_blank" rel="noopener noreferrer">visual regression tests</a>.</p></div></div>
|
||
<p>Upgrading MDX comes with all the breaking changes documented on the <a href="https://mdxjs.com/blog/v2/" target="_blank" rel="noopener noreferrer">MDX v2</a> and <a href="https://mdxjs.com/blog/v3/" target="_blank" rel="noopener noreferrer">MDX v3</a> release blog posts. Most breaking changes come from MDX v2, and MDX v3 is a relatively small release. The <a href="https://mdxjs.com/migrating/v2/" target="_blank" rel="noopener noreferrer">MDX v2 migration guide</a> has a section on how to <a href="https://mdxjs.com/migrating/v2/#update-mdx-files" target="_blank" rel="noopener noreferrer">update MDX files</a> that will be particularly relevant to us. Also make sure to read the <a href="https://mdxjs.com/docs/troubleshooting-mdx/" target="_blank" rel="noopener noreferrer">Troubleshooting MDX</a> page that can help you interpret common MDX error messages.</p>
|
||
<p>Make sure to also read our updated <a href="/docs/markdown-features/react"><strong>MDX and React</strong></a> documentation page.</p>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="using-the-mdx-playground">Using the MDX playground<a href="#using-the-mdx-playground" class="hash-link" aria-label="Direct link to Using the MDX playground" title="Direct link to Using the MDX playground"></a></h3>
|
||
<p>The MDX playground is your new best friend. It permits to understand how your content is <strong>compiled to React components</strong>, and troubleshoot compilation or rendering issues in isolation.</p>
|
||
<ul>
|
||
<li><a href="https://mdxjs.com/playground/" target="_blank" rel="noopener noreferrer">MDX playground - current version</a></li>
|
||
<li><a href="https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground/" target="_blank" rel="noopener noreferrer">MDX playground - v1</a></li>
|
||
</ul>
|
||
<details class="details_Nokh alert alert--info details_Cn_P" data-collapsed="true"><summary>Configuring the MDX playground options for Docusaurus</summary><div><div class="collapsibleContent_EoA1"><p>To obtain a compilation behavior similar to what Docusaurus v2 uses, please turn on these options on the <a href="https://mdxjs.com/playground/" target="_blank" rel="noopener noreferrer">MDX playground</a>:</p><ul>
|
||
<li>Use <code>MDX</code></li>
|
||
<li>Use <code>remark-gfm</code></li>
|
||
<li>Use <code>remark-directive</code></li>
|
||
</ul><p><img decoding="async" loading="lazy" alt="Screenshot of the MDX playground&#39;s options panel, with only the &quot;Use MDX&quot;, &quot;Use remark-gfm&quot;, and &quot;Use remark-directive&quot; options checked" src="/assets/images/mdx2-playground-options-eab88e8328a6902759c4236ffc93d9c6.png" width="1968" height="1316" class="img_vXGZ"></p></div></div></details>
|
||
<p>Using the two MDX playgrounds side-by-side, you will soon notice that some content is compiled differently or fails to compile in v2.</p>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>Making your content future-proof</div><div class="admonitionContent_Knsx"><p>The goal will be to refactor your problematic content so that it <strong>works fine with both versions of MDX</strong>. This way, when you upgrade to Docusaurus v3, this content will already work out-of-the-box.</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="using-the-mdx-checker-cli">Using the MDX checker CLI<a href="#using-the-mdx-checker-cli" class="hash-link" aria-label="Direct link to Using the MDX checker CLI" title="Direct link to Using the MDX checker CLI"></a></h3>
|
||
<p>We provide a <a href="https://github.com/slorber/docusaurus-mdx-checker" target="_blank" rel="noopener noreferrer">docusaurus-mdx-checker</a> CLI that permits to easily spot problematic content. Run this command on your site to obtain a list of files that will fail to compile under MDX v3.</p>
|
||
<div class="language-bash codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-bash codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">npx docusaurus-mdx-checker</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<p>For each compilation issue, the CLI will log the file path and a line number to look at.</p>
|
||
<p><img decoding="async" loading="lazy" alt="Screenshot of the terminal showing an example MDX checker CLI output, with a few error messages" src="/assets/images/mdx-checker-output-0f96cc19fd3ed4d55901ca90ad657c14.png" width="1161" height="417" class="img_vXGZ"></p>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_Knsx"><p>Use this CLI to estimate of how much work will be required to make your content compatible with MDX v3.</p></div></div>
|
||
<div class="theme-admonition theme-admonition-warning admonition_o5H7 alert alert--warning"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>warning</div><div class="admonitionContent_Knsx"><p>This CLI is a best effort, and will <strong>only report compilation errors</strong>.</p><p>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 <a href="/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing">visual regression tests</a>.</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="common-mdx-problems">Common MDX problems<a href="#common-mdx-problems" class="hash-link" aria-label="Direct link to Common MDX problems" title="Direct link to Common MDX problems"></a></h3>
|
||
<p>Docusaurus cannot document exhaustively all the changes coming with MDX. That's the responsibility of the <a href="https://mdxjs.com/migrating/v2/" target="_blank" rel="noopener noreferrer">MDX v2</a> and <a href="https://mdxjs.com/migrating/v3/" target="_blank" rel="noopener noreferrer">MDX v3</a> migration guides.</p>
|
||
<p>However, by upgrading a few Docusaurus sites, we noticed that most of the issues come down to only a few cases that we have documented for you.</p>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="bad-usage-of-">Bad usage of <code>{</code><a href="#bad-usage-of-" class="hash-link" aria-label="Direct link to bad-usage-of-" title="Direct link to bad-usage-of-"></a></h4>
|
||
<p>The <code>{</code> character is used for opening <a href="https://mdxjs.com/docs/what-is-mdx/#expressions" target="_blank" rel="noopener noreferrer">JavaScript expressions</a>. MDX will now fail if what you put inside <code>{expression}</code> is not a valid expression.</p>
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">The object shape looks like {username: string, age: number}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>Error message</div><div class="admonitionContent_Knsx"><blockquote>
|
||
<p>Could not parse expression with acorn: Unexpected content after expression</p>
|
||
</blockquote></div></div>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Available options to fix this error:</p><ul>
|
||
<li>Use inline code: <code>{username: string, age: number}</code></li>
|
||
<li>Use the HTML code: <code>&#123;</code></li>
|
||
<li>Escape it: <code>\{</code></li>
|
||
</ul></div></div>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="bad-usage-of--1">Bad usage of <code><</code><a href="#bad-usage-of--1" class="hash-link" aria-label="Direct link to bad-usage-of--1" title="Direct link to bad-usage-of--1"></a></h4>
|
||
<p>The <code><</code> character is used for opening <a href="https://mdxjs.com/docs/what-is-mdx/#jsx" target="_blank" rel="noopener noreferrer">JSX tags</a>. MDX will now fail if it thinks your JSX is invalid.</p>
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">Use Android version <5</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">You can use a generic type like Array</span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">T</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Follow the template "Road to </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">YOUR_MINOR_VERSION</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain">"</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>Error messages</div><div class="admonitionContent_Knsx"><blockquote>
|
||
<p>Unexpected character <code>5</code> (U+0035) before name, expected a character that can start a name, such as a letter, <code>$</code>, or <code>_</code></p>
|
||
</blockquote><blockquote>
|
||
<p>Expected a closing tag for <code><T></code> (1:6-1:9) before the end of <code>paragraph</code> end-tag-mismatch mdast-util-mdx-jsx</p>
|
||
</blockquote><blockquote>
|
||
<p>Expected a closing tag for <code><YOUR_MINOR_VERSION></code> (134:19-134:39) before the end of <code>paragraph</code></p>
|
||
</blockquote></div></div>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Available options to fix this error:</p><ul>
|
||
<li>Use inline code: <code>Array<T></code></li>
|
||
<li>Use the HTML code: <code>&lt;</code> or <code>&#60;</code></li>
|
||
<li>Escape it: <code>\<</code></li>
|
||
</ul></div></div>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="bad-usage-of-gfm-autolink">Bad usage of GFM Autolink<a href="#bad-usage-of-gfm-autolink" class="hash-link" aria-label="Direct link to Bad usage of GFM Autolink" title="Direct link to Bad usage of GFM Autolink"></a></h4>
|
||
<p>Docusaurus supports <a href="https://github.github.com/gfm/" target="_blank" rel="noopener noreferrer">GitHub Flavored Markdown (GFM)</a>, but <a href="https://github.github.com/gfm/#autolinks" target="_blank" rel="noopener noreferrer">autolink</a> using the <code><link></code> syntax is not supported anymore by MDX.</p>
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">sebastien@thisweekinreact.com</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"><http://localhost:3000></span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>Error messages</div><div class="admonitionContent_Knsx"><blockquote>
|
||
<p>Unexpected character <code>@</code> (U+0040) in name, expected a name character such as letters, digits, <code>$</code>, or <code>_</code>; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use <code>[text](url)</code>)</p>
|
||
</blockquote><blockquote>
|
||
<p>Unexpected character <code>/</code> (U+002F) before local name, expected a character that can start a name, such as a letter, <code>$</code>, or <code>_</code> (note: to create a link in MDX, use <code>[text](url)</code>)</p>
|
||
</blockquote></div></div>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Use regular Markdown links, or remove the <code><</code> and <code>></code>. MDX and GFM are able to autolink literals already.</p><div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">sebastien@thisweekinreact.com</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token url" style="color:#36acaa">[</span><span class="token url content" style="color:#36acaa">sebastien@thisweekinreact.com</span><span class="token url" style="color:#36acaa">](</span><span class="token url" style="color:#36acaa">mailto:sebastien@thisweekinreact.com</span><span class="token url" style="color:#36acaa">)</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">http://localhost:3000</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token url" style="color:#36acaa">[</span><span class="token url content" style="color:#36acaa">http://localhost:3000</span><span class="token url" style="color:#36acaa">](</span><span class="token url" style="color:#36acaa">http://localhost:3000</span><span class="token url" style="color:#36acaa">)</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="lower-case-mdxcomponent-mapping">Lower-case MDXComponent mapping<a href="#lower-case-mdxcomponent-mapping" class="hash-link" aria-label="Direct link to Lower-case MDXComponent mapping" title="Direct link to Lower-case MDXComponent mapping"></a></h4>
|
||
<p>For users providing a <a href="/docs/markdown-features/react#mdx-component-scope">custom <code>MDXComponent</code>mapping</a>, components are now "sandboxed":</p>
|
||
<ul>
|
||
<li>a <code>MDXComponent</code> mapping for <code>h1</code> only gets used for <code># hi</code> but not for <code><h1>hi</h1></code></li>
|
||
<li>a <strong>lower-cased</strong> custom element name will not be substituted by its respective <code>MDXComponent</code> component anymore</li>
|
||
</ul>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>visual difference</div><div class="admonitionContent_Knsx"><p>Your <a href="/docs/markdown-features/react#mdx-component-scope"><code>MDXComponent</code> component mapping</a> might not be applied as before, and your custom components might no longer be used.</p></div></div>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>For native Markdown elements, you can keep using <strong>lower-case</strong>: <code>p</code>, <code>h1</code>, <code>img</code>, <code>a</code>...</p><p>For any other element, <strong>use upper-case names</strong>.</p><div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">src/theme/MDXComponents.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">import MDXComponents from '@theme-original/MDXComponents';</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">export default {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> ...MDXComponents,</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> p: (props) => <p {...props} className="my-paragraph"/></span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> myElement: (props) => <div {...props} className="my-class" />,</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> MyElement: (props) => <div {...props} className="my-class" />,</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">};</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="unintended-extra-paragraphs">Unintended extra paragraphs<a href="#unintended-extra-paragraphs" class="hash-link" aria-label="Direct link to Unintended extra paragraphs" title="Direct link to Unintended extra paragraphs"></a></h4>
|
||
<p>In MDX v3, 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 <code><p></code> tags.</p>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>visual difference</div><div class="admonitionContent_Knsx"><p>See how this content is rendered differently by MDX v1 and v3.</p><div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain">Some </span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Markdown</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain"> content</span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> Some </span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Markdown</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain"> content</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><div class="language-html codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">MDX v1 output</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-html codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain">Some **Markdown** content</span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain">Some **Markdown** content</span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><div class="language-html codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">MDX v3 output</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-html codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain">Some </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">strong</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain">Markdown</span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">strong</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"> content</span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">p</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain">Some </span><span class="token tag punctuation" style="color:#393A34"><</span><span class="token tag" style="color:#22863A">strong</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain">Markdown</span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">strong</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token plain"> content</span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">p</span><span class="token tag punctuation" style="color:#393A34">></span><span class="token tag punctuation" style="color:#393A34"></</span><span class="token tag" style="color:#22863A">div</span><span class="token tag punctuation" style="color:#393A34">></span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>If you don't want an extra <code><p></code> tag, refactor content on a case by case basis to use a single-line JSX tag.</p><div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"><figure></span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> <img src="/img/myImage.png" alt="My alt" /></span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> <figcaption></span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> My image caption</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> </figcaption></span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> <figcaption>My image caption</figcaption></span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"></figure></span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="unintended-usage-of-directives">Unintended usage of directives<a href="#unintended-usage-of-directives" class="hash-link" aria-label="Direct link to Unintended usage of directives" title="Direct link to Unintended usage of directives"></a></h4>
|
||
<p>Docusaurus v3 now uses <a href="https://talk.commonmark.org/t/generic-directives-plugins-syntax/444" target="_blank" rel="noopener noreferrer">Markdown Directives</a> (implemented with <a href="https://github.com/remarkjs/remark-directive" target="_blank" rel="noopener noreferrer">remark-directive</a>) as a generic way to provide support for admonitions, and other upcoming Docusaurus features.</p>
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">This is a :textDirective</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">::leafDirective</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">:::containerDirective</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">Container directive content</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">:::</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>Visual change</div><div class="admonitionContent_Knsx"><p>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.</p><div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">The AWS re:Invent conf is great</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Due to <code>:Invent</code> being parsed as a text directive, this will now be rendered as:</p><div class="codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-text codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">The AWS re</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">conf is great</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><ul>
|
||
<li>Use the HTML code: <code>&#58;</code></li>
|
||
<li>Add a space after <code>:</code> (if it makes sense): <code>: text</code></li>
|
||
<li>Escape it: <code>\:</code></li>
|
||
</ul></div></div>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="unsupported-indented-code-blocks">Unsupported indented code blocks<a href="#unsupported-indented-code-blocks" class="hash-link" aria-label="Direct link to Unsupported indented code blocks" title="Direct link to Unsupported indented code blocks"></a></h4>
|
||
<p>MDX does not transform indented text as code blocks anymore.</p>
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain"> console.log("hello");</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>Visual change</div><div class="admonitionContent_Knsx"><p>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.</p></div></div>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Use the regular code block syntax instead of indentation:</p><div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token code punctuation" style="color:#393A34">```</span><span class="token code code-language">js</span><span class="token code"></span><br></span><span class="token-line" style="color:#393A34"><span class="token code"></span><span class="token code code-block language-js">console.log('hello');</span><span class="token code"></span><br></span><span class="token-line" style="color:#393A34"><span class="token code"></span><span class="token code punctuation" style="color:#393A34">```</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="other-markdown-incompatibilities">Other Markdown incompatibilities<a href="#other-markdown-incompatibilities" class="hash-link" aria-label="Direct link to Other Markdown incompatibilities" title="Direct link to Other Markdown incompatibilities"></a></h3>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="emphasis-starting-or-ending-with-a-space-or-a-punctuation">Emphasis starting or ending with a space or a punctuation<a href="#emphasis-starting-or-ending-with-a-space-or-a-punctuation" class="hash-link" aria-label="Direct link to Emphasis starting or ending with a space or a punctuation" title="Direct link to Emphasis starting or ending with a space or a punctuation"></a></h4>
|
||
<p>New MDX parser now strictly complies with the CommonMark spec. CommonMark spec has introduced rules for emphasis around spaces and punctuation, which are incompatible especially with languages that do not use a space to split words, since v0.14.</p>
|
||
<p>Japanese and Chinese are most affected by this, but there are some other languages that can be affected (e.g. Thai and Khmer), for example when you try to emphasize an inline code or a link. Languages that use a space to split words are much less affected.</p>
|
||
<p><code>**</code> (other than <code>`**`</code>) in the following example were parsed as intended in Docusaurus 2, but are not now in Docusaurus 3.</p>
|
||
<!-- -->
|
||
<!-- -->
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">example.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Do not end a range of emphasis with a space. </span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">Or </span><span class="token code-snippet code keyword" style="color:#CF222E">`**`</span><span class="token plain"> will not work as intended.</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token comment" style="color:#6B6B6B;font-style:italic"><!-- Japanese --></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">「。」の後に文を続けると`</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">`が意図した動作をしません。</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">また、</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token url" style="color:#36acaa">[</span><span class="token url content" style="color:#36acaa">リンク</span><span class="token url" style="color:#36acaa">](</span><span class="token url" style="color:#36acaa">https://docusaurus.io/</span><span class="token url" style="color:#36acaa">)</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">や</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token code-snippet code keyword" style="color:#CF222E">`コード`</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">のすぐ外側に`</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">`、そのさらに外側に句読点以外がある場合も同様です。</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<details class="details_Nokh alert alert--info details_Cn_P" data-collapsed="true"><summary>See the detailed conditions and how to upgrade</summary><div><div class="collapsibleContent_EoA1"><p>If <code>*</code> or <code>**</code> matches either of the following conditions, it will not work as the beginning of an emphasis mark anymore:</p><ul>
|
||
<li>The next character is a space (e.g. <code>word* word</code>)</li>
|
||
<li>The previous character is a punctuation character and the next character is a letter (not a space or punctuation character) (e.g. <code>文**（文）</code>)</li>
|
||
</ul><p>On the contrary, if <code>*</code> or <code>**</code> matches either of the following conditions, it will not work as the end of an emphasis mark anymore:</p><ul>
|
||
<li>The previous character is a space (e.g. <code>word *word</code>)</li>
|
||
<li>The next character is a punctuation character and the previous character is a letter (e.g. <code>文。**文</code>)</li>
|
||
</ul><p>“A punctuation character” includes non-ASCII ones, brackets, quotation marks and some symbols including <code>%</code> and <code>@</code>. More strictly speaking, a character whose 2-letters Unicode category starts with <code>P</code> is treated as a punctuation character here.</p><div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>If the offending emphasis mark is next to a space, move the space out of the range of emphasis:</p><div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">english.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">Do not end a range of emphasis with a space.</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain"> Or </span><span class="token code-snippet code keyword" style="color:#CF222E">`**`</span><span class="token plain"> will not work.</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>If the offending emphasis mark is surrounded by both a punctuation character and a letter, you can fix it without modifying the content by:</p><ol>
|
||
<li>Convert the document to MDX if it is a vanilla Markdown.</li>
|
||
<li>replace the offending emphasis mark with a raw HTML tag (<code><em></code> or <code><strong></code>) instead:</li>
|
||
</ol><div class="language-mdx codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">japanese.mdx</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-mdx codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain"><strong>「。」の後に文を続けると`**`が意図した動作をしません。</strong>また、<strong>[リンク](https://docusaurus.io/)</strong>や<strong>`コード`</strong>のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>While not an ideal solution, you can also either of the following without converting the document to MDX:</p><ul>
|
||
<li>
|
||
<p>Move the most outside punctuation character out of the emphasis mark.</p>
|
||
<!-- -->
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">japanese.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">「。」の後に文を続けると`</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">`が意図した動作をしません</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">。また、[</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">リンク**](https://docusaurus.io/)や・・・</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
</li>
|
||
<li>
|
||
<p>Put a space just outside of the offending <code>*</code> or <code>**</code>. This solution does not force you to convert the document to MDX.</p>
|
||
<!-- -->
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">japanese.md</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content">「。」の後に文を続けると`</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">`が意図した動作をしません。</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content"> また、</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token url" style="color:#36acaa">[</span><span class="token url content" style="color:#36acaa">リンク</span><span class="token url" style="color:#36acaa">](</span><span class="token url" style="color:#36acaa">https://docusaurus.io/</span><span class="token url" style="color:#36acaa">)</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content"> や </span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token code-snippet code keyword" style="color:#CF222E">`コード`</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token bold content"> のすぐ外側に`</span><span class="token bold punctuation" style="color:#393A34">**</span><span class="token plain">`、そのさらに外側に句読点以外がある場合も同様です。</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
</li>
|
||
</ul></div></div></div></div></details>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="mdx-plugins">MDX plugins<a href="#mdx-plugins" class="hash-link" aria-label="Direct link to MDX plugins" title="Direct link to MDX plugins"></a></h3>
|
||
<p>All the official packages (Unified, Remark, Rehype...) in the MDX ecosystem are now <a href="https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c" target="_blank" rel="noopener noreferrer"><strong>ES Modules only</strong></a> and do not support <a href="https://nodejs.org/api/modules.html#modules-commonjs-modules" target="_blank" rel="noopener noreferrer">CommonJS</a> anymore.</p>
|
||
<p>In practice this means that you can't do <code>require("remark-plugin")</code> anymore.</p>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Docusaurus v3 now supports <a href="https://flaviocopes.com/es-modules/" target="_blank" rel="noopener noreferrer"><strong>ES Modules</strong></a> configuration files. We recommend that you migrate your config file to ES module, that enables you to import the Remark plugins easily:</p><div class="language-js codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">docusaurus.config.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-js codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token keyword module" style="color:#CF222E">import</span><span class="token plain"> </span><span class="token imports">remarkPlugin</span><span class="token plain"> </span><span class="token keyword module" style="color:#CF222E">from</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'remark-plugin'</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword module" style="color:#CF222E">export</span><span class="token plain"> </span><span class="token keyword module" style="color:#CF222E">default</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">title</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'Docusaurus'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#6B6B6B;font-style:italic">/* site config using remark plugins here */</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>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 <a href="/docs/configuration#syntax-to-declare-docusaurus-config">Docusaurus config supports the usage of an async function</a> to let you do so.</p><div class="language-js codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">docusaurus.config.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-js codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">module</span><span class="token punctuation" style="color:#393A34">.</span><span class="token method-variable function-variable method function property-access" style="color:#8250DF">exports</span><span class="token plain"> </span><span class="token operator" style="color:#D73A49">=</span><span class="token plain"> </span><span class="token keyword" style="color:#CF222E">async</span><span class="token plain"> </span><span class="token keyword" style="color:#CF222E">function</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#CF222E">const</span><span class="token plain"> myPlugin </span><span class="token operator" style="color:#D73A49">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">(</span><span class="token keyword control-flow" style="color:#CF222E">await</span><span class="token plain"> </span><span class="token keyword module" style="color:#CF222E">import</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#C6105F">'remark-plugin'</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">)</span><span class="token punctuation" style="color:#393A34">.</span><span class="token keyword module" style="color:#CF222E">default</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword control-flow" style="color:#CF222E">return</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#6B6B6B;font-style:italic">// site config...</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>For plugin authors</div><div class="admonitionContent_Knsx"><p>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 <a href="https://github.com/facebook/docusaurus/discussions/9337" target="_blank" rel="noopener noreferrer">dedicated support discussion</a> to help plugin authors upgrade their code.</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="formatters">Formatters<a href="#formatters" class="hash-link" aria-label="Direct link to Formatters" title="Direct link to Formatters"></a></h3>
|
||
<p>Prettier, the most common formatter, supports only the legacy MDX v1, not v3 yet as of Docusaurus v3.0.0. You can add <code>{/* prettier-ignore */}</code> before the incompatible parts of your code to make it work with Prettier.</p>
|
||
<div class="language-mdx codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-mdx codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">{/* prettier-ignore */}</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"><SomeComponent>Some long text in the component</SomeComponent></span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<p>If you get tired of too many <code>{/* prettier-ignore */}</code> insertions, you can consider disabling MDX formatting by Prettier by adding the following to your <code>.prettierignore</code> file, until it starts supporting MDX v3:</p>
|
||
<div class="language-txt codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">.prettierignore</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-txt codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">*.mdx</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<h2 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="other-breaking-changes">Other Breaking Changes<a href="#other-breaking-changes" class="hash-link" aria-label="Direct link to Other Breaking Changes" title="Direct link to Other Breaking Changes"></a></h2>
|
||
<p>Apart the MDX v3 upgrade, here is an exhaustive list of breaking changes coming with Docusaurus v3.</p>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="nodejs-v180">Node.js v18.0<a href="#nodejs-v180" class="hash-link" aria-label="Direct link to Node.js v18.0" title="Direct link to Node.js v18.0"></a></h3>
|
||
<p>Node.js 16 <a href="https://nodejs.org/en/blog/announcements/nodejs16-eol" target="_blank" rel="noopener noreferrer">reached End-of-Life</a>, and Docusaurus v3 now requires <strong>Node.js >= 18.0</strong>.</p>
|
||
<div class="theme-admonition theme-admonition-tip admonition_o5H7 alert alert--success"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Install Node.js 18.0+ on your computer.</p><p>Eventually, configure your continuous integration, CDN or host to use this new Node.js version.</p><p>You can also update your site <code>package.json</code> to prevent usage of an older unsupported version:</p><div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">package.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "engines": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "node": ">=16.14"</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "node": ">=18.0"</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Upgrade your Docusaurus v2 site to Node.js 18 before upgrading to Docusaurus v3.</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="react-v180">React v18.0+<a href="#react-v180" class="hash-link" aria-label="Direct link to React v18.0+" title="Direct link to React v18.0+"></a></h3>
|
||
<p>Docusaurus v3 now requires <strong>React >= 18.0</strong>.</p>
|
||
<p>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. The official themes and plugins are compatible with React 18.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Read the official <a href="https://react.dev/blog/2022/03/29/react-v18" target="_blank" rel="noopener noreferrer">React v18.0</a> and <a href="https://react.dev/blog/2022/03/08/react-18-upgrade-guide" target="_blank" rel="noopener noreferrer">How to Upgrade to React 18</a>, and look at your own React code to figure out which components might be affected this upgrade.</p><p>We recommend to particularly look for:</p><ul>
|
||
<li>Automatic batching for stateful components</li>
|
||
<li>New React hydration errors reported to the console</li>
|
||
</ul></div></div>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>Experimental support for React 18 features</div><div class="admonitionContent_Knsx"><p>React 18 comes with new features:</p><ul>
|
||
<li><code><Suspense></code></li>
|
||
<li><code>React.lazy()</code></li>
|
||
<li><code>startTransition</code></li>
|
||
</ul><p>Their Docusaurus support is considered as experimental. We might have to adjust the integration in the future, leading to a different runtime behavior.</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="prism-react-renderer-v20">Prism-React-Renderer v2.0+<a href="#prism-react-renderer-v20" class="hash-link" aria-label="Direct link to Prism-React-Renderer v2.0+" title="Direct link to Prism-React-Renderer v2.0+"></a></h3>
|
||
<p>Docusaurus v3 upgrades <a href="https://github.com/FormidableLabs/prism-react-renderer" target="_blank" rel="noopener noreferrer"><code>prism-react-renderer</code></a> to v2.0+. This library is used for code block syntax highlighting.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>This is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. The <a href="https://github.com/FormidableLabs/prism-react-renderer/releases/tag/prism-react-renderer%402.0.0" target="_blank" rel="noopener noreferrer"><code>prism-react-renderer</code> v2 release notes</a> are not super exhaustive, but there are 3 major changes to be aware of for Docusaurus users.</p><p>The dependency should be upgraded:</p><div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">package.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "dependencies": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "prism-react-renderer": "^1.3.5",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "prism-react-renderer": "^2.1.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>The API to import themes in your Docusaurus config file has been updated:</p><div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">docusaurus.config.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> const lightTheme = require('prism-react-renderer/themes/github');</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> const darkTheme = require('prism-react-renderer/themes/dracula');</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> const {themes} = require('prism-react-renderer');</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> const lightTheme = themes.github;</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> const darkTheme = themes.dracula;</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Previously, <code>react-prism-render</code> v1 <a href="https://github.com/FormidableLabs/prism-react-renderer/blob/v1.3.5/src/vendor/prism/includeLangs.js" target="_blank" rel="noopener noreferrer">included more languages by default</a>. From v2.0+, <a href="https://github.com/FormidableLabs/prism-react-renderer/blob/prism-react-renderer%402.1.0/packages/generate-prism-languages/index.ts#L9" target="_blank" rel="noopener noreferrer">less languages are included by default</a>. You may need to add extra languages to your Docusaurus config:</p><div class="language-js codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">docusaurus.config.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-js codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#CF222E">const</span><span class="token plain"> siteConfig </span><span class="token operator" style="color:#D73A49">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">themeConfig</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">prism</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line theme-code-block-highlighted-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">additionalLanguages</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#C6105F">'bash'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'diff'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'json'</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="react-live-v40">React-Live v4.0+<a href="#react-live-v40" class="hash-link" aria-label="Direct link to React-Live v4.0+" title="Direct link to React-Live v4.0+"></a></h3>
|
||
<p>For users of the <code>@docusaurus/theme-live-codeblock</code> package, Docusaurus v3 upgrades <a href="https://github.com/FormidableLabs/react-live" target="_blank" rel="noopener noreferrer"><code>react-live</code></a> to v4.0+.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>In theory, you have nothing to do, and your existing interactive code blocks should keep working as before.</p><p>However, this is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. Read the <a href="https://github.com/FormidableLabs/react-live/releases/tag/v3.0.0" target="_blank" rel="noopener noreferrer">v3</a> and <a href="https://github.com/FormidableLabs/react-live/releases/tag/v4.0.0" target="_blank" rel="noopener noreferrer">v4</a> changelogs in case of problems.</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="remark-emoji-v40">remark-emoji v4.0+<a href="#remark-emoji-v40" class="hash-link" aria-label="Direct link to remark-emoji v4.0+" title="Direct link to remark-emoji v4.0+"></a></h3>
|
||
<p>Docusaurus v3 upgrades <a href="https://github.com/rhysd/remark-emoji" target="_blank" rel="noopener noreferrer"><code>remark-emoji</code></a> to v4.0+. This library is to support <code>:emoji:</code> shortcuts in Markdown.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Most Docusaurus users have nothing to do. Users of emoji shortcodes should read the <a href="https://github.com/rhysd/remark-emoji/blob/master/CHANGELOG.md" target="_blank" rel="noopener noreferrer">changelog</a> and double-check their emojis keep rendering as expected.</p><blockquote>
|
||
<p><strong>Breaking Change</strong> Update <a href="https://www.npmjs.com/package/node-emoji" target="_blank" rel="noopener noreferrer">node-emoji</a> from v1 to v2. This change introduces support for many new emojis and removes old emoji short codes which are no longer valid on GitHub.</p>
|
||
</blockquote></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="mermaid-v104">Mermaid v10.4+<a href="#mermaid-v104" class="hash-link" aria-label="Direct link to Mermaid v10.4+" title="Direct link to Mermaid v10.4+"></a></h3>
|
||
<p>For users of the <code>@docusaurus/theme-mermaid</code> package, Docusaurus v3 upgrades <a href="https://github.com/mermaid-js/mermaid" target="_blank" rel="noopener noreferrer"><code>mermaid</code></a> to v10.4+.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>In theory, you have nothing to do, and your existing diagrams should keep working as before.</p><p>However, this is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. Read the <a href="https://github.com/mermaid-js/mermaid/releases/tag/v10.0.0" target="_blank" rel="noopener noreferrer">v10</a> changelog in case of problem.</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="typescript-v50">TypeScript v5.0+<a href="#typescript-v50" class="hash-link" aria-label="Direct link to TypeScript v5.0+" title="Direct link to TypeScript v5.0+"></a></h3>
|
||
<p>Docusaurus v3 now requires <strong>TypeScript >= 5.0</strong>.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Upgrade your dependencies to use TypeScript 5+</p><div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">package.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "devDependencies": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "typescript": "~4.7.4"</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "typescript": "~5.2.2"</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="typescript-base-config">TypeScript base config<a href="#typescript-base-config" class="hash-link" aria-label="Direct link to TypeScript base config" title="Direct link to TypeScript base config"></a></h3>
|
||
<p>The official Docusaurus TypeScript config has been re-internalized from the external package <a href="https://www.npmjs.com/package/@tsconfig/docusaurus" target="_blank" rel="noopener noreferrer"><code>@tsconfig/docusaurus</code></a> to our new monorepo package <a href="https://www.npmjs.com/package/@docusaurus/tsconfig" target="_blank" rel="noopener noreferrer"><code>@docusaurus/tsconfig</code></a>.</p>
|
||
<p>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.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Swap the external TypeScript config package for the new official one</p><div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">package.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "devDependencies": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "@tsconfig/docusaurus": "^1.0.7",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "@docusaurus/tsconfig": "3.0.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Use it in your <code>tsconfig.json</code> file:</p><div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">tsconfig.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "extends": "@tsconfig/docusaurus/tsconfig.json",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "extends": "@docusaurus/tsconfig",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "compilerOptions": {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> "baseUrl": "."</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="new-config-loader">New Config Loader<a href="#new-config-loader" class="hash-link" aria-label="Direct link to New Config Loader" title="Direct link to New Config Loader"></a></h3>
|
||
<p>Docusaurus v3 changes its internal config loading library from <a href="https://github.com/sindresorhus/import-fresh" target="_blank" rel="noopener noreferrer"><code>import-fresh</code></a> to <a href="https://github.com/unjs/jiti" target="_blank" rel="noopener noreferrer"><code>jiti</code></a>. It is responsible for loading files such as <code>docusaurus.config.js</code> or <code>sidebars.js</code>, and Docusaurus plugins.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>In theory, you have nothing to do, and your existing config files should keep working as before.</p><p>However, this is a major dependency swap and subtle behavior changes could occur.</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="admonition-warning">Admonition Warning<a href="#admonition-warning" class="hash-link" aria-label="Direct link to Admonition Warning" title="Direct link to Admonition Warning"></a></h3>
|
||
<p>For historical reasons, we support an undocumented admonition <code>:::warning</code> that renders with a red color.</p>
|
||
<div class="theme-admonition theme-admonition-danger admonition_o5H7 alert alert--danger"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>Warning</div><div class="admonitionContent_Knsx"><p>This is a Docusaurus v2 <code>:::warning</code> admonition.</p></div></div>
|
||
<p>However, the color and icon have always been wrong. Docusaurus v3 re-introduces <code>:::warning</code> admonition officially, documents it, and fix the color and icon.</p>
|
||
<div class="theme-admonition theme-admonition-warning admonition_o5H7 alert alert--warning"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>warning</div><div class="admonitionContent_Knsx"><p>This is a Docusaurus v3 <code>:::warning</code> admonition.</p></div></div>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>If you previously used the undocumented <code>:::warning</code> admonition, make sure to verify for each usage if yellow is now an appropriate color. If you want to keep the red color, use <code>:::danger</code> instead.</p><p>Docusaurus v3 also <a href="https://github.com/facebook/docusaurus/pull/9308" target="_blank" rel="noopener noreferrer">deprecated the <code>:::caution</code></a> admonition. Please refactor <code>:::caution</code> (yellow) to either <code>:::warning</code> (yellow) or <code>:::danger</code> (red).</p><p>If you want to keep the title “caution”, you might want to refactor it to <code>:::warning[caution]</code> (yellow).</p></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="versioned-sidebars">Versioned Sidebars<a href="#versioned-sidebars" class="hash-link" aria-label="Direct link to Versioned Sidebars" title="Direct link to Versioned Sidebars"></a></h3>
|
||
<p>This breaking change will only affect <strong>Docusaurus v2 early adopters</strong> who versioned their docs before <code>v2.0.0-beta.10</code> (December 2021).</p>
|
||
<p>When creating version <code>v1.0.0</code>, the sidebar file contained a prefix <code>version-v1.0.0/</code> that <a href="https://github.com/facebook/docusaurus/pull/9310" target="_blank" rel="noopener noreferrer">Docusaurus v3 does not support anymore</a>.</p>
|
||
<div class="language-json codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">versioned_sidebars/version-v1.0.0-sidebars.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-json codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#005CC5">"version-v1.0.0/docs"</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#C6105F">"version-v1.0.0/introduction"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#C6105F">"version-v1.0.0/prerequisites"</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Remove the useless versioned prefix from your versioned sidebars.</p><div class="language-json codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">versioned_sidebars/version-v1.0.0-sidebars.json</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-json codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#005CC5">"docs"</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#C6105F">"introduction"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">"prerequisites"</span><span class="token punctuation" style="color:#393A34">]</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="blog-feed-limit">Blog Feed Limit<a href="#blog-feed-limit" class="hash-link" aria-label="Direct link to Blog Feed Limit" title="Direct link to Blog Feed Limit"></a></h3>
|
||
<p>The <code>@docusaurus/plugin-content-blog</code> now limits the RSS feed to the last 20 entries by default. For large Docusaurus blogs, this is a more sensible default value to avoid an increasingly large RSS file.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>In case you don't like this new default behavior, you can revert to the former "unlimited feed" behavior with the new <code>limit: false</code> feed option:</p><div class="language-js codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">docusaurus.config.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-js codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#CF222E">const</span><span class="token plain"> blogOptions </span><span class="token operator" style="color:#D73A49">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">feedOptions</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line theme-code-block-highlighted-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">limit</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token boolean" style="color:#005CC5">false</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="docs-theme-refactoring">Docs Theme Refactoring<a href="#docs-theme-refactoring" class="hash-link" aria-label="Direct link to Docs Theme Refactoring" title="Direct link to Docs Theme Refactoring"></a></h3>
|
||
<p>For users that swizzled docs-related theme components (like <code>@theme/DocPage</code>), these components have been significantly refactor to make it easier to customize.</p>
|
||
<p>Technically, <strong>this is not a breaking change</strong> because these components are <strong>flagged as unsafe to swizzle</strong>, however many Docusaurus sites ejected docs-related components, and will be interested to know their customizations might break Docusaurus.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>How to upgrade</div><div class="admonitionContent_Knsx"><p>Delete all your swizzled components, re-swizzle them, and re-apply your customizations on top of the newly updated components.</p><p>Alternatively, you can look at the <a href="https://github.com/facebook/docusaurus/pull/7966" target="_blank" rel="noopener noreferrer">pull-request notes</a> to understand the new theme component tree structure, and eventually try to patch your swizzled components manually.</p></div></div>
|
||
<h2 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="optional-changes">Optional Changes<a href="#optional-changes" class="hash-link" aria-label="Direct link to Optional Changes" title="Direct link to Optional Changes"></a></h2>
|
||
<p>Some changes are not mandatory, but remain useful to be aware of to plainly leverage Docusaurus v3.</p>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="automatic-jsx-runtime">Automatic JSX runtime<a href="#automatic-jsx-runtime" class="hash-link" aria-label="Direct link to Automatic JSX runtime" title="Direct link to Automatic JSX runtime"></a></h3>
|
||
<p>Docusaurus v3 now uses the React 18 <a href="https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html" target="_blank" rel="noopener noreferrer">"automatic" JSX runtime</a>.</p>
|
||
<p>It is not needed anymore to import React in JSX files that do not use any React API.</p>
|
||
<div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">src/components/MyComponent.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> import React from 'react';</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> export default function MyComponent() {</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> return <div>Hello</div>;</span><br></span><span class="token-line" style="color:#393A34"><span class="token unchanged line"></span><span class="token unchanged prefix unchanged"> </span><span class="token unchanged line"> }</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="esm-and-typescript-configs">ESM and TypeScript Configs<a href="#esm-and-typescript-configs" class="hash-link" aria-label="Direct link to ESM and TypeScript Configs" title="Direct link to ESM and TypeScript Configs"></a></h3>
|
||
<p>Docusaurus v3 supports ESM and TypeScript config files, and it might be a good idea to adopt those new options.</p>
|
||
<div class="language-js codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">docusaurus.config.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-js codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token keyword module" style="color:#CF222E">export</span><span class="token plain"> </span><span class="token keyword module" style="color:#CF222E">default</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">title</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'Docusaurus'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">url</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'https://docusaurus.io'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#6B6B6B;font-style:italic">// your site config ...</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<div class="language-ts codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">docusaurus.config.ts</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-ts codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#CF222E">import</span><span class="token plain"> </span><span class="token keyword" style="color:#CF222E">type</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain">Config</span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"> </span><span class="token keyword" style="color:#CF222E">from</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'@docusaurus/types'</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#CF222E">import</span><span class="token plain"> </span><span class="token keyword" style="color:#CF222E">type</span><span class="token plain"> </span><span class="token operator" style="color:#D73A49">*</span><span class="token plain"> </span><span class="token keyword" style="color:#CF222E">as</span><span class="token plain"> Preset </span><span class="token keyword" style="color:#CF222E">from</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'@docusaurus/preset-classic'</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#CF222E">const</span><span class="token plain"> config</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> Config </span><span class="token operator" style="color:#D73A49">=</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> title</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'My Site'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> favicon</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">'img/favicon.ico'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> presets</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">[</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token string" style="color:#C6105F">'classic'</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#6B6B6B;font-style:italic">/* Your preset config here */</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"> satisfies Preset</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">Options</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> themeConfig</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token comment" style="color:#6B6B6B;font-style:italic">/* Your theme config here */</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token plain"> satisfies Preset</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">ThemeConfig</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#CF222E">export</span><span class="token plain"> </span><span class="token keyword" style="color:#CF222E">default</span><span class="token plain"> config</span><span class="token punctuation" style="color:#393A34">;</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="using-the-mdx-extension">Using the <code>.mdx</code> extension<a href="#using-the-mdx-extension" class="hash-link" aria-label="Direct link to using-the-mdx-extension" title="Direct link to using-the-mdx-extension"></a></h3>
|
||
<p>We recommend using the <code>.mdx</code> extension whenever you use JSX, <code>import</code>, or <code>export</code> (i.e. MDX features) inside a Markdown file. It is semantically more correct and improves compatibility with external tools (IDEs, formatters, linters, etc.).</p>
|
||
<p>In future versions of Docusaurus, <code>.md</code> files will be parsed as standard <a href="https://commonmark.org/" target="_blank" rel="noopener noreferrer">CommonMark</a>, which does not support these features. In Docusaurus v3, <code>.md</code> files keep being compiled as MDX files, but it will be possible to <a href="https://github.com/facebook/docusaurus/issues/3018" target="_blank" rel="noopener noreferrer">opt-in for CommonMark</a>.</p>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="upgrading-math-packages">Upgrading math packages<a href="#upgrading-math-packages" class="hash-link" aria-label="Direct link to Upgrading math packages" title="Direct link to Upgrading math packages"></a></h3>
|
||
<p>If you use Docusaurus to render <a href="/docs/markdown-features/math-equations">Math Equations</a>, you should upgrade the MDX plugins.</p>
|
||
<p>Make sure to use <code>remark-math 6</code> and <code>rehype-katex 7</code> for Docusaurus v3 (using MDX v3). We can't guarantee other versions will work.</p>
|
||
<div class="language-diff codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-diff codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">{</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "remark-math": "^3.0.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "remark-math": "^6.0.0",</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token deleted-sign deleted prefix deleted" style="color:#d73a49">-</span><span class="token deleted-sign deleted line" style="color:#d73a49"> "rehype-katex": "^5.0.0"</span><br></span><span class="token-line" style="color:#393A34"><span class="token deleted-sign deleted line" style="color:#d73a49"></span><span class="token inserted-sign inserted prefix inserted" style="color:#36acaa">+</span><span class="token inserted-sign inserted line" style="color:#36acaa"> "rehype-katex": "^7.0.0"</span><br></span><span class="token-line" style="color:#393A34"><span class="token inserted-sign inserted line" style="color:#36acaa"></span><span class="token plain">}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<h3 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="turn-off-mdx-v1-compat">Turn off MDX v1 compat<a href="#turn-off-mdx-v1-compat" class="hash-link" aria-label="Direct link to Turn off MDX v1 compat" title="Direct link to Turn off MDX v1 compat"></a></h3>
|
||
<p>Docusaurus v3 comes with <a href="/docs/api/docusaurus-config#markdown">MDX v1 compatibility options</a>, that are turned on by default.</p>
|
||
<div class="language-js codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockTitle_bdru">docusaurus.config.js</div><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-js codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token keyword module" style="color:#CF222E">export</span><span class="token plain"> </span><span class="token keyword module" style="color:#CF222E">default</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">markdown</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">mdx1Compat</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">comments</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token boolean" style="color:#005CC5">true</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">admonitions</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token boolean" style="color:#005CC5">true</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token literal-property property" style="color:#005CC5">headingIds</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token boolean" style="color:#005CC5">true</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><span class="token punctuation" style="color:#393A34">;</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="comments-option"><code>comments</code> option<a href="#comments-option" class="hash-link" aria-label="Direct link to comments-option" title="Direct link to comments-option"></a></h4>
|
||
<p>This option allows the usage of HTML comments inside MDX, while HTML comments are officially not supported anymore.</p>
|
||
<p>For MDX files, we recommend to progressively use MDX <code>{/* comments */}</code> instead of HTML <code><!-- comments --></code>, and then turn this compatibility option off.</p>
|
||
<div class="theme-admonition theme-admonition-info admonition_o5H7 alert alert--info"><div class="admonitionHeading_FzoX"><span class="admonitionIcon_rXq6"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>Blog truncate marker</div><div class="admonitionContent_Knsx"><p>The default blog truncate marker now supports both <code><!-- truncate --></code> and <code>{/* truncate */}</code>.</p></div></div>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="admonitions-option"><code>admonitions</code> option<a href="#admonitions-option" class="hash-link" aria-label="Direct link to admonitions-option" title="Direct link to admonitions-option"></a></h4>
|
||
<p>This option allows the usage of the Docusaurus v2 <a href="/docs/markdown-features/admonitions#specifying-title">admonition title</a> syntax:</p>
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">:::note Your Title</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">content</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">:::</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<p>Docusaurus now implements admonitions with <a href="https://talk.commonmark.org/t/generic-directives-plugins-syntax/444" target="_blank" rel="noopener noreferrer">Markdown Directives</a> (implemented with <a href="https://github.com/remarkjs/remark-directive" target="_blank" rel="noopener noreferrer">remark-directive</a>), and the syntax to provide a directive label requires square brackets:</p>
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token plain">:::note[Your Title]</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">content</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">:::</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<p>We recommend to progressively use the new Markdown directive label syntax, and then turn this compatibility option off.</p>
|
||
<h4 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="headingids-option"><code>headingIds</code> option<a href="#headingids-option" class="hash-link" aria-label="Direct link to headingids-option" title="Direct link to headingids-option"></a></h4>
|
||
<p>This option allows the usage of the Docusaurus v2 <a href="/docs/markdown-features/toc#heading-ids">explicit heading id</a> syntax:</p>
|
||
<div class="language-md codeBlockContainer_jDV4 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_vx7S"><pre tabindex="0" class="prism-code language-md codeBlock_Gebt thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_FJaf"><span class="token-line" style="color:#393A34"><span class="token title important punctuation" style="color:#393A34;font-weight:bold">###</span><span class="token title important" style="color:#0550AE;font-weight:bold"> Hello World {#my-explicit-id}</span><br></span></code></pre><div class="buttonGroup_cUGO"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_OqsO" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_PgCn"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_bsQG"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
|
||
<p>This syntax is now invalid MDX, and would require to escape the <code>{</code> character: <code>\{#my-explicit-id}</code>.</p>
|
||
<p>We recommend to keep this compatibility option on for now, until we provide a new syntax compatible with newer versions of MDX.</p>
|
||
<h2 class="anchor anchorWithHideOnScrollNavbar_SSbb" id="troubleshooting">Troubleshooting<a href="#troubleshooting" class="hash-link" aria-label="Direct link to Troubleshooting" title="Direct link to Troubleshooting"></a></h2>
|
||
<p>In case of any upgrade problem, the first things to try are:</p>
|
||
<ul>
|
||
<li>make sure all your docs compile in the <a href="https://mdxjs.com/playground/" target="_blank" rel="noopener noreferrer">MDX playground</a>, or using <a href="https://github.com/slorber/docusaurus-mdx-checker" target="_blank" rel="noopener noreferrer"><code>npx docusaurus-mdx-checker</code></a></li>
|
||
<li>delete <code>node_modules</code> and <code>package-lock.json</code>, and then run <code>npm install</code> again</li>
|
||
<li>run <code>docusaurus clear</code> to clear the caches</li>
|
||
<li>remove third-party plugins that might not support Docusaurus v3</li>
|
||
<li>delete all your swizzled components</li>
|
||
</ul>
|
||
<p>Once you have tried that, you can ask for support through the following support channels:</p>
|
||
<ul>
|
||
<li><a href="https://github.com/facebook/docusaurus/discussions/9336" target="_blank" rel="noopener noreferrer">Docusaurus v3 - Upgrade Support</a></li>
|
||
<li><a href="https://discord.com/channels/398180168688074762/1154771869094912090" target="_blank" rel="noopener noreferrer">Docusaurus v3 - Discord channel #migration-v2-to-v3</a></li>
|
||
<li><a href="https://github.com/facebook/docusaurus/discussions/9053" target="_blank" rel="noopener noreferrer">MDX v3 - Upgrade Support</a></li>
|
||
<li><a href="https://github.com/facebook/docusaurus/discussions/9337" target="_blank" rel="noopener noreferrer">MDX v3 - Remark/Rehype Plugins Support</a></li>
|
||
<li><a href="https://discord.com/channels/398180168688074762/1116724556976111616" target="_blank" rel="noopener noreferrer">MDX v3 - Discord channel #migration-mdx-v3</a></li>
|
||
</ul>
|
||
<p>Please consider <strong>our time is precious</strong>. To ensure that your support request is not ignored, we kindly ask you to:</p>
|
||
<ul>
|
||
<li>provide a <strong>minimal</strong> reproduction that we can easily run, ideally created with <a href="https://docusaurus.new" target="_blank" rel="noopener noreferrer">docusaurus.new</a></li>
|
||
<li>provide a live deployment url showing the problem in action (if your site can build)</li>
|
||
<li>explain clearly the problem, much more than an ambiguous "it doesn't work"</li>
|
||
<li>include as much relevant material as possible: code snippets, repo url, git branch urls, full stack traces, screenshots and videos</li>
|
||
<li>present your request clearly, concisely, showing us that you have made an effort to help us help you</li>
|
||
</ul>
|
||
<p>Alternatively, you can look for a paid <a href="https://github.com/facebook/docusaurus/discussions/9281" target="_blank" rel="noopener noreferrer">Docusaurus Service Provider</a> to execute this upgrade for you. If your site is open source, you can also ask our community for <a href="https://github.com/facebook/docusaurus/discussions/9283" target="_blank" rel="noopener noreferrer">free, benevolent help</a>.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col"><a href="https://github.com/facebook/docusaurus/edit/main/website/docs/migration/v3.mdx" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_IMw_" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_OHCJ"><span class="theme-last-updated">Last updated<!-- --> on <b><time datetime="2024-03-20T17:08:05.000Z" itemprop="dateModified">Mar 20, 2024</time></b> by <b>Zed Spencer-Milnes</b></span></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/migration"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Upgrading Docusaurus</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/migration/v2"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Overview</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_RLlU thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#upgrading-dependencies" class="table-of-contents__link toc-highlight">Upgrading Dependencies</a></li><li><a href="#upgrading-mdx" class="table-of-contents__link toc-highlight">Upgrading MDX</a><ul><li><a href="#using-the-mdx-playground" class="table-of-contents__link toc-highlight">Using the MDX playground</a></li><li><a href="#using-the-mdx-checker-cli" class="table-of-contents__link toc-highlight">Using the MDX checker CLI</a></li><li><a href="#common-mdx-problems" class="table-of-contents__link toc-highlight">Common MDX problems</a></li><li><a href="#other-markdown-incompatibilities" class="table-of-contents__link toc-highlight">Other Markdown incompatibilities</a></li><li><a href="#mdx-plugins" class="table-of-contents__link toc-highlight">MDX plugins</a></li><li><a href="#formatters" class="table-of-contents__link toc-highlight">Formatters</a></li></ul></li><li><a href="#other-breaking-changes" class="table-of-contents__link toc-highlight">Other Breaking Changes</a><ul><li><a href="#nodejs-v180" class="table-of-contents__link toc-highlight">Node.js v18.0</a></li><li><a href="#react-v180" class="table-of-contents__link toc-highlight">React v18.0+</a></li><li><a href="#prism-react-renderer-v20" class="table-of-contents__link toc-highlight">Prism-React-Renderer v2.0+</a></li><li><a href="#react-live-v40" class="table-of-contents__link toc-highlight">React-Live v4.0+</a></li><li><a href="#remark-emoji-v40" class="table-of-contents__link toc-highlight">remark-emoji v4.0+</a></li><li><a href="#mermaid-v104" class="table-of-contents__link toc-highlight">Mermaid v10.4+</a></li><li><a href="#typescript-v50" class="table-of-contents__link toc-highlight">TypeScript v5.0+</a></li><li><a href="#typescript-base-config" class="table-of-contents__link toc-highlight">TypeScript base config</a></li><li><a href="#new-config-loader" class="table-of-contents__link toc-highlight">New Config Loader</a></li><li><a href="#admonition-warning" class="table-of-contents__link toc-highlight">Admonition Warning</a></li><li><a href="#versioned-sidebars" class="table-of-contents__link toc-highlight">Versioned Sidebars</a></li><li><a href="#blog-feed-limit" class="table-of-contents__link toc-highlight">Blog Feed Limit</a></li><li><a href="#docs-theme-refactoring" class="table-of-contents__link toc-highlight">Docs Theme Refactoring</a></li></ul></li><li><a href="#optional-changes" class="table-of-contents__link toc-highlight">Optional Changes</a><ul><li><a href="#automatic-jsx-runtime" class="table-of-contents__link toc-highlight">Automatic JSX runtime</a></li><li><a href="#esm-and-typescript-configs" class="table-of-contents__link toc-highlight">ESM and TypeScript Configs</a></li><li><a href="#using-the-mdx-extension" class="table-of-contents__link toc-highlight">Using the <code>.mdx</code> extension</a></li><li><a href="#upgrading-math-packages" class="table-of-contents__link toc-highlight">Upgrading math packages</a></li><li><a href="#turn-off-mdx-v1-compat" class="table-of-contents__link toc-highlight">Turn off MDX v1 compat</a></li></ul></li><li><a href="#troubleshooting" class="table-of-contents__link toc-highlight">Troubleshooting</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Learn</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs">Introduction</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/installation">Installation</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/migration">Migration from v1 to v2</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://stackoverflow.com/questions/tagged/docusaurus" target="_blank" rel="noopener noreferrer" class="footer__link-item">Stack Overflow<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a class="footer__link-item" href="/feature-requests">Feature Requests</a></li><li class="footer__item"><a href="https://discordapp.com/invite/docusaurus" target="_blank" rel="noopener noreferrer" class="footer__link-item">Discord<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a class="footer__link-item" href="/community/support">Help</a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/blog">Blog</a></li><li class="footer__item"><a class="footer__link-item" href="/changelog">Changelog</a></li><li class="footer__item"><a href="https://github.com/facebook/docusaurus" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://twitter.com/docusaurus" target="_blank" rel="noopener noreferrer" class="footer__link-item">Twitter<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item">
|
||
<a href="https://www.netlify.com" target="_blank" rel="noreferrer noopener" aria-label="Deploys by Netlify">
|
||
<img src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" alt="Deploys by Netlify" width="114" height="51">
|
||
</a>
|
||
</li><li class="footer__item">
|
||
<a href="https://argos-ci.com" target="_blank" rel="noreferrer noopener" aria-label="Covered by Argos">
|
||
<img src="https://argos-ci.com/badge.svg" alt="Covered by Argos" width="133" height="20">
|
||
</a>
|
||
</li></ul></div><div class="col footer__col"><div class="footer__title">Legal</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://opensource.facebook.com/legal/privacy/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Privacy<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://opensource.facebook.com/legal/terms/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Terms<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://opensource.facebook.com/legal/cookie-policy/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Cookie Policy<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_Rdzz"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="margin-bottom--sm"><a href="https://opensource.fb.com" rel="noopener noreferrer" class="footerLogoLink_CiM_"><img src="/img/meta_opensource_logo_negative.svg" alt="Meta Open Source Logo" class="footer__logo themedComponent_bJGS themedComponent--light_LEkC"><img src="/img/meta_opensource_logo_negative.svg" alt="Meta Open Source Logo" class="footer__logo themedComponent_bJGS themedComponent--dark_jnGk"></a></div><div class="footer__copyright">Copyright © 2024 Meta Platforms, Inc. Built with Docusaurus.</div></div></div></footer></div>
|
||
</body>
|
||
</html> |