3.0.0-rc.0

[slorber]

v3.0.0-rc.0 (2023-10-20)

Docusaurus v3 is feature complete.

It is now used by at least 3 major sites: Docusaurus, Jest and React-Native, and a few community sites. We fixed all the tiny issues encountered during that process.

This is now time to move v3 to the RC stage!

The final release is close, and the V3 upgrade guide is already available.

Release links

• GitHub Release PR: chore: v3.0.0-rc.0 release #9418
• GitHub Release notes: https://github.com/facebook/docusaurus/releases/tag/v3.0.0-rc.0
• GitHub Release discussion: 3.0.0-rc.0 #9429
• v3 Upgrade guide: https://docusaurus.io/docs/next/migration/v3

Dependency upgrades

Docusaurus v3 is mostly an infrastructure upgrade, notably:

• Node 18
• MDX 2
• React 18
• TS 5
• Mermaid 10.4
• react-prism-renderer v2
• react-live v4
• import-fresh => jiti

Breaking changes

The breaking changes are exhaustively documented in the V3 upgrade guide.

MDX v2 is the most annoying breaking change of Docusaurus v3: it will likely require you to update a few md/mdx files to ensure they still compile fine and render exactly as before.

The UI should mostly remain unchanged from the latest v2.x release, and we encourage you to try visual regression testing to avoid introducing any visual glitch during this upgrade.

Before attempting the upgrade, we also recommend to prepare your site incrementally while staying under Docusaurus v2. This will make it easier to adopt v3, and help reduce the size of the final PR, making it easier to review.

Features highlight

v3 also comes with a few useful features that we'll detail in the final release blog post, but you can get an overview by reading the changelog.

Notable features:

• ESM and TS config files
• Unlisted docs and blogs (!== from drafts)
• JSX automatic runtime
• Create embedded docs versions with query-string param
• New mermaid diagrams: Mindmap, Quadrant Chart
• New ESLint rules: no-html-links + prefer-docusaurus-heading
• Experimental CommonMark mode
• All others coming with the upgraded deps

Example upgrade PRs:

Use these PRs as inspiration to figure out what it takes to upgrade to v3:

• React-Native v3 upgrade PR: Upgrade React-Native website to Docusaurus v3 react-native-website#3780
• Jest v3 upgrade PR: Upgrade Jest website to Docusaurus v3 jestjs/jest#14463
• Metro v3 upgrade PR: WIP - Docusaurus v3 + FB preset patch metro#1094

Changelog

💥 Breaking Change

• create-docusaurus, docusaurus-plugin-content-docs, docusaurus-plugin-ideal-image, docusaurus-types, docusaurus-utils, docusaurus
  • #9317 feat(core): support TypeScript + ESM configuration (@harryzcy)
• create-docusaurus, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus
  • #9316 chore: upgrade syntax highlighting dependencies, prism-react-renderer to v2, react-live to v4 (@harryzcy)
• create-docusaurus, docusaurus-cssnano-preset, docusaurus-logger, docusaurus-mdx-loader, docusaurus-migrate, docusaurus-plugin-client-redirects, docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus-plugin-debug, docusaurus-plugin-google-analytics, docusaurus-plugin-google-gtag, docusaurus-plugin-google-tag-manager, docusaurus-plugin-ideal-image, docusaurus-plugin-pwa, docusaurus-plugin-sitemap, docusaurus-preset-classic, docusaurus-remark-plugin-npm2yarn, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid, docusaurus-theme-search-algolia, docusaurus-theme-translations, docusaurus-utils-common, docusaurus-utils-validation, docusaurus-utils, docusaurus, eslint-plugin, lqip-loader
  • #9348 chore: update node engine version 18 (@OzakIOne)
• docusaurus-plugin-content-docs, docusaurus-theme-classic
  • #9310 chore(plugin-docs): remove legacy versioned prefix on doc ids and sidebar names in versioned sidebars (@slorber)
• docusaurus-theme-classic, docusaurus-theme-translations
  • #9308 fix(theme): make warning a first-class admonition, and deprecate caution admonition (@slorber)
• docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid
  • #9305 feat(theme-mermaid): upgrade Mermaid to v10.4 - handle async rendering (@slorber)
• create-docusaurus, docusaurus-plugin-content-docs, docusaurus-plugin-debug, docusaurus-plugin-google-analytics, docusaurus-plugin-google-gtag, docusaurus-plugin-google-tag-manager, docusaurus-plugin-ideal-image, docusaurus-plugin-pwa, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid, docusaurus-theme-search-algolia, docusaurus-tsconfig, docusaurus
  • #9258 feat: Docusaurus v3 upgrades and require TypeScript 5 (@slorber)
• docusaurus-plugin-content-blog
  • #9189 feat(blog-plugin): limit option for blog feedOptions (@johnnyreilly)
• create-docusaurus, docusaurus-tsconfig
  • #9050 feat: create official TypeScript base config @docusaurus/tsconfig (@slorber)
• create-docusaurus, docusaurus-mdx-loader, docusaurus-module-type-aliases, docusaurus-plugin-client-redirects, docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus-plugin-debug, docusaurus-plugin-google-analytics, docusaurus-plugin-google-gtag, docusaurus-plugin-google-tag-manager, docusaurus-plugin-ideal-image, docusaurus-plugin-pwa, docusaurus-plugin-sitemap, docusaurus-preset-classic, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid, docusaurus-theme-search-algolia, docusaurus-types, docusaurus
  • #8961 feat: React 18 + automatic JSX runtime + build --dev (@slorber)
• create-docusaurus
  • #9026 chore: remove facebook template (@slorber)
• create-docusaurus, docusaurus-mdx-loader, docusaurus-migrate, docusaurus-plugin-content-blog, docusaurus-remark-plugin-npm2yarn, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-mermaid, docusaurus-types, docusaurus-utils-validation, docusaurus-utils, docusaurus
  • #8288 feat: upgrade to MDX v2 (@slorber)
• docusaurus-plugin-content-docs, docusaurus-theme-classic, docusaurus-theme-common, docusaurus
  • #7966 fix(plugin-docs,theme): refactor docs plugin routes and component tree (@slorber)

🚀 New Feature

• create-docusaurus, docusaurus-plugin-content-docs, docusaurus-plugin-ideal-image, docusaurus-types, docusaurus-utils, docusaurus
  • #9317 feat(core): support TypeScript + ESM configuration (@harryzcy)
• docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid
  • #9305 feat(theme-mermaid): upgrade Mermaid to v10.4 - handle async rendering (@slorber)
• create-docusaurus
  • #9241 feat: support bun package manager in create-docusaurus (@colinhacks)
• docusaurus-plugin-content-blog
  • #9189 feat(blog-plugin): limit option for blog feedOptions (@johnnyreilly)
• docusaurus-theme-classic
  • #9152 feat(theme): add support for meta og locale and alternates (@FlorinaPacurar)
  • #9028 feat(theme): add ability to inject data attributes from query-string - possibility to create an iframe/embed variant of a page (@slorber)
  • #8915 feat(theme): add queryString option to localeDropdown (@wceolin)
• docusaurus-plugin-client-redirects, docusaurus-utils-validation
  • #9171 feat(client-redirects-plugin): support fully qualified urls and querystring/hash in destination/to url (@slorber)
• docusaurus
  • #9102 feat(cli): deploy command should allow customizing git config user.name / user.email in deployment branch (Enhance the deploy command to enable the setting of git user.name and user.email in deployment branch #9101) (@amdshrif)
• docusaurus-mdx-loader, docusaurus-types, docusaurus
  • #9097 feat(mdx): add siteConfig.markdown.format to configure the default content parser (MDX / CommonMark) (@slorber)
• docusaurus-plugin-content-pages, docusaurus-theme-classic
  • #9071 feat(pages): add support for missing SEO front matter + improve SEO docs (@slorber)
• create-docusaurus, docusaurus-tsconfig
  • #9050 feat: create official TypeScript base config @docusaurus/tsconfig (@slorber)
• create-docusaurus, docusaurus-mdx-loader, docusaurus-module-type-aliases, docusaurus-plugin-client-redirects, docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus-plugin-debug, docusaurus-plugin-google-analytics, docusaurus-plugin-google-gtag, docusaurus-plugin-google-tag-manager, docusaurus-plugin-ideal-image, docusaurus-plugin-pwa, docusaurus-plugin-sitemap, docusaurus-preset-classic, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock, docusaurus-theme-mermaid, docusaurus-theme-search-algolia, docusaurus-types, docusaurus
  • #8961 feat: React 18 + automatic JSX runtime + build --dev (@slorber)
• docusaurus-theme-common
  • #8982 feat(theme-common): code block MagicComments support for TeX/LaTeX/Matlab (@jj-style)
  • #8870 feat(theme-common): code block MagicComments support for Lua/Haskell -- and WebAssembly ;; (@tarunrajput)
• create-docusaurus, docusaurus-mdx-loader, docusaurus-migrate, docusaurus-plugin-content-blog, docusaurus-remark-plugin-npm2yarn, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-mermaid, docusaurus-types, docusaurus-utils-validation, docusaurus-utils, docusaurus
  • #8288 feat: upgrade to MDX v2 (@slorber)
• docusaurus-theme-classic, docusaurus-theme-common
  • #8890 feat(theme): create more generic ThemedComponent util from ThemedImage (@slorber)
• create-docusaurus, docusaurus-theme-classic, docusaurus-theme-search-algolia, eslint-plugin
  • #8384 feat(eslint-plugin): new prefer-docusaurus-heading rule (@Devansu-Yadav)
• docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-search-algolia, docusaurus, eslint-plugin
  • #8156 feat: add eslint plugin no-html-links (@JohnVicke)
• docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-translations, docusaurus-utils-validation, docusaurus-utils
  • #8004 feat(docs,blog,pages): add support for "unlisted" front matter - hide md content in production (@jodyheavener)

🐛 Bug Fix

• docusaurus
  • #9387 fix(core): log missing errorInfo in React 18 onRecoverableError callback (@johnnyreilly)
  • #9309 fix(cli): disable vertical borders of the update notification (@qwerzl)
  • #9112 fix(core): throw error if build folder already exists on initial clean (@thedevwonder)
  • #9006 fix(core): docusaurus CLI should detect the correct yarn version when suggesting upgrades (@0420syj)
  • #7951 fix(core): make webpack HMR always listen to current location (@jeengbe)
• docusaurus-mdx-loader
  • #9386 fix(mdx-loader): get correct error line numbers, handle front matter + contentTitle with remark (@slorber)
  • #9262 fix(mdx-loader): improve mdxJsxTextElementToHtml (@slorber)
  • #9202 fix(mdx-loader): ensure heading anchor slugs respect GitHub emoji behavior (@yosukekato165)
  • #9100 fix(mdx): fix for html multi-line comments (@slorber)
  • #9091 fix(mdx-loader): loader error message should display stacktrace if no extra MDX details (@slorber)
  • #8960 fix: allow html syntax in MDX v2 with format md (@slorber)
• docusaurus-theme-classic
  • #9385 fix(theme): avoid rendering empty search container if site has no search plugin (@slorber)
  • #9183 fix(theme): make Prism code block language / additionalLanguages case insensitive (@heysujal)
  • #9216 fix(theme): fix typo in swizzle component config (@sixhobbits)
  • #9093 fix(theme): support details/summary in CommonMark + add md dogfood test cases (@slorber)
• docusaurus-mdx-loader, docusaurus-utils
  • #9369 fix(mdx-loader): prevent Open Graph images from being inserted as base64 (@Zwyx)
• docusaurus-theme-translations
  • #9362 fix(theme-translations): add Japanese translation for "warning" (@tats-u)
  • #9321 fix(theme-translations): add missing zh-Hans messages (@chudongvip)
  • #9338 fix(theme-translations): complete and fix hungarian translations (@la55u)
  • #9292 fix(theme-translations): add missing Spanish theme translations (@Villanuevand)
  • #9021 fix(theme-transalations): fix Swedish translation of "last updated" (@gazab)
• docusaurus-theme-classic, docusaurus-theme-translations
  • #9308 fix(theme): make warning a first-class admonition, and deprecate caution admonition (@slorber)
  • #9269 fix(theme): improve docs sidebar category caret aria-label accessibility (@pinakipb2)
• Other
  • #9260 fix(website): fix showcase search input (@biplavmz)
  • #8193 fix(website): mobile scroll on homepage announcement (@maliMirkec)
  • #8042 fix(website): fix blog post social card (@slorber)
• docusaurus-theme-common
  • #9276 fix(theme-common): remove useless useSyncExternalStore shim (@slorber)
• create-docusaurus
  • #9217 fix(create-docusaurus): increase Browserslist support query in dev (@slorber)
• docusaurus-plugin-content-blog
  • #9151 fix(content-blog): links in feed should be absolute (@VinceCYLiao)
• docusaurus-utils, docusaurus
  • #9160 fix(core): handle single quotes inside file paths (@Josh-Cena)
• docusaurus-plugin-debug
  • #9116 fix(debug-plugin): upgrade react-json-view to maintained React-18 compatible fork (@slorber)
• docusaurus-utils
  • #9046 fix(utils): better handling of code blocks in link replacement (@Josh-Cena)
  • #8927 fix(utils): make Markdown link replacement much more rigorous (@Josh-Cena)
  • #7864 fix(utils): always match exclusion root dirs as complete folder paths (@Josh-Cena)
  • #7801 fix(utils): recognize ~~~ as code fences in link replacement (@Josh-Cena)
• docusaurus-plugin-pwa, docusaurus
  • #8872 fix(core): better error logging on SSR/dev failures + log stacktraces and error causes (@slorber)
• docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus-utils-validation, docusaurus
  • #8258 fix(docusaurus-utils-validation): baseUrl + routeBasePath: allow empty string, normalized as "/" (@Djunnni)
• docusaurus-theme-classic, docusaurus-theme-common
  • #8319 fix(docs,theme): auto-generated category index should not display unlisted content (@slorber)
• docusaurus-theme-classic, docusaurus-theme-common, docusaurus-theme-live-codeblock
  • #8015 fix(live-codeblock): add error boundary to live code preview (@rashidmya)
• docusaurus-mdx-loader, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-utils-validation, docusaurus
  • #7945 refactor(theme): split admonitions, make swizzle easier, better retrocompatibility (@slorber)
• docusaurus-plugin-content-docs, docusaurus-theme-classic, docusaurus-theme-common, docusaurus
  • #7966 fix(plugin-docs,theme): refactor docs plugin routes and component tree (@slorber)

🏃‍♀️ Performance

• docusaurus
  • #9051 perf(core): use React 18 startTransition for hydration (@sanjaiyan-dev)
  • #8081 perf(core): move scripts to document head + defer (@sanjaiyan-dev)
• docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus
  • #8972 fix: remove useless js-loader in front of mdx-loader (@slorber)

💅 Polish

• docusaurus
  • #9381 feat(core): throw error when official docusaurus dependencies use different versions (@JorensM)
• docusaurus-theme-translations
  • #9302 chore(theme-translations): complete zh-Hant translations (@qwerzl)
  • #9025 chore(theme-translations): complete it translations (@bitpredator)
• docusaurus-theme-classic
  • #9184 fix(theme): change schema.org itemType prop urls from http to https (@thedevwonder)
• create-docusaurus, docusaurus-plugin-content-blog, docusaurus-plugin-content-docs, docusaurus-plugin-content-pages, docusaurus
  • #9133 fix(init): change initial site URL to one that is safe for the future (@tats-u)
• docusaurus-theme-classic, docusaurus-theme-common
  • #8150 fix(theme-classic): polish admonition details, render title-only admonitions (@attitude)
• docusaurus-plugin-google-gtag
  • #8143 refactor(plugin-gtag): update gtag plugin to modern SPA recommendations (@lanegoolsby)
• docusaurus-mdx-loader, docusaurus-theme-classic, docusaurus-theme-common, docusaurus-utils-validation, docusaurus
  • #7945 refactor(theme): split admonitions, make swizzle easier, better retrocompatibility (@slorber)

📝 Documentation

• Other
  • #9417 docs: add Docusaurus v3.0 upgrade guide (@slorber)
  • #9396 docs: fix typos in website/docs/i18n/i18n-git.mdx (@suravshrestha)
  • #9397 docs: fix typos in website/docs/migration/migration-manual.mdx (@suravshrestha)
  • #9388 docs: fix algolia crowler config template link for v3 (@slorber)
  • #9377 docs(deployment): add permissions config to github action file in v2.4.3 (@chillinPanda)
  • #9333 docs: "Preparing your site for Docusaurus v3" blog post (@slorber)
  • #9330 docs: "Upgrading frontend dependencies with confidence" blog post (@slorber)
  • #9288 docs: fix bad link for create doc (@forresst)
  • #9267 docs: fix typo in docs-introduction (@HyeokjinKang)
  • #9247 docs: Reword comparison between React authoring and CSS authoring (@hidde)
  • #9223 docs: fix grammatical error, rewrite sentence to make clearer (@thatrobotdev)
  • #9233 docs(website): Add a "clearAll" Feature to site showcase (@biplavmz)
  • #9180 docs: remove 'import type' declaration in javascript snippet (@oluwatobiss)
  • #9177 docs: improve the opening sentence's clarity (@oluwatobiss)
  • #9149 docs: improve yarn deps upgrade command (@webbertakken)
  • #9139 docs: add Flightcontrol as a deployment option (@ModupeD)
  • #9082 docs: fix themeConfig.prism.defaultLanguage table api ref docs (@razzeee)
  • #9074 docs: fix filenames in docs/swizzling.mdx (@shwaka)
  • #9065 docs: update link for commonly used languages (@heysujal)
  • #9055 docs: update outdated links in showcase (@manuel-rw)
  • #9063 docs: add @markprompt/docusaurus-theme-search (@schneegansm)
  • #9033 docs: update info for community plugin docusaurus2-graphql-doc-generator (@edno)
  • #9044 docs: fix prism theme broken link in code blocks docs (@adithyaakrishna)
  • #9043 docs: fix grammar typo in swizzling.mdx (@adampatterson)
  • #9018 docs: fix link to rehype (@Mogyuchi)
  • #8993 docs: fix broken link in code blocks docs (@NamanGarg2075)
  • #8975 docs: update link in md code blocks section (@rbarbazz)
  • #8976 docs: update broken links theme configuration page (@rbarbazz)
  • #8904 docs: fix broken link to Prism includeLangs.js default list of languages (@conlacda)
  • #8951 docs: mention equivalent config syntaxes (@thadguidry)
  • #8950 docs: bidirectional link between api config and guide config (@thadguidry)
  • #8953 docs: mention blog truncating marker edge case (@allyw2002)
  • #8941 docs: rewrite some docs for mdx v2 (@slorber)
  • #8943 docs: mention docusaurus.community site in resources (@thadguidry)
  • #8920 docs: mdx-js is using v2 for next edition (@jhcao23)
  • #8888 docs: improve sidebar items custom props docs (@slorber)
  • #8877 docs: add "permissions.content: write" to GH workflow examples (@e-minguez)
  • #8845 docs: add description on blog post file/folder naming conventions and date extraction patterns (@rojakcoder)
  • #8865 docs: correct small grammar error (@werner33)
  • #8830 docs: link to mermaid config types (@PaulRBerg)
  • #8804 docs: update suggestion for OSS meta projects (@antonk52)
  • #8788 docs: remove problematic mdx2 anchor id docs for MDX 2 migration (@slorber)
  • #8780 docs: fix localhost url without link (@slorber)
  • #8779 docs: v2 docs should discourage the usage of a lower-case MDX component (will not work in v3) (@slorber)
  • #8761 docs: add mention that themeConfig.footer.copyright supports html strings (@fxpby)
  • #8723 docs: add TypeScript playgrounds to docusaurus.new + Playground page (@slorber)
  • #8709 docs: add dark mode version of BrowserStack logo (@fredrikstave)
  • #8642 docs: clarify query string behavior (@homotechsual)
  • #8576 docs(playground): use CodeSandbox cloud sandboxes (@danilowoz)
  • #8543 docs: add link to pluralization docs (@homotechsual)
  • #8556 docs: document plugin-content-pages wrapperClassName frontmatter. (@homotechsual)
  • #8548 docs: fix typo 'validationOptions' (@gracefullight)
  • #8509 docs(website): fix broken external links wrongly modified to use the .mdx extension (ex: github README.mdx) (@Kesyau)
  • #8507 docs: blog + community + dogfood docs should use .mdx extension (@slorber)
  • #8490 docs(website): use .mdx extension for every docs (@slorber)
  • #8484 docs: plugin-content-sitemap -> plugin-sitemap (@chubei)
  • #8454 fix(docs): Update link for tooljet website(broken) (@shawshankkumar)
  • #8443 docs: fix website home testimonials broken image URLs (@abhinandanwadwa)
  • #8438 docs: add hyperlink to swizzling in Search page (@dandv)
  • #8431 docs: add diagrams page to 2.2.0 sidebar (@homotechsual)
  • #8307 docs: clarify additionalLanguages with custom language definitions. (@homotechsual)
  • #8390 docs: changed actions/checkout version from 2 to 3 (@cm-igarashi-ryosuke)
  • #8262 docs: fix links to external plugin description (@scubamaggo)
  • #8375 docs: add Kinsta to deployment page (@palmiak)
  • #8417 docs: document theme-mermaid in API sidebar (@homotechsual)
  • #8392 docs: add i18n guide doc should link to i18n core config doc (@mcallisto)
  • #8388 docs: point to where commit types are listed (@dandv)
  • #8352 docs: actually demo the zero-width space workaround in MDX (@waldyrious)
  • #8363 docs: fix unclosed admonition code block (@Zwyx)
  • #8364 docs: autogenerated page comment does not matching dirName in examples (@HumbleDeer)
  • #8359 docs: fix anchor link #customFields (@Zwyx)
  • #8320 docs: remove blog.johnnyreilly.com Google Analytics tag from docs part 2 (@johnnyreilly)
  • #8335 docs: use Mermaid diagram for routing page (@Mysterious-Dev)
  • #8313 docs: link to migration guide from Blogger to Docusaurus / remove blog.johnnyreilly.com Google Analytics tag from docs (@johnnyreilly)
  • #8292 docs: document tag types for insertHtmlContent (@homotechsual)
  • #8272 docs: fix mermaid theme options typo (@ntucker)
  • #8209 docs: removing community resource docusaurus-plugin-relative-paths (@ShahriarKh)
  • #8146 docs(content-docs): add api doc for displayed_sidebar front matter (@slorber)
  • #8115 docs: add caveat about using Translate in string contexts (@Josh-Cena)
  • #8053 docs: document usage of docs frontMatter.custom_edit_url: null (@homotechsual)
  • #8010 docs(showcase): add 74 new showcase sites (@slorber)
  • #7955 docs: add docusaurus-post-generator to community resource list (@moojing)
  • #7906 docs: add TOC heading level options to guide (@Josh-Cena)
  • #7884 docs: add baseUrl to example tsconfig (@Foosballfan)
  • #7835 docs: update workbox doc link (@hslee2008)
  • #7799 docs: formally document how admonitions can be customized (@Josh-Cena)
  • #7796 docs: modify the description of deploying to Netlify (@Oreoxmt)
• docusaurus-logger
  • #9210 docs: add the missing import logger statement (@Josh-Cena)
  • #8047 docs: improve alt messages (@Josh-Cena)
• create-docusaurus
  • #8944 polish(create-docusaurus): add comment in config to mention different ways to declare config + doc link (@thadguidry)
  • #8323 docs: fix typo 'internalization' (@dandv)
• docusaurus-plugin-ideal-image
  • #8630 docs: normalize README for ideal-image plugin (@Mysterious-Dev)
• docusaurus-mdx-loader
  • #8419 docs: document siteConfig.markdown + better mdx-loader retrocompat (@slorber)

🔧 Maintenance

• docusaurus-migrate
  • #9400 chore: remove docusaurus-migrate (@slorber)
• docusaurus-theme-search-algolia
  • #9320 chore(theme-search-algolia): revert docsearch package range downgrade after bugfix release (@slorber)
• docusaurus-theme-translations
  • #9304 chore(theme-translations): complete French translations (@forresst)
• Other
  • #9264 ci: only install Chromium for Playwright Argos tests (@mxschmitt)
  • #9245 chore: bump devcontainer to Ubuntu 22.04 to resolve arm64 incompatibility (@AFRUITPIE)
  • #8947 test: add visual regression tests with Argos CI (@slorber)
  • #8911 chore: migrate website config to createConfigAsync (@slorber)
  • #8578 docs: fix dead anchor for issue reporting guidelines in template (@Sainan)
  • #8447 chore: update lerna to v6.2.0 (@AgentEnder)
  • #7967 test: improve e2e verdaccio configuration (@juanpicado)
  • #7863 docs: publish 2.0.0 release blog post + adapt website for the launch (@slorber)
  • #7828 misc: change showcase submission process, use GitHub discussion (@slorber)
• docusaurus-plugin-content-blog
  • #9195 test(blog-plugin): fix ability to generate proper blog website fixture build snapshot (@slorber)
• create-docusaurus, docusaurus-theme-classic
  • #9024 docs: remove Meta Data Policy footer link on website (@KarthickSakthi)
• docusaurus
  • #8660 chore: bump update-notifier (@layershifter)

Committers: 131

• 0x24Karthick (@KarthickSakthi)
• Abhinandan Wadhwa (@abhinandanwadwa)
• Abinash Satapathy (@Abinashbunty)
• Adam Patterson (@adampatterson)
• Adithya Krishna (@adithyaakrishna)
• Ahmad Shrif (@amdshrif)
• Ahmed Mustafa Malik (@amm98d)
• Akshay Bhalotia (@akshaybhalotia)
• Alex (@sashashura)
• Alexander Nguyen (@GalexyN)
• Alexey Pyltsyn (@lex111)
• Andrew Lyons (@andrewnicols)
• Andrés Villanueva (@Villanuevand)
• Anna (@HumbleDeer)
• Anton Kastritskii (@antonk52)
• Antony Onipko (@antonyoni)
• Aolin (@Oreoxmt)
• Aqueeb (@aqueeb)
• Bei Chu (@chubei)
• Billy Chan (@billy1624)
• Biplav Kumar Mazumdar (@biplavmz)
• Bruce (@recallwei)
• Charles Killer (@Foosballfan)
• Chongyi Zheng (@harryzcy)
• Chua Chee How (@rojakcoder)
• Clément Vannicatte (@shortcuts)
• Colin McDonnell (@colinhacks)
• Coupy (@HyeokjinKang)
• Craigory Coppola (@AgentEnder)
• Dan Dascalescu (@dandv)
• Dan Roscigno (@DanRoscigno)
• Danilo Woznica (@danilowoz)
• David J. Felix (@DavidJFelix)
• Debbie O'Brien (@debs-obrien)
• Devansu Yadav (@Devansu-Yadav)
• Dinh Bao Dang (@chillinPanda)
• Dongjoon Lee (@Djunnni)
• Eduardo Mínguez (@e-minguez)
• Eunkwang Shin (@gracefullight)
• Forresst (@forresst)
• Francesco Ciulla (@FrancescoXX)
• Fredrik Stave (@fredrikstave)
• Fxpby (@fxpby)
• Gabriel Csapo (@gabrielcsapo)
• Gareth Dwyer (@sixhobbits)
• Grégory Heitz (@edno)
• Gustav Tonér (@gazab)
• Hayden Hong (@AFRUITPIE)
• Hidde de Vries (@hidde)
• Hyunseung (@hslee2008)
• JJ Style (@jj-style)
• James Kerrane (@thatrobotdev)
• Jean Humann (@jean-humann)
• Jesper Engberg (@jeengbe)
• Jody Heavener (@jodyheavener)
• Joe Williams (@BubbaJoe)
• John Cao (@jhcao23)
• John Reilly (@johnnyreilly)
• Jordan Manley (@werner33)
• Jorens Merenjanu (@JorensM)
• Joshua Chen (@Josh-Cena)
• Juan Picado (@juanpicado)
• Kolja (@razzeee)
• Lane Goolsby (@lanegoolsby)
• Lorenzo Lewis (@lorenzolewis)
• Maciek Palmowski (@palmiak)
• Manuel (@manuel-rw)
• Marco Kuper (@scubamaggo)
• Marco Stroppel (@mstroppel)
• Marie (@schneegansm)
• Markshawn (@MarkShawn2020)
• Martin Adamko (@attitude)
• Max Schmitt (@mxschmitt)
• Michael Remediakis (@mickremedi)
• Mikey O'Toole (@homotechsual)
• ModupeD (@ModupeD)
• Mu-Jing-Tsai (@moojing)
• Mysterious_Dev (@Mysterious-Dev)
• Naffy Dharni (@knownasnaffy)
• Naman Garg (@NamanGarg2075)
• Nathaniel Tucker (@ntucker)
• Oleksandr Fediashov (@layershifter)
• Oluwatobi Sofela (@oluwatobiss)
• Paul Razvan Berg (@PaulRBerg)
• Pinaki Bhattacharjee (@pinakipb2)
• Raphaël Barbazza (@rbarbazz)
• Rashid (@rashidmya)
• Ryosuke Igarashi (@cm-igarashi-ryosuke)
• SADIK KUZU (@sadikkuzu)
• Sanjaiyan Parthipan (@sanjaiyan-dev)
• Serenus (@Kesyau)
• Shahriar (@ShahriarKh)
• Shashank Kumar (@shawshankkumar)
• Shun Wakatsuki (@shwaka)
• Silvestar Bistrović (@maliMirkec)
• Sujal Gupta (@heysujal)
• Sunghyun Cho (@anaclumos)
• Surav Shrestha (@suravshrestha)
• Sébastien Lorber (@slorber)
• Tamal Anwar Chowdhury (@tamalchowdhury)
• Tarun Chauhan (@tarunrajput)
• Tatsunori Uchino (@tats-u)
• Thad Guidry (@thadguidry)
• Tom Mrazauskas (@mrazauskas)
• Viktor Malmedal (@JohnVicke)
• Waldir Pimenta (@waldyrious)
• Wan Sim (@0420syj)
• Webber Takken (@webbertakken)
• Will Ceolin (@wceolin)
• Yangshun Tay (@yangshun)
• Zwyx (@Zwyx)
• @Dr-Electron
• @FlorinaPacurar
• @Mogyuchi
• @Sainan
• @VinceCYLiao
• @allyw2002
• @bitpredator
• @conlacda
• @dawei-wang
• @la55u
• @mcallisto
• @prateekbytes
• @qwerzl
• @rsteele6
• @samatt14
• @thedevwonder
• @yosukekato165
• ozaki (@OzakIOne)
• sykp241095 (@sykp241095)
• 初冬 (@chudongvip)

---

This discussion was created from the release 3.0.0-rc.0.

[csantos-nydig]

I was taking a look at the migration guide, specifically at https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3#bad-usage-of--1 Bad usage of <

But I wonder how can I write blogs if I want to use the default truncateMarker <!-- truncate --> 😅 ?

[slorber]

We still support HTML comments through a compat option (although technically it's invalid MDX v2 syntax.

You can still use <!-- truncate --> (invalid MDX 2 but still supported)
Preferably you want to use {/* truncate */} now (valid MDX 2)

[csantos-nydig]

I used docusaurus-mdx-checker and it detected that syntax as invalid MDX2 syntax (as you said), which will be the same once I upgrade eslint-plugin-mdx.

I haven't tried your suggestion of {/* truncate */} yet; but I wonder if the default value of truncateMarker should be updated at the docusaurus-level so you don't use an invalid MDX2 syntax as your default?

[slorber]

@csantos-nydig that would really help if you actually tried, and provided a minimal runnable repro of a concrete problem you encounter. Otherwise we are only discussing theorical things.

v3 supports both <!-- truncate --> and {/* truncate */} for its default truncate marker regexp, as documented here: https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-blog#truncateMarker

npx docusaurus-mdx-checker is not supposed to return errors related to the truncate marker. If it does, I cannot help in any way if you don't provide me the exact Markdown source leading to this error

[csantos-nydig]

@slorber you were right. This works as expected. Just to close the loop here:

• I was using <!-- truncate --> in both *.md and *.mdx files (blog files)
• I updated my *.mdx files to use {/* truncate */}
• I kept my *.mdx files the same

---

Small note, for anyone interested:
It was failing for me because I'm still in docusaurus v2 "preparing my site for v3", and {/* truncate */} is not yet a valid truncateMarker

docusaurus/packages/docusaurus-plugin-content-blog/src/options.ts

Line 28 in 56410aa

truncateMarker: /<!--\s*truncate\s*-->/,

*it is only available in v3.0.0-rc.0;

docusaurus/packages/docusaurus-plugin-content-blog/src/options.ts

Line 29 in e66dfe0

truncateMarker: /<!--\s*truncate\s*-->|\{\/\*\s*truncate\s*\*\/\}/,

so for now I have updated my truncateMarker to /<!--\s*truncate\s*-->|\{\/\*\s*truncate\s*\*\/\}/ directly in the docusaurus.config file 👍

[slorber]

Thanks, great to know it's working

It was failing for me because I'm still in docusaurus v2 "preparing my site for v3", and {/* truncate */} is not yet a valid truncateMarker

Yes you can set the regexp you want yourself, although I did not include the migration of truncate markers to the v3 preparation guide since html comments remain supported. That will likely be in the v4 preparation guide ;)

[mrazauskas]

It is exciting to see ESM support for config file. Because of that I converted docusaurus-remark-plugin-tab-blocks to ESM and published it under rc tag.

Jest website got another update and now it is using rc versions of both Docusaurus and the plugin. See jestjs/jest#14629

I was expecting there will be a need to convert the config file in ESM, because the plugin is now an ESM package. Strangely require() is working just fine: https://github.com/jestjs/jest/blob/e7280a2132f454d5939b22c4e9a7a05b30cfcbe6/website/docusaurus.config.js#L65

Nothing is broken. The website builds as expected. Only the code looks puzzling. So I wanted to draw your attention.

[slorber]

Thanks, didn't know it would work. That's probably a feature provided by https://github.com/unjs/jiti, similar to how Bun is able to handle CJS/ESM in the same file.