mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-02 11:47:23 +02:00
1 line
No EOL
260 KiB
JavaScript
1 line
No EOL
260 KiB
JavaScript
"use strict";(self.webpackChunkwebsite=self.webpackChunkwebsite||[]).push([["35524"],{5865:function(e){e.exports=JSON.parse('{"archive":{"blogPosts":[{"id":"/releases/3.7","metadata":{"permalink":"/blog/releases/3.7","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/3.7/index.mdx","source":"@site/blog/releases/3.7/index.mdx","title":"Docusaurus 3.7","description":"We are happy to announce Docusaurus 3.7.","date":"2025-01-03T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":2.41,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 3.7","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2025-01-03T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","nextItem":{"title":"Docusaurus 3.6","permalink":"/blog/releases/3.6"}},"content":"We are happy to announce **Docusaurus 3.7**.\\n\\nDocusaurus is now compatible with [React 19](https://react.dev/blog/2024/12/05/react-19).\\n\\nUpgrading should be easy. Our [release process](/community/release-process) respects [Semantic Versioning](https://semver.org/). Minor versions do not include any breaking changes.\\n\\n\\n\\n{/* truncate */}\\n\\n## Highlight\\n\\n### React 19\\n\\nIn [#10763](https://github.com/facebook/docusaurus/pull/10763), we added support for [React 19](https://react.dev/blog/2024/12/05/react-19), and the Docusaurus website is running on React 19 already.\\n\\nFrom now on, all newly initialized sites will run on React 19 by default, and React 19 will be the minimum required version Docusaurus v4.\\n\\nHowever, React 18 remains supported, and existing Docusaurus sites can either choose to stay on React 18, or upgrade their dependencies to React 19:\\n\\n```diff\\n{\\n \\"name\\": \\"my-docusaurus-site\\",\\n \\"dependencies\\": {\\n- \\"react\\": \\"^18.0.0\\",\\n- \\"react-dom\\": \\"^18.0.0\\"\\n+ \\"react\\": \\"^19.0.0\\",\\n+ \\"react-dom\\": \\"^19.0.0\\"\\n }\\n}\\n```\\n\\n:::warning\\n\\nThere\'s no urge to upgrade your site immediately.\\n\\nReact 19 is a bit heavier than React 18. Since we support both versions, we don\'t leverage yet the new features that are exclusive to React 19.\\n\\nHowever, upgrading to React 19 prepares your site for Docusaurus v4, that will drop support for React 18.\\n\\nHere are good reasons to upgrade your site before Docusaurus v4:\\n\\n- You have custom React code and want to ensure it is ready for React19\\n- You plan to leverage the brand-new React 19 features in your own code\\n- You use custom or third-party plugins and want to ensure their compatibility\\n- You have a monorepo and want to align the React dependency to v19 for all packages\\n\\n:::\\n\\nAlong the way, we [fixed](https://github.com/facebook/docusaurus/pull/10786) all the remaining hydration errors reported by React 19, some of them produced by our aggressive HTML minifier settings.\\n\\n### SVGR plugin\\n\\nDocusaurus has built-in support for [SVGR](https://github.com/gregberge/svgr), allowing you to seamlessly import and use SVG files as React components:\\n\\n```tsx\\nimport DocusaurusSvg from \'./docusaurus.svg\';\\n\\n<DocusaurusSvg />;\\n```\\n\\nThis built-in support has been the source of various bug reports due to the inability to customize the [SVGR Options](https://react-svgr.com/docs/options/), in particular the [SVG Optimizer](https://svgo.dev/) options.\\n\\nIn [#10677](https://github.com/facebook/docusaurus/pull/10677), we extracted a new [`@docusaurus/plugin-svgr`](/docs/api/plugins/@docusaurus/plugin-svgr) that you can now configure according to your needs. It is included by default in our classic preset:\\n\\n```js\\nexport default {\\n presets: [\\n [\\n \'classic\',\\n {\\n svgr: {\\n svgrConfig: {\\n // Your SVGR options ...\\n svgoConfig: {\\n // Your SVGO options ...\\n // Use \\"svgoConfig: undefined\\" to use a svgo.config.js file\\n },\\n },\\n },\\n },\\n ],\\n ],\\n};\\n```\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#10768](https://github.com/facebook/docusaurus/pull/10768): Blog authors have built-in icons for social platforms bluesky, mastodon, threads, twitch, youtube, instagram.\\n- [#10729](https://github.com/facebook/docusaurus/pull/10729): Blog now supports `frontMatter.sidebar_label`\\n- [#10803](https://github.com/facebook/docusaurus/pull/10803): `@docusaurus/remark-plugin-npm2yarn` now supports Bun conversions.\\n- [#10672](https://github.com/facebook/docusaurus/pull/10672): Upgrade Algolia DocSearch to `algoliasearch` v5.\\n- [#10800](https://github.com/facebook/docusaurus/pull/10800): Docusaurus Faster turns Rspack incremental mode on by default.\\n- [#10783](https://github.com/facebook/docusaurus/pull/10783): Improve Dutch theme translations.\\n- [#10760](https://github.com/facebook/docusaurus/pull/10760): Improve Korean theme translations.\\n\\nCheck the **[3.7.0 changelog entry](/changelog/3.7.0)** for an exhaustive list of changes."},{"id":"/releases/3.6","metadata":{"permalink":"/blog/releases/3.6","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/3.6/index.mdx","source":"@site/blog/releases/3.6/index.mdx","title":"Docusaurus 3.6","description":"We are happy to announce Docusaurus 3.6.","date":"2024-11-04T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":5.91,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 3.6","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2024-11-04T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 3.7","permalink":"/blog/releases/3.7"},"nextItem":{"title":"Docusaurus 3.5","permalink":"/blog/releases/3.5"}},"content":"We are happy to announce **Docusaurus 3.6**.\\n\\nDocusaurus is now \u26A1\uFE0F\u26A1\uFE0F\u26A1\uFE0F **much faster** to build your site.\\n\\nUpgrading should be easy. Our [release process](/community/release-process) respects [Semantic Versioning](https://semver.org/). Minor versions do not include any breaking changes.\\n\\n\\n\\n{/* truncate */}\\n\\n## Highlights\\n\\nThis release has been mostly focused on build performance through the [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) project.\\n\\n## Docusaurus Faster\\n\\nThe [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) project\'s goal is to reduce the build times and memory consumption.\\n\\nWe have worked on multiple optimizations and modernized our infrastructure to use faster Rust-based tools, notably:\\n\\n- \uD83E\uDD80 [Rspack](https://rspack.dev/): Fast Rust-based web bundler, almost drop-in replacement for [webpack](https://webpack.js.org/)\\n- \uD83E\uDD80 [SWC](https://swc.rs/): Speedy Web Compiler, Rust-based platform for the Web (HTML, CSS, JS)\\n- \uD83E\uDD80 [Lightning CSS](https://lightningcss.dev/): An extremely fast CSS parser, transformer, bundler, and minifier\\n\\n### Impacts\\n\\nAdopting a new infrastructure can have various impacts. It\'s impossible to list them all exhaustively, so let\'s focus on the major ones.\\n\\nTo help you adopt it easily, we have been fairly conservative in terms of expected static site output and [browser support](/docs/browser-support).\\n\\n#### Build Time\\n\\nBenchmarks on community site show that you can expect your production site to build \u26A1\uFE0F**2 to 4 times faster**! \uD83D\uDD25:\\n\\n- [React Native website](https://github.com/facebook/react-native-website/pull/4268): 3.04x faster \uD83D\uDD25\\n- [Babel website](https://github.com/babel/website/pull/2997): 3.27x faster \uD83D\uDD25\\n- [Lexical website](https://github.com/facebook/lexical/pull/6761): 2x faster \uD83D\uDD25\\n\\n[How to benchmark](https://github.com/facebook/docusaurus/issues/10556#issuecomment-2407671873)\\n\\n:::note About rebuilds\\n\\n[Rspack doesn\'t support persistent caching yet](https://rspack.dev/misc/planning/roadmap#persistent-cache), but it\'s on the roadmap and should be implemented soon. We think it\'s not a problem for the adoption of Rspack considering a cold Rspack build is usually as fast as a warm Webpack build using persistent caching.\\n\\n:::\\n\\n#### Memory Consumption\\n\\nYou should also notice an improvement in memory consumption:\\n\\n- The new infrastructure consumes less memory overall\\n- We fixed an important [memory leak](https://github.com/facebook/docusaurus/pull/10599) that affects in particular i18n sites\\n- We added [CI checks](https://github.com/facebook/docusaurus/pull/10601) to ensure that we don\'t regress, and that our site and init template can both build in a memory-constrained environments\\n- We added [internal tooling](https://github.com/facebook/docusaurus/pull/10590) to better understand which step of a build consumes memory\\n- We [removed a `process.exit(0)`](https://github.com/facebook/docusaurus/pull/10410) that can hide memory leaks in your own code and third-party plugins\\n\\n#### Other Impacts\\n\\n- The HTML minifier now [emits warnings in case of invalid HTML markup](https://github.com/facebook/docusaurus/discussions/10580)\\n- The static HTML output is [~5% smaller](https://github.com/facebook/docusaurus/pull/10554)\\n- Some bugs are automatically fixed by the new infrastructure\\n\\n### Adoption Strategy\\n\\nThis new infrastructure is a breaking change, but it is opt-in and does not require a new major version of Docusaurus.\\n\\nBefore using Docusaurus Faster, add this new package:\\n\\n```bash npm2yarn\\nnpm install @docusaurus/faster\\n```\\n\\nTo help you **adopt it incrementally under Docusaurus v3**, we\'re introducing a set of feature flags that you can activate progressively.\\n\\nWe recommend turning them on all at once with this simple boolean shortcut:\\n\\n```js\\nconst config = {\\n future: {\\n experimental_faster: true,\\n },\\n};\\n```\\n\\nIn case one of the flags does not work for your site, it\'s possible to turn feature flags on independently:\\n\\n```ts\\nconst config = {\\n future: {\\n experimental_faster: {\\n swcJsLoader: true,\\n swcJsMinimizer: true,\\n swcHtmlMinimizer: true,\\n lightningCssMinimizer: true,\\n rspackBundler: true,\\n mdxCrossCompilerCache: true,\\n },\\n },\\n};\\n```\\n\\n- [`swcJsLoader`](https://github.com/facebook/docusaurus/pull/10435): Use [SWC](https://swc.rs/) to transpile JS (instead of [Babel](https://babeljs.io/))\\n- [`swcJsMinimizer`](https://github.com/facebook/docusaurus/pull/10441): Use [SWC](https://swc.rs/) to minify JS (instead of [Terser](https://github.com/terser/terser))\\n- [`swcHtmlMinimizer `](https://github.com/facebook/docusaurus/pull/10554): Use [SWC](https://swc.rs/) to minify HTML and inlined JS/CSS (instead of [html-minifier-terser](https://github.com/terser/html-minifier-terser))\\n- [`lightningCssMinimizer`](https://github.com/facebook/docusaurus/pull/10522): Use [Lightning CSS](https://lightningcss.dev/) to minify CSS (instead of [cssnano](https://github.com/cssnano/cssnano) and [clean-css](https://github.com/clean-css/clean-css))\\n- [`rspackBundler`](https://github.com/facebook/docusaurus/pull/10402): Use [Rspack](https://rspack.dev/) to bundle your app (instead of [webpack](https://webpack.js.org/))\\n- [`mdxCrossCompilerCache`](https://github.com/facebook/docusaurus/pull/10479): Compile MDX files once for both browser/Node.js environments instead of twice\\n\\n:::tip Experimental but safe\\n\\nDon\'t be afraid to turn this feature on. What\'s experimental is the config options.\\n\\nThe new infrastructure is robust and well-tested by our CI pipeline. The [Docusaurus site](https://docusaurus.io/) already uses it in production, and we plan to use it on other Meta docs sites as well.\\n\\n:::\\n\\n#### Plugins\\n\\nThe new infrastructure uses [Rspack](https://rspack.dev/). By chance, Rspack is almost 100% compatible with [webpack](https://webpack.js.org/), and Rspack shouldn\'t break our plugin ecosystem.\\n\\nMost Docusaurus plugins should work out of the box with Rspack, even those implementing [`configureWebpack`](/docs/api/plugin-methods/lifecycle-apis#configureWebpack).\\n\\nHowever, some of them will require small modifications to make them compatible with Rspack. The general idea is to avoid importing `webpack` directly, and use the \\"dynamically provided\\" webpack instance instead:\\n\\n```diff\\n-import webpack from \'webpack\';\\n\\nexport default function (context, options) {\\n return {\\n name: \'custom-docusaurus-plugin\',\\n- configureWebpack(config, isServer) {\\n+ configureWebpack(config, isServer, {currentBundler}) {\\n return {\\n plugins: [\\n- new webpack.DefinePlugin({}),\\n+ new currentBundler.instance.DefinePlugin({}),\\n ]\\n };\\n },\\n };\\n}\\n```\\n\\n:::tip For plugins authors\\n\\nCheck the [dedicated issue](https://github.com/facebook/docusaurus/issues/10572) for guidelines and support.\\n\\n:::\\n\\n### Next Steps\\n\\nIt\'s only the beginning: we will continue working on the [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) project and already have a few more performance improvements planned.\\n\\nDepending on [your feedback](https://github.com/facebook/docusaurus/issues/10556), we plan to make this new infrastructure the default in an upcoming major version of Docusaurus.\\n\\n\uD83D\uDE4F We\'d like to thank the authors of all these great tools that already helped us make Docusaurus much faster than before. In particular the [Rspack team](https://rspack.dev/misc/team/core-team) that supported us along the way, handled our feedback very quickly and implemented all the missing features we needed to make it happen. \uD83D\uDC4F\\n\\n## Rsdoctor plugin\\n\\nIn [#10588](https://github.com/facebook/docusaurus/pull/10588), we created a Docusaurus plugin for [Rsdoctor](https://rsdoctor.dev/). It analyzes the bundling phase of Docusaurus and helps you figure out what slows down the bundler in terms of loaders, plugins and minimizers. It works for both webpack and Rspack.\\n\\n\\n\\nTo use it, install the new [`@docusaurus/plugin-rsdoctor`](/docs/api/plugins/@docusaurus/plugin-rsdoctor) package, and then use the plugin in your config:\\n\\n```ts title=\\"docusaurus.config.js\\"\\nexport default {\\n plugins: [\\n [\\n \'rsdoctor\',\\n {\\n /* options */\\n },\\n ],\\n ],\\n};\\n```\\n\\n:::tip\\n\\nTurn it on conditionally, based on an environment variable:\\n\\n```ts title=\\"docusaurus.config.js\\"\\nexport default {\\n plugins: [\\n process.env.RSDOCTOR === \'true\' && [\\n \'rsdoctor\',\\n {\\n /* options */\\n },\\n ],\\n ],\\n};\\n```\\n\\n```bash\\n# Build without Rsdoctor\\nnpm run build\\n\\n# Build with Rsdoctor\\nRSDOCTOR=true npm run build\\n```\\n\\n:::\\n\\n## Mermaid\\n\\nIn [#10510](https://github.com/facebook/docusaurus/pull/10510), we relaxed our [Mermaid diagrams](https://mermaid.js.org/) dependency range to allow newer major versions of Mermaid. We now support both Mermaid 10/11, and expect upcoming versions to be compatible, letting you upgrade on your own terms.\\n\\nThis unlocks new types of diagrams, such as [Architecture Diagrams](https://mermaid.js.org/syntax/architecture):\\n\\n```mermaid\\narchitecture-beta\\n group api(cloud)[API]\\n\\n service db(database)[Database] in api\\n service disk1(disk)[Storage] in api\\n service disk2(disk)[Storage] in api\\n service server(server)[Server] in api\\n\\n db:L -- R:server\\n disk1:T -- B:server\\n disk2:T -- B:db\\n```\\n\\n## Translations\\n\\n- \uD83C\uDDF8\uD83C\uDDEE [#10551](https://github.com/facebook/docusaurus/pull/10551): Improve Slovenian theme translations.\\n- \uD83C\uDDFB\uD83C\uDDF3 [#10507](https://github.com/facebook/docusaurus/pull/10507): Improve Vietnamese theme translations.\\n- \uD83C\uDDEA\uD83C\uDDF8 [#10413](https://github.com/facebook/docusaurus/pull/10413): Improve Spanish theme translations.\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#10586](https://github.com/facebook/docusaurus/pull/10586): Blog support for `frontMatter.title_meta` to override `frontMatter.title` for SEO reason.\\n- [#10600](https://github.com/facebook/docusaurus/pull/10600): `docusaurus build` and `docusaurus deploy` now support multiple `--locale` CLI args.\\n- [#10454](https://github.com/facebook/docusaurus/pull/10454): `docusaurus-remark-plugin-npm2yarn` upgrades to [`npm-to-yarn` v3](https://github.com/nebrelbug/npm-to-yarn/releases/tag/v3.0.0) and can convert `npx` commands.\\n- [#10612](https://github.com/facebook/docusaurus/pull/10612): Canary releases will use `3.5.2-canary-<number>` instead of `0.0.0-canary-<number>` to respect plugins `peerDependency` constraints.\\n- [#10547](https://github.com/facebook/docusaurus/pull/10547): `@docusaurus/tsconfig` upgrades to `target: \'es2022\'`.\\n- [#10514](https://github.com/facebook/docusaurus/pull/10514): Remove `babel.config.js` from Docusaurus init templates to discourage customizing Babel.\\n\\nCheck the **[3.6.0 changelog entry](/changelog/3.6.0)** for an exhaustive list of changes."},{"id":"/releases/3.5","metadata":{"permalink":"/blog/releases/3.5","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/3.5/index.mdx","source":"@site/blog/releases/3.5/index.mdx","title":"Docusaurus 3.5","description":"We are happy to announce Docusaurus 3.5.","date":"2024-08-09T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":3.91,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 3.5","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2024-08-09T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 3.6","permalink":"/blog/releases/3.6"},"nextItem":{"title":"Docusaurus 3.4","permalink":"/blog/releases/3.4"}},"content":"We are happy to announce **Docusaurus 3.5**.\\n\\nThis release contains many **new exciting blog features**.\\n\\nUpgrading should be easy. Our [release process](/community/release-process) respects [Semantic Versioning](https://semver.org/). Minor versions do not include any breaking changes.\\n\\n\\n\\n{/* truncate */}\\n\\n## Highlights\\n\\n### Blog Social Icons\\n\\nIn [#10222](https://github.com/facebook/docusaurus/pull/10222), we added the possibility to associate social links to blog authors, for inline authors declared in front matter or global through the `authors.yml` file.\\n\\n```yml title=\\"blog/authors.yml\\"\\nslorber:\\n name: S\xe9bastien Lorber\\n # other author properties...\\n # highlight-start\\n socials:\\n x: sebastienlorber\\n linkedin: sebastienlorber\\n github: slorber\\n newsletter: https://thisweekinreact.com\\n # highlight-end\\n```\\n\\n\\n\\nIcons and handle shortcuts are provided for pre-defined platforms `x`, `linkedin`, `github` and `stackoverflow`. It\'s possible to provide any additional platform entry (like `newsletter` in the example above) with a full URL.\\n\\n### Blog Authors Pages\\n\\nIn [#10216](https://github.com/facebook/docusaurus/pull/10216), we added the possibility for [global blog authors](/docs/blog#global-authors) (declared in `authors.yml`) to have their own dedicated page listing all the blog posts they contributed to.\\n\\nThis feature is opt-in and mostly relevant for **multi-author blogs**. You can turn it on for a specific author by setting the `page: true` property:\\n\\n```yml title=\\"blog/authors.yml\\"\\nslorber:\\n name: S\xe9bastien Lorber\\n # the description will be displayed on the author\'s page\\n description: \'A freelance React and React-Native developer...\'\\n # highlight-next-line\\n page: true # Turns the feature on\\n```\\n\\nThis creates a [dedicated author page](/blog/authors/slorber) at `/blog/authors/slorber`.\\n\\n\\n\\nAn [authors index page](/blog/authors) is also created, listing all the blog authors.\\n\\n\\n\\nCheck the [blog authors pages guide](/docs/blog#authors-pages) for details.\\n\\n### Blog Feeds Styling\\n\\nIn [#9252](https://github.com/facebook/docusaurus/pull/9252), we added support for [styling your blog feeds](https://darekkay.com/blog/rss-styling/) by providing custom XSLT `.xls` files for the RSS and Atom feeds. This allows browsers to render the feeds in a more visually appealing way, like a regular HTML page, instead of the default XML view.\\n\\n```js title=\\"website/docusaurus.config.js\\"\\nconst blogOptions = {\\n feedOptions: {\\n // highlight-start\\n xslt: {\\n rss: \'custom-rss.xsl\',\\n atom: \'custom-atom.xsl\',\\n },\\n // highlight-end\\n },\\n};\\n```\\n\\nWriting your own XSLT can be complex, but you can also use `xslt: true` to turn on the built-in style:\\n\\n```js title=\\"website/docusaurus.config.js\\"\\nconst blogOptions = {\\n feedOptions: {\\n // highlight-start\\n xslt: true,\\n // highlight-end\\n },\\n};\\n```\\n\\n\\n\\n### Blog Sidebar Grouping\\n\\nIn [#10252](https://github.com/facebook/docusaurus/pull/10252), we added support for grouping blog posts by years in the blog sidebar.\\n\\n\\n\\nThis feature is now turned on by default, but can be disabled with `themeConfig.blog.sidebar.groupByYear: false`.\\n\\n### Blog Consistency Options\\n\\nWe added new blog options to enforce recommended practices for your blog posts:\\n\\n#### `onInlineAuthors`\\n\\nWe believe large multi-blogs are easier to manage by using [global authors](/docs/blog#global-authors), declared in `authors.yml`. This notably permits to avoids duplicating author information across multiple blog posts, and now permits to generate [author pages](/docs/blog#authors-pages).\\n\\nIn [#10224](https://github.com/facebook/docusaurus/pull/10224), we added the `onInlineAuthors` option. Use `onInlineAuthors: \'throw\'` to forbid [inline authors](/docs/blog#inline-authors), and enforce a consistent usage of [global authors](/docs/blog#global-authors).\\n\\n#### `onUntruncatedBlogPosts`\\n\\nWe believe blog posts are better using [truncation markers](/docs/blog#blog-list) (`\x3c!-- truncate --\x3e` or `{/* truncate */}`). On paginated lists (blog home, tags pages, authors pages), this permits to render a more concise preview of the blog post instead of a full blog post.\\n\\nIn [#10375](https://github.com/facebook/docusaurus/pull/10375), we added the `onUntruncatedBlogPosts` option. Use `onUntruncatedBlogPosts: \'throw\'` to enforce a consistent usage of [truncation markers](/docs/blog#blog-list).\\n\\n## Translations\\n\\n- \uD83C\uDDEA\uD83C\uDDEA [#10339](https://github.com/facebook/docusaurus/pull/10339): Add Estonian theme translations.\\n- \uD83C\uDDEE\uD83C\uDDE9 [#10325](https://github.com/facebook/docusaurus/pull/10325): Add Indonesian theme translations.\\n- \uD83C\uDDEA\uD83C\uDDF8 [#10360](https://github.com/facebook/docusaurus/pull/10360): Improve Spanish theme translations.\\n- \uD83C\uDDE9\uD83C\uDDEA [#10235](https://github.com/facebook/docusaurus/pull/10235): Improve German theme translations.\\n- \uD83C\uDDE8\uD83C\uDDF3 [#10257](https://github.com/facebook/docusaurus/pull/10257): Improve Traditional Chinese (zh-Hant) theme translations.\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#10369](https://github.com/facebook/docusaurus/pull/10369): Add support for [pkg.pr.new](https://pkg.pr.new) continuous releases so that you can test any pull-request code in a StackBlitz playground.\\n- [#10376](https://github.com/facebook/docusaurus/pull/10376): Theme unlisted/draft banners are also shown in dev so that you don\'t forget to publish your content.\\n- [#10335](https://github.com/facebook/docusaurus/pull/10335): The Markdown top-level headings `# title` are automatically wrapped in `<header>` for consistency with front matter `title: Title`.\\n- [#10286](https://github.com/facebook/docusaurus/pull/10286): Allows Docusaurus plugins to self-disable by returning `null`.\\n- [#10241](https://github.com/facebook/docusaurus/pull/10241): Add support for [MDX processor `recmaPlugins` option](https://mdxjs.com/packages/mdx/#processoroptions) to modify the MDX Estree AST.\\n- [#10324](https://github.com/facebook/docusaurus/pull/10324): The docs autogenerated `_category_.json` accepts a new `description` property that gets displayed on generated index pages.\\n- [#10368](https://github.com/facebook/docusaurus/pull/10368): The CLI command `docusaurus --version` now actually returns the Docusaurus version.\\n- [#10240](https://github.com/facebook/docusaurus/pull/10240): Markdown `mdx-code-block` now supports indentation.\\n- [#10219](https://github.com/facebook/docusaurus/pull/10219): Fix `<TabItem lazy>` support the for `className` prop.\\n- [#10313](https://github.com/facebook/docusaurus/pull/10313): Blog-related `@docusaurus/theme-common/internal` APIs have been moved to `@docusaurus/plugin-content-blog/client`.\\n- [#10316](https://github.com/facebook/docusaurus/pull/10316): Docs-related `@docusaurus/theme-common/internal` APIs have been moved to `@docusaurus/plugin-content-docs/client`.\\n\\nCheck the **[3.5.0 changelog entry](/changelog/3.5.0)** for an exhaustive list of changes."},{"id":"/releases/3.4","metadata":{"permalink":"/blog/releases/3.4","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/3.4/index.mdx","source":"@site/blog/releases/3.4/index.mdx","title":"Docusaurus 3.4","description":"We are happy to announce Docusaurus 3.4.","date":"2024-05-31T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":3.045,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 3.4","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2024-05-31T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 3.5","permalink":"/blog/releases/3.5"},"nextItem":{"title":"Docusaurus 3.3","permalink":"/blog/releases/3.3"}},"content":"We are happy to announce **Docusaurus 3.4**.\\n\\nUpgrading should be easy. Our [release process](/community/release-process) respects [Semantic Versioning](https://semver.org/). Minor versions do not include any breaking changes.\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\n## Highlights\\n\\n### Tags files\\n\\nThe docs and blog plugins both already supported a `tags` front matter attribute, enabling you to group related content. But tags declared inline in the front matter are not always ideal.\\n\\nWith [#10137](https://github.com/facebook/docusaurus/pull/10137), you can now declare a list of pre-defined tags in a `tags.yml` file:\\n\\n```yml title=\\"blog/tags.yml\\"\\ntag1:\\n label: \'Tag 1\'\\n description: \'Tag 1 description\'\\n permalink: /tag-1-permalink\\n\\ntag2:\\n label: \'Tag 2\'\\n description: \'Tag 2 description\'\\n permalink: /tag-2-permalink\\n```\\n\\nThese predefined tags can be used in the front matter of your blog or docs files:\\n\\n```md title=\\"blog/2024-05-31-my-blog-post.md\\"\\n---\\ntags: [tag1, tag2]\\n---\\n\\n# Title\\n\\nContent\\n```\\n\\n:::tip Keeping tags usage consistent\\n\\nUse the new `onInlineTags: \'throw\'` plugin option to enforce the usage of predefined tags and prevent contributors from creating new unwanted tags.\\n\\n:::\\n\\n### Hash Router - Experimental\\n\\nWith [9859](https://github.com/facebook/docusaurus/pull/9859), we added a new **experimental** hash router config option, useful for **offline browsing** by opening your site locally through the `file://` protocol.\\n\\n```tsx title=\\"docusaurus.config.js\\"\\nexport default {\\n future: {\\n experimental_router: \'hash\',\\n },\\n};\\n```\\n\\n:::warning\\n\\nThis mode is **not recommended for sites deployed through a web server**.\\n\\n:::\\n\\nWhen this mode is turned on, Docusaurus will opt out of static site rendering, and build a client-side single page application where all routes are prefixed with `/#/`. A single `index.html` file is generated. This file can be opened locally in your browser by simply clicking it, using the browser `file://` protocol. This makes it possible to distribute a Docusaurus site as a `.zip` file so that readers can browse it offline, without having to install anything complex on their computer apart a web browser.\\n\\n\\n\\nTry browsing our own Docusaurus site built with the hash router:\\n\\n- [Docusaurus website - Hash Router web deployment](https://facebook.github.io/docusaurus/#/)\\n- [Docusaurus website - Hash Router downloadable GitHub artifacts](https://github.com/facebook/docusaurus/actions/workflows/build-hash-router.yml)\\n\\n:::caution Experimental\\n\\nThis feature is **experimental**. If you try it out, please let us know how it works for you [here](https://github.com/facebook/docusaurus/issues/3825).\\n\\n:::\\n\\n### Site Storage - Experimental\\n\\nDocusaurus uses the browser `localStorage` API to persist UI state.\\n\\nBut sometimes the storage space is \\"shared\\" between multiple sites using the same domain, leading to **storage key conflicts**. This generally happens in two cases\\n\\n- when working on multiple `http://localhost:3000` sites\\n- when hosting multiple sites under the same domain: `https://example.com/site1/` and `https://example.com/site2/`\\n\\nFor this reason, we introduced a new **experimental** `siteStorage` configuration option:\\n\\n```tsx\\nexport default {\\n future: {\\n experimental_storage: {\\n type: \'localStorage\',\\n namespace: true,\\n },\\n },\\n};\\n```\\n\\nWhen `namespace: true` is set, we apply a hash suffix to all the storage keys, making them unique to the current site (based on `config.url` and `config.baseUrl`. For example, the `theme` storage key becomes `theme-x6f`. It is also possible to provide your own custom suffix `namespace: \'suffix\'`. We also made it possible to use `type: \'sessionStorage\'` instead of the default `localStorage`.\\n\\n:::caution Experimental\\n\\nThis feature is **experimental**. If you try it out, please let us know how it works for you [here](https://github.com/facebook/docusaurus/pull/10121).\\n\\n:::\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#10151](https://github.com/facebook/docusaurus/pull/10151): add Turkmen (tk) theme translations\\n- [#10111](https://github.com/facebook/docusaurus/pull/10111): add Bulgarian (bg) theme translations\\n- [#10168](https://github.com/facebook/docusaurus/pull/10168): fix many long overdue Markdown link resolution bugs\\n- [#10178](https://github.com/facebook/docusaurus/pull/10178): the `/search` page now respects the `contextualSearch: false` setting\\n- [#10118](https://github.com/facebook/docusaurus/pull/10118): fix bad pluralization on docs generated index category card description\\n- [#10130](https://github.com/facebook/docusaurus/pull/10130): fix false positives reported by the broken anchor checker due to trailing slashes\\n\\nCheck the **[3.4.0 changelog entry](/changelog/3.4.0)** for an exhaustive list of changes."},{"id":"/releases/3.3","metadata":{"permalink":"/blog/releases/3.3","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/3.3/index.mdx","source":"@site/blog/releases/3.3/index.mdx","title":"Docusaurus 3.3","description":"We are happy to announce Docusaurus 3.3.","date":"2024-05-03T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":2.56,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 3.3","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2024-05-03T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 3.4","permalink":"/blog/releases/3.4"},"nextItem":{"title":"Docusaurus 3.2","permalink":"/blog/releases/3.2"}},"content":"We are happy to announce **Docusaurus 3.3**.\\n\\nUpgrading should be easy. Our [release process](/community/release-process) respects [Semantic Versioning](https://semver.org/). Minor versions do not include any breaking changes.\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\nimport BrowserWindow from \'@site/src/components/BrowserWindow\';\\nimport IframeWindow from \'@site/src/components/BrowserWindow/IframeWindow\';\\n\\n## Highlights\\n\\n### Prepare for React 19\\n\\nThe React core team recently [released the first **React 19 beta**](https://react.dev/blog/2024/04/25/react-19). They also [published an upgrade guide and a **React v18.3 release**](https://react.dev/blog/2024/04/25/react-19-upgrade-guide) with new warnings to help us identify issues **before upgrading to React 19**.\\n\\nDocusaurus v3 depends on React `18.x`. When initializing a new Docusaurus sites, it will use that new React `18.3` release. It\'s also the case if you decide to upgrade your dependencies, or re-generate your package manager lockfile.\\n\\nIt turns out in its current state, **Docusaurus had a few of those extra warnings to fix**, notably this one immediately appearing on your dev console on any page load and navigation:\\n\\n> Warning: LoadableComponent uses the legacy contextTypes API which is no longer supported and will be removed in the next major release. Use React.createContext() with static contextType instead.\\n\\nIn [#10079](https://github.com/facebook/docusaurus/pull/10079), we got Docusaurus ready for React 19. We fixed all the React 18.3 warnings we encountered. In case we missed any, don\'t hesitate to [**report new warnings**](https://github.com/facebook/docusaurus/issues/10099) if you see them, to us but also to other Docusaurus third-party plugin authors.\\n\\n### `createSitemapItems`\\n\\nIn [#10083](https://github.com/facebook/docusaurus/pull/10083), we introduced a new flexible `createSitemapItems()` hook to the sitemap plugin. This enables users to create/filter/transform/enhance the sitemap items with their own custom logic.\\n\\n```ts\\nexport default {\\n presets: [\\n [\\n \'@docusaurus/preset-classic\',\\n {\\n sitemap: {\\n // highlight-start\\n createSitemapItems: async ({\\n defaultCreateSitemapItems,\\n ...params\\n }) => {\\n const items = await defaultCreateSitemapItems(params);\\n return items.filter((item) => !item.url.includes(\'/tags/\'));\\n },\\n // highlight-end\\n },\\n },\\n ],\\n ],\\n};\\n```\\n\\n### Pages plugin improvements\\n\\nThe Docusaurus [pages plugin](/docs/api/plugins/@docusaurus/plugin-content-pages) has historically been lagging behind the docs and blog plugins in terms of available feature.\\n\\nIn [#10032](https://github.com/facebook/docusaurus/pull/10032) we normalized the options available on each core content plugins by adding a few the missing page plugins APIs related to the edit url and the last update metadata displayed at the bottom on Markdown pages.\\n\\n```js\\nexport default {\\n presets: [\\n [\\n \'@docusaurus/preset-classic\',\\n {\\n pages: {\\n // highlight-start\\n editUrl:\\n \'https://github.com/facebook/docusaurus/tree/main/website/src/pages\',\\n editLocalizedFiles: true,\\n showLastUpdateAuthor: true,\\n showLastUpdateTime: true,\\n // highlight-end\\n },\\n },\\n ],\\n ],\\n};\\n```\\n\\n<IframeWindow url=\\"/examples/markdownPageExample\\" />\\n\\n:::note Only for Markdown pages\\n\\nThese new plugin options only apply to Markdown pages, and have no effect on React pages for which you have full control over the layout with JSX.\\n\\n:::\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#10064](https://github.com/facebook/docusaurus/pull/10064): new site config option `siteConfig.markdown.anchors.maintainCase`\\n- [#9767](https://github.com/facebook/docusaurus/pull/9767): new `docusaurus deploy --target-dir` option\\n- [#10042](https://github.com/facebook/docusaurus/pull/10042): new (experimental) plugin API: `route.props`\\n- [#10060](https://github.com/facebook/docusaurus/pull/10060): optimizes the App entrypoint, avoid useless re-renders on navigations\\n- [#10080](https://github.com/facebook/docusaurus/pull/10080): `<Admonition>` component can render properly without heading/icon\\n- [#10091](https://github.com/facebook/docusaurus/pull/10091): `<Tabs>` props can now override defaults\\n- [#10090](https://github.com/facebook/docusaurus/pull/10090): `docusaurus serve` works better with a `/baseUrl/` pathname prefix\\n- [#10070](https://github.com/facebook/docusaurus/pull/10070): add missing theme translations for `pt-BR`\\n- [#10025](https://github.com/facebook/docusaurus/pull/10025): doc sidebar item label now impacts the doc pagination label\\n\\nCheck the **[3.3.0 changelog entry](/changelog/3.3.0)** for an exhaustive list of changes."},{"id":"/releases/3.2","metadata":{"permalink":"/blog/releases/3.2","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/3.2/index.mdx","source":"@site/blog/releases/3.2/index.mdx","title":"Docusaurus 3.2","description":"We are happy to announce Docusaurus 3.2.","date":"2024-03-29T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":3.475,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 3.2","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2024-03-29T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 3.3","permalink":"/blog/releases/3.3"},"nextItem":{"title":"Docusaurus 3.1","permalink":"/blog/releases/3.1"}},"content":"We are happy to announce **Docusaurus 3.2**.\\n\\nThe upgrade should be easy: as explained in our [release process documentation](/community/release-process), minor versions respect [Semantic Versioning](https://semver.org/).\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\nimport BrowserWindow from \'@site/src/components/BrowserWindow\';\\nimport IframeWindow from \'@site/src/components/BrowserWindow/IframeWindow\';\\nimport ErrorBoundaryTestButton from \'@site/src/components/ErrorBoundaryTestButton\';\\n\\n## Highlights\\n\\n### Faster builds\\n\\nWe worked hard to reduce the time it takes to build a Docusaurus site in production mode.\\n\\nBetween v3.1.0 and v3.2.0, several changes have been made, leading to significantly faster production builds for many sites.\\n\\nLet\'s take an example. Our benchmark on the [React Native website upgrading to v3.2](https://github.com/facebook/react-native-website/pull/4072) reports the following results:\\n\\n- \uD83D\uDD25 Cold builds: 95s \u27A1\uFE0F 66s (~30% faster)\\n- \uD83D\uDD25 Incremental builds: 55s \u27A1\uFE0F 22s (~60% faster)\\n\\nThe results will vary depending on your site\'s topology and the options you turned on, but we expect the largest sites will see the most significant improvements.\\n\\nNote that this is only the beginning, and Docusaurus performance can still be significantly improved, notably the bundling time and the memory consumption. Track our [performance issue](https://github.com/facebook/docusaurus/issues/4765) for upcoming improvements.\\n\\n<details>\\n <summary>What is the difference between a cold build and an incremental build?</summary>\\n\\nA cold build is when the Docusaurus caches are empty, generally after running `docusaurus clear`.\\n\\nAn incremental build happens when you run another time the `docusaurus build` command. Docusaurus automatically tries to \\"re-use\\" computations from former builds to make subsequent builds faster. In practice it\'s based on [Webpack persistent caching](https://webpack.js.org/guides/build-performance/#persistent-cache). To enable incremental builds on your CI server, you can persist the `node_modules/.cache` folder across builds.\\n\\n</details>\\n\\n### Faster Dev Server\\n\\nWe also worked on improving the performance of the dev server, so that you can get a faster feedback when editing Markdown/MDX files.\\n\\nThe way we initially implemented content reloading wasn\'t great. For example, editing a blog post file would also trigger a useless reload of the unrelated docs plugin. From now on, when editing a plugin\'s content, only that plugin will reload. It\'s hard to measure precisely the impact of this change, but I estimate edits should appear in your browser at least 50% faster \uD83D\uDD25.\\n\\nWe plan to keep improving the speed of our dev server, with even more granular hot reloads, ensuring we don\'t run useless computations that would always keep giving the same result.\\n\\n### MDX partials table-of-contents\\n\\nWith [#9684](https://github.com/facebook/docusaurus/pull/9684), Docusaurus is now able to render headings coming from an imported partial into the table-of-contents.\\n\\nDocusaurus and MDX allows you to [import one Markdown file into another](/docs/markdown-features/react#importing-markdown). We usually call the imported Markdown file a \\"partial\\", and use the `_` prefix so that this file does not lead to the creation of a new page.\\n\\n```md title=\\"myDoc.mdx\\"\\n# My Doc\\n\\n## Doc heading\\n\\nContent is imported from another MDX file:\\n\\nimport ImportedDoc from \'./\\\\_importedDoc.mdx\';\\n\\n<ImportedDoc />\\n```\\n\\n```md title=\\"_myPartial.mdx\\"\\n## Partial heading\\n\\nSome paragraph\\n```\\n\\nPreviously, the heading `Partial heading` did not appear in the table-of-contents, but now it will!\\n\\n### Blog improvements\\n\\nWe improved the blog plugin with several new options to make it even more powerful and flexible:\\n\\n- [#9912](https://github.com/facebook/docusaurus/pull/9912): you can now display the last update time and author of a blog post, a feature the docs plugin already had.\\n- [#9886](https://github.com/facebook/docusaurus/pull/9886): a new `processBlogPosts` option allow you to filter/transform/sort blog posts.\\n- [#9838](https://github.com/facebook/docusaurus/pull/9838): a new `pageBasePath` option allows you to customize the blog pagination URL segment (`/blog/page/2`)\\n\\n### Sitemap lastmod\\n\\nWith [#9954](https://github.com/facebook/docusaurus/pull/9954), the sitemap plugin has a new `lastmod` option that can now emit a `<lastmod>` tag on the XML. The value is read from the Git history by default, but can be overridden with docs and blog `last_update` front matter.\\n\\nWe also made it possible to opt-out of emitting `<priority>` and `<frequency>` tags, which are generally ignored by crawlers (notably [Google](https://developers.google.com/search/blog/2023/06/sitemaps-lastmod-ping)).\\n\\nWe recommend using the following sitemap plugin config, that will become the default in Docusaurus V4:\\n\\n```js\\n{\\n lastmod: \'date\',\\n priority: null,\\n changefreq: null,\\n}\\n```\\n\\n## Other changes\\n\\n- [#9687](https://github.com/facebook/docusaurus/pull/9687): new Vercel Analytics plugin\\n- [#9681](https://github.com/facebook/docusaurus/pull/9681) and [#9442](https://github.com/facebook/docusaurus/pull/9442): `docusaurus swizzle` and `create-docusaurus` CLIs now ask users if they prefer to use TypeScript\\n- [#9928](https://github.com/facebook/docusaurus/pull/9928): new Icelandic translation\\n- [#9928](https://github.com/facebook/docusaurus/pull/9931): new `allContentLoaded` plugin lifecycle (experimental)\\n\\nCheck the **[3.2.0 changelog entry](/changelog/3.2.0)** for an exhaustive list of changes."},{"id":"/releases/3.1","metadata":{"permalink":"/blog/releases/3.1","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/3.1/index.mdx","source":"@site/blog/releases/3.1/index.mdx","title":"Docusaurus 3.1","description":"We are happy to announce Docusaurus 3.1.","date":"2024-01-05T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":1.665,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 3.1","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2024-01-05T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 3.2","permalink":"/blog/releases/3.2"},"nextItem":{"title":"Announcing Docusaurus 3.0","permalink":"/blog/releases/3.0"}},"content":"We are happy to announce **Docusaurus 3.1**.\\n\\nThe upgrade should be easy: as explained in our [release process documentation](/community/release-process), minor versions respect [Semantic Versioning](https://semver.org/).\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\nimport BrowserWindow from \'@site/src/components/BrowserWindow\';\\nimport IframeWindow from \'@site/src/components/BrowserWindow/IframeWindow\';\\nimport ErrorBoundaryTestButton from \'@site/src/components/ErrorBoundaryTestButton\';\\n\\n## Highlights\\n\\n### Broken anchors checker\\n\\nIn [#9528](https://github.com/facebook/docusaurus/pull/9528), we improved the built-in broken links checker to also detect broken anchors.\\n\\n\\n\\n:::tip[Make it fail fast]\\n\\nThe new [`onBrokenAnchors`](/docs/api/docusaurus-config#onBrokenAnchors) option has value `warn` by default, for retro-compatibility reasons.\\n\\nWe recommend to turn it to `throw` and fail your CI builds instead of deploying broken anchors to productions.\\n\\n:::\\n\\n:::note\\n\\nFor users and plugin authors implementing custom `<Heading>` and `<Link>` components, we provide a new [`useBrokenLinks`](/docs/docusaurus-core#useBrokenLinks) React hook API.\\n\\n**Most Docusaurus users don\'t need to care about it**, built-in components (`docusaurus/Link` and `@theme/Heading`) already use it internally.\\n\\n:::\\n\\n### `parseFrontMatter` hook\\n\\nIn [#9624](https://github.com/facebook/docusaurus/pull/9624), we added a new [`siteConfig.markdown.parseFrontMatter` function hook](/docs/api/docusaurus-config#markdown).\\n\\nThis makes it possible to implement convenient front matter transformations, shortcuts, or to integrate with external systems using front matter that Docusaurus plugins do not support.\\n\\n```js title=\\"docusaurus.config.js\\"\\nexport default {\\n markdown: {\\n // highlight-start\\n parseFrontMatter: async (params) => {\\n // Reuse the default parser\\n const result = await params.defaultParseFrontMatter(params);\\n\\n // Process front matter description placeholders\\n result.frontMatter.description =\\n result.frontMatter.description?.replaceAll(\'{{MY_VAR}}\', \'MY_VALUE\');\\n\\n // Create your own front matter shortcut\\n if (result.frontMatter.i_do_not_want_docs_pagination) {\\n result.frontMatter.pagination_prev = null;\\n result.frontMatter.pagination_next = null;\\n }\\n\\n // Rename an unsupported front matter coming from another system\\n if (result.frontMatter.cms_seo_summary) {\\n result.frontMatter.description = result.frontMatter.cms_seo_summary;\\n delete result.frontMatter.cms_seo_summary;\\n }\\n\\n return result;\\n },\\n // highlight-end\\n },\\n};\\n```\\n\\nRead the [front matter guide](/docs/markdown-features#front-matter) and the [`parseFrontMatter` API ref](/docs/api/docusaurus-config#markdown) for details.\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#9674](https://github.com/facebook/docusaurus/pull/9674): add `siteConfig.markdown.remarkRehypeOptions` to pass options to `remark-rehype`, letting you customize things such as MDX footnote label\\n- [#9671](https://github.com/facebook/docusaurus/pull/9671): add code block MagicComments support for (Visual) Basic/Batch/Fortran/COBOL/ML\\n- [#9610](https://github.com/facebook/docusaurus/pull/9610): enable CLI port configuration via `PORT` environment variable\\n- [#9477](https://github.com/facebook/docusaurus/pull/9477): complete Brazilian Portuguese (pt-BR) translations\\n\\nCheck the **[3.1.0 changelog entry](/changelog/3.1.0)** for an exhaustive list of changes."},{"id":"/releases/3.0","metadata":{"permalink":"/blog/releases/3.0","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/3.0/index.mdx","source":"@site/blog/releases/3.0/index.mdx","title":"Announcing Docusaurus 3.0","description":"Today, we are happy to announce Docusaurus 3.0! \uD83E\uDD73","date":"2023-10-31T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":10.515,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Announcing Docusaurus 3.0","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2023-10-31T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 3.1","permalink":"/blog/releases/3.1"},"nextItem":{"title":"Preparing your site for Docusaurus v3","permalink":"/blog/preparing-your-site-for-docusaurus-v3"}},"content":"Today, we are happy to **announce Docusaurus 3.0**! \uD83E\uDD73\\n\\nAt [**Meta Open Source**](https://opensource.fb.com/), we believe Docusaurus will help you build the **best documentation websites** with **minimal effort**, letting you **focus on what really matters**: writing the content.\\n\\nThis is a new **major version** of Docusaurus, coming with **new exciting features** and upgraded dependencies.\\n\\nIn line with the [**Semantic Versioning**](https://semver.org/) principles, this release includes **breaking changes** we documented thoroughly in the [**v3 upgrade guide**](/docs/migration/v3/). Breaking changes can be bothersome, but they are necessary to set the ground for a **new wave of Docusaurus features** we plan to implement.\\n\\n\\n\\n{/* truncate */}\\n\\nWe initially planned to release more frequent major versions, but Docusaurus v3 has taken longer than expected. Among the breaking changes that we accrued, **upgrading to MDX v3** is probably the main challenge to the adoption of this new version. We went the extra mile to make this upgrade as easy as possible, notably by adding [compatibility options for MDX v1](/docs/api/docusaurus-config#markdown).\\n\\nThe simplest sites will only need to upgrade a few npm dependencies. For more complex sites, we came up with a few strategies that can help you upgrade more confidently:\\n\\n- [Prepare your site](/blog/preparing-your-site-for-docusaurus-v3) ahead of time, incrementally, while staying on Docusaurus v2\\n- [Set up visual regression tests](/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing) to catch unexpected visual changes happening during the upgrade\\n\\n:::info About Docusaurus v2\\n\\nAccording to our [release process](/community/release-process#stable-version), Docusaurus v2 has now entered **maintenance mode**. It will only receive support for major security issues for 3 months, until 31 January 2024. It is recommended to upgrade within that time frame to v3.\\n\\n:::\\n\\nimport IframeWindow from \'@site/src/components/BrowserWindow/IframeWindow\';\\n\\n## Breaking changes\\n\\nThis section only gives you a quick glance. All the breaking changes are thoroughly documented in the [**v3 upgrade guide**](/docs/migration/v3).\\n\\nDocusaurus v3 upgraded a few dependencies to new major versions, each coming with its own breaking changes:\\n\\n- Node.js v16 \u27A1\uFE0F v18\\n- React v17 \u27A1\uFE0F v18\\n- MDX v1 \u27A1\uFE0F v3\\n- TypeScript v4 \u27A1\uFE0F v5\\n- prism-react-renderer v1 \u27A1\uFE0F v2\\n- react-live v2 \u27A1\uFE0F v4\\n- Mermaid v9 \u27A1\uFE0F v10\\n- import-fresh v3 \u27A1\uFE0F jiti v1\\n- remark-emoji v2 \u27A1\uFE0F v4\\n\\nA typical `package.json` dependency upgrade looks like:\\n\\n```diff title=\\"package.json\\"\\n {\\n \\"dependencies\\": {\\n // upgrade to Docusaurus v3\\n- \\"@docusaurus/core\\": \\"2.4.3\\",\\n- \\"@docusaurus/preset-classic\\": \\"2.4.3\\",\\n+ \\"@docusaurus/core\\": \\"3.0.0\\",\\n+ \\"@docusaurus/preset-classic\\": \\"3.0.0\\",\\n // upgrade to MDX v3\\n- \\"@mdx-js/react\\": \\"^1.6.22\\",\\n+ \\"@mdx-js/react\\": \\"^3.0.0\\",\\n // upgrade to prism-react-renderer v2.0+\\n- \\"prism-react-renderer\\": \\"^1.3.5\\",\\n+ \\"prism-react-renderer\\": \\"^2.1.0\\",\\n // upgrade to React v18.0+\\n- \\"react\\": \\"^17.0.2\\",\\n- \\"react-dom\\": \\"^17.0.2\\"\\n+ \\"react\\": \\"^18.2.0\\",\\n+ \\"react-dom\\": \\"^18.2.0\\"\\n },\\n \\"devDependencies\\": {\\n // upgrade Docusaurus dev dependencies to v3\\n- \\"@docusaurus/module-type-aliases\\": \\"2.4.3\\",\\n- \\"@docusaurus/types\\": \\"2.4.3\\"\\n+ \\"@docusaurus/module-type-aliases\\": \\"3.0.0\\",\\n+ \\"@docusaurus/types\\": \\"3.0.0\\"\\n }\\n \\"engines\\": {\\n // require Node.js 18.0+\\n- \\"node\\": \\">=16.14\\"\\n+ \\"node\\": \\">=18.0\\"\\n }\\n }\\n```\\n\\nApart from MDX v3, most breaking changes coming with those upgraded dependencies have been handled internally for you: most of the time, you shouldn\'t have to do anything. Outside of dependencies, the only functional breaking changes coming explicitly from the Docusaurus codebase are:\\n\\n- [#9189](https://github.com/facebook/docusaurus/pull/9189): new default blog RSS feed limit of 20 entries\\n- [#9308](https://github.com/facebook/docusaurus/pull/9308): fix and re-introduce the `:::warning` admonition, deprecate `:::caution`\\n- [#9310](https://github.com/facebook/docusaurus/pull/9310): remove the legacy versioned sidebar id prefix, used for sites versioned before `v2.0.0-beta.10` (December 2021)\\n- [#7966](https://github.com/facebook/docusaurus/pull/7966): refactor docs theme components, eventually requiring to you re-swizzle them\\n\\n## Highlights\\n\\nBelow is a non-exhaustive list of new useful features coming with this new version. All the features are listed in the [**Docusaurus v3.0.0 release notes**](https://github.com/facebook/docusaurus/releases/tag/v3.0.0).\\n\\n### Markdown\\n\\nDocusaurus v3 upgraded from MDX v1 to MDX v3:\\n\\n- in [#8288](https://github.com/facebook/docusaurus/pull/8288), we upgraded to [**MDX v2**](https://mdxjs.com/blog/v2/) ([migration guide](https://mdxjs.com/migrating/v2/))\\n- in [#9451](https://github.com/facebook/docusaurus/pull/9451), we upgraded to [**MDX v3**](https://mdxjs.com/blog/v3/) ([migration guide](https://mdxjs.com/migrating/v3/))\\n\\nThis new MDX version is **much better for content writers and plugin authors**, and lays the ground for implementing new exciting Markdown features.\\n\\n:::warning MDX v3 - the main challenge\\n\\nThe transition from MDX v1 to MDX v3 is the **main challenge** to the adoption of Docusaurus v3.\\n\\nSome documents that compiled successfully under Docusaurus v2 might now **fail to compile** under Docusaurus v3, while others might **render differently**.\\n\\nMost breaking changes come from [MDX v2](https://mdxjs.com/blog/v2/), and [MDX v3](https://mdxjs.com/blog/v3/) is a relatively small release. The [MDX v2 migration guide](https://mdxjs.com/migrating/v2/) has a section on how to [update MDX files](https://mdxjs.com/migrating/v2/#update-mdx-files) that will be particularly relevant to us. Also make sure to read the [Troubleshooting MDX](https://mdxjs.com/docs/troubleshooting-mdx/) page that can help you interpret common MDX error messages.\\n\\n**Don\'t be intimidated**. Most problems are **easy to fix** and often related to `{` and `<` characters that you now need to escape. However, depending on the size of your site, you might need to edit many files and feel overwhelmed. For this reason, we provide a command [`npx docusaurus-mdx-checker`](https://github.com/slorber/docusaurus-mdx-checker) to help you get an estimate of the work to be done, and we recommend to [prepare your site in advance](/blog/preparing-your-site-for-docusaurus-v3).\\n\\nIf you created custom [MDX plugins](/docs/markdown-features/plugins) (Remark/Rehype), the AST is slightly different, and you might need to refactor them.\\n\\n:::\\n\\nThis notably enables us to add a [CommonMark mode](/docs/markdown-features#mdx-vs-commonmark) that should make it easier for existing documentations to adopt Docusaurus. It is currently opt-in and **experimental** and limited ([some Docusaurus features will not work](https://github.com/facebook/docusaurus/issues/9092)). In Docusaurus v3, all files are still interpreted as MDX, but we plan to interpret `.md` files as CommonMark in an upcoming major version, and recommend to use the `.mdx` extension for any file using JSX or ES modules.\\n\\nWe also introduced a new way to [configure Markdown globally for your site](/docs/api/docusaurus-config#markdown), and plan to add more flexible options later.\\n\\n```js title=\\"docusaurus.config.js\\"\\nexport default {\\n markdown: {\\n format: \'mdx\',\\n mermaid: true,\\n preprocessor: ({filePath, fileContent}) => {\\n return fileContent.replaceAll(\'{{MY_VAR}}\', \'MY_VALUE\');\\n },\\n mdx1Compat: {\\n comments: true,\\n admonitions: true,\\n headingIds: true,\\n },\\n },\\n};\\n```\\n\\nDocusaurus now uses the [remark-directive](https://github.com/remarkjs/remark-directive) plugin to support admonitions. This also offers you the ability to create your own Remark plugins to extend Markdown with your own [custom directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) such as `:textDirective`, `::leafDirective` or `:::containerDirective`.\\n\\n### ESM and TypeScript configs {#esm-ts-configs}\\n\\nIn [#9317](https://github.com/facebook/docusaurus/pull/9317), we added support for ES Modules and TypeScript config files, including site config, docs sidebars, plugins and presets.\\n\\nHere are 2 TypeScript examples, giving you a modern experience with IDE autocompletion:\\n\\n```ts title=\\"docusaurus.config.ts\\"\\nimport type {Config} from \'@docusaurus/types\';\\nimport type * as Preset from \'@docusaurus/preset-classic\';\\n\\nconst config: Config = {\\n title: \'My Site\',\\n favicon: \'img/favicon.ico\',\\n // your site config ...\\n presets: [\\n [\\n \'classic\',\\n {\\n // your preset config ...\\n } satisfies Preset.Options,\\n ],\\n ],\\n themeConfig: {\\n // your theme config ...\\n } satisfies Preset.ThemeConfig,\\n};\\n\\nexport default config;\\n```\\n\\n```ts title=\\"sidebars.ts\\"\\nimport type {SidebarsConfig} from \'@docusaurus/plugin-content-docs\';\\n\\nconst sidebars: SidebarsConfig = {\\n docs: [\'introduction\'],\\n};\\n\\nexport default sidebars;\\n```\\n\\n### Unlisted content\\n\\nDocusaurus already supported a `draft: true` front matter option in our 3 content plugins (docs, blog, pages), which allows you to remove some pages from your production builds.\\n\\nIn [#8004](https://github.com/facebook/docusaurus/pull/8004), we introduced a new `unlisted: true` front matter option, which will keep your pages available in production builds, while \\"hiding\\" them and making them impossible to discover unless you have the url. This enables convenient workflows where you can easily ask for feedback on a piece of content before the final publication.\\n\\nUnlisted content will:\\n\\n- be excluded from `sitemap.xml`\\n- be excluded from SEO results thanks to `<meta name=\\"robots\\" content=\\"noindex, nofollow\\" />`\\n- be excluded from blog RSS feeds\\n- be excluded from Algolia DocSearch results\\n- be filtered from site navbar items, docs sidebars, blog sidebar, blog archives, tags pages...\\n\\nUnlisted content will also display a banner so that you don\'t forget to turn it off once your content is ready for prime time. Here\'s an example of an [unlisted blog post](/tests/blog/unlisted-post):\\n\\n<IframeWindow url=\\"/tests/blog/unlisted-post\\" />\\n\\n### React 18\\n\\nIn [#8961](https://github.com/facebook/docusaurus/pull/8961), we upgraded to React 18. This is important, notably for the [gradual adoption of Concurrent React features](https://react.dev/blog/2022/03/29/react-v18#gradually-adopting-concurrent-features), as well as upcoming exciting features such as [build-time React Server Components](https://github.com/facebook/docusaurus/issues/9089).\\n\\nThis new version of React should be a drop-in replacement for most Docusaurus sites. It comes with breaking changes that we handled internally in the Docusaurus codebase. If your site is using a lot of custom React code, we recommend you to take a look at the official article on [How to Upgrade to React 18](https://react.dev/blog/2022/03/08/react-18-upgrade-guide), notably the new [automatic batching](https://react.dev/blog/2022/03/08/react-18-upgrade-guide#automatic-batching) behavior.\\n\\n:::danger Experimental support for React 18 features\\n\\nReact 18 comes with new features:\\n\\n- `<Suspense>`\\n- `React.lazy()`\\n- `startTransition()`\\n\\nTheir Docusaurus support is considered as **experimental**. We might have to adjust the integration in the future, leading to a different runtime behavior.\\n\\n:::\\n\\n### Automatic JSX runtime\\n\\nDocusaurus now uses the [\\"automatic\\" JSX runtime](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html).\\n\\nIt is not needed anymore to import React in JSX files that do not use any React API.\\n\\n```diff title=\\"src/components/MyComponent.js\\"\\n- import React from \'react\';\\n\\n export default function MyComponent() {\\n return <div>Hello</div>;\\n }\\n```\\n\\n### Debug builds\\n\\nIt is now possible to build your static site in dev mode.\\n\\n```bash\\ndocusaurus build --dev\\n```\\n\\n:::tip Debug React-related problems\\n\\nDocusaurus will log more errors to the console, notably React 18 hydration errors through the new [`onRecoverableError` callback](https://react.dev/reference/react-dom/client/hydrateRoot#parameters).\\n\\nThis new build mode is particularly helpful for **troubleshooting React problems**. Docusaurus will use the development build of React, thus producing detailed and readable error messages instead of minified ones linking to the [React Error Decoder page](https://reactjs.org/docs/error-decoder.html/).\\n\\n:::\\n\\n### TypeScript\\n\\nDocusaurus v3 now requires a minimum version of TypeScript 5.0.\\n\\nWe re-internalized the base recommended TypeScript config to a new official package:\\n\\n```diff title=\\"tsconfig.json\\"\\n {\\n- \\"extends\\": \\"@tsconfig/docusaurus/tsconfig.json\\",\\n+ \\"extends\\": \\"@docusaurus/tsconfig\\",\\n \\"compilerOptions\\": {\\n \\"baseUrl\\": \\".\\"\\n }\\n }\\n```\\n\\nWe also have cleaner, normalized exports for Docusaurus core type, plugin, and preset options, which you can use within the brand-new [TypeScript config files](#esm-ts-configs):\\n\\n```ts title=\\"docusaurus.config.ts\\"\\nimport type {Config} from \'@docusaurus/types\';\\nimport type {Options, ThemeConfig} from \'@docusaurus/preset-classic\';\\nimport type {SidebarsConfig} from \'@docusaurus/plugin-content-docs\';\\n```\\n\\n### Code blocks\\n\\nIn [#9316](https://github.com/facebook/docusaurus/pull/9316), we improved on syntax highlighting thanks to the [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) v2 upgrade. For example, a bash param `--save` is now colored:\\n\\n```bash\\nnpm install --save some-package\\n```\\n\\nThe [interactive code editor](/docs/markdown-features/code-blocks#interactive-code-editor) also upgrades to [react-live](https://github.com/FormidableLabs/react-live) v4, coming with a new [sucrase](https://github.com/alangpierce/sucrase) compiler. It is faster, lighter, and supports modern features, notably TypeScript type annotations.\\n\\n```js live\\nfunction Hello() {\\n const name: string = \'World\';\\n return <div>Hello {name}</div>;\\n}\\n```\\n\\nIn [#8982](https://github.com/facebook/docusaurus/pull/8982) and [#8870](https://github.com/facebook/docusaurus/pull/8870), we also added [magic comments](/docs/markdown-features/code-blocks#custom-magic-comments) support for TeX-like, Haskell-like, and WebAssembly comment syntax.\\n\\n```haskell title=\\"haskell.hs\\"\\nstringLength :: String -> Int\\n-- highlight-next-line\\nstringLength [] = 0\\nstringLength (x:xs) = 1 + stringLength xs\\n```\\n\\n```matlab title=\\"matlab.m\\"\\n% highlight-start\\nfunction result = times2(n)\\n result = n * 2;\\nend\\n% highlight-end\\nx = 10;\\n% highlight-next-line\\ny = times2(x);\\n```\\n\\n### Mermaid diagrams\\n\\nIn [#9305](https://github.com/facebook/docusaurus/pull/9305), we upgraded to Mermaid v10.4 and added support for async diagram rendering. Docusaurus is now able to render new types of diagrams.\\n\\n<details>\\n <summary>Mindmap</summary>\\n\\n```mermaid\\nmindmap\\n root((mindmap))\\n Research\\n Creative techniques\\n Strategic planning\\n Argument mapping\\n Tools\\n Pen and paper\\n Mermaid\\n```\\n\\n</details>\\n\\n<details>\\n <summary>Quadrant chart</summary>\\n\\n```mermaid\\nquadrantChart\\n title Reach and engagement of campaigns\\n x-axis Low Reach --\x3e High Reach\\n y-axis Low Engagement --\x3e High Engagement\\n quadrant-1 We should expand\\n quadrant-2 Need to promote\\n quadrant-3 Re-evaluate\\n quadrant-4 May be improved\\n Campaign A: [0.3, 0.6]\\n Campaign B: [0.45, 0.23]\\n Campaign C: [0.57, 0.69]\\n Campaign D: [0.78, 0.34]\\n Campaign E: [0.40, 0.34]\\n Campaign F: [0.35, 0.78]\\n```\\n\\n</details>\\n\\n### Query-string data attributes\\n\\nIn [#9028](https://github.com/facebook/docusaurus/pull/9028), we made it possible to set custom HTML [data attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*) though `docusaurus-data-x` query-string parameters. This makes it easier to embed a Docusaurus iframe on another site, and lets you customize the appearance of the embedded version with CSS.\\n\\n```css title=\\"/src/css/custom.css\\"\\nhtml[data-navbar=\'false\'] .navbar {\\n display: none;\\n}\\n\\nhtml[data-red-border] div#__docusaurus {\\n border: red solid thick;\\n}\\n```\\n\\n<IframeWindow url=\\"/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border\\" />\\n\\n### Other features\\n\\nOther new features worth mentioning:\\n\\n- [#9189](https://github.com/facebook/docusaurus/pull/9189): new blog `feedOptions.limit` option\\n- [#9071](https://github.com/facebook/docusaurus/pull/9071): add normalized SEO front matter support for the pages plugin\\n- [#9171](https://github.com/facebook/docusaurus/pull/9028): the client-redirects plugin now supports fully qualified urls and query-string/hash in destination url\\n- [#9171](https://github.com/facebook/docusaurus/pull/9171): new ESLint rule [`no-html-links`](/docs/api/misc/@docusaurus/eslint-plugin/no-html-links)\\n- [#8384](https://github.com/facebook/docusaurus/pull/8384): new ESLint rule [`prefer-docusaurus-heading`](/docs/api/misc/@docusaurus/eslint-plugin/prefer-docusaurus-heading)\\n\\nRead [**Docusaurus v3.0.0 release notes**](https://github.com/facebook/docusaurus/releases/tag/v3.0.0) for an exhaustive list of changes.\\n\\n## Conclusion\\n\\nThis release comes with a few features, but more importantly **upgrades many pieces of the Docusaurus infrastructure**.\\n\\nThe **MDX upgrade** consumed a lot of our time this year, and we worked hard to make this important upgrade less difficult for all of you.\\n\\nNow that we\'ve caught up with our infrastructure, we\'ll be back **delivering useful documentation features** very soon, in upcoming minor versions.\\n\\nWe would like to thank you for using Docusaurus over the years. The documentation framework space is becoming more competitive lately, and we will do our best to ensure that Docusaurus remains a **competitive solution** that stands out for its great **flexibility**."},{"id":"/preparing-your-site-for-docusaurus-v3","metadata":{"permalink":"/blog/preparing-your-site-for-docusaurus-v3","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2023/09-29-preparing-your-site-for-docusaurus-v3/index.mdx","source":"@site/blog/2023/09-29-preparing-your-site-for-docusaurus-v3/index.mdx","title":"Preparing your site for Docusaurus v3","description":"This blog post was written when Docusaurus v3 was in beta. There are some changes in dependency versions and upgrade steps you should be aware of if upgrading to Docusaurus v3 current stable releases. Use the upgrade guide for the most up-to-date migration steps.","date":"2023-09-29T00:00:00.000Z","tags":[{"inline":false,"label":"Maintenance","permalink":"/blog/tags/maintenance"}],"readingTime":13.975,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Preparing your site for Docusaurus v3","authors":["slorber"],"tags":["maintenance"],"slug":"/preparing-your-site-for-docusaurus-v3","image":"./img/social-card.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Announcing Docusaurus 3.0","permalink":"/blog/releases/3.0"},"nextItem":{"title":"Upgrading frontend dependencies with confidence","permalink":"/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing"}},"content":":::warning\\n\\nThis blog post was written when Docusaurus v3 was in beta. There are some changes in dependency versions and upgrade steps you should be aware of if upgrading to Docusaurus v3 current stable releases. Use the [upgrade guide](https://docusaurus.io/docs/next/migration/v3) for the most up-to-date migration steps.\\n\\n:::\\n\\n**Docusaurus v3** is now [**in beta**](https://github.com/facebook/docusaurus/discussions/9312) and the official release is around the corner. This is the perfect time to start **preparing your site** for this new major version.\\n\\nDocusaurus v3 comes with a few **breaking changes**, many of which can be **handled today under Docusaurus v2**. Preparing your site ahead of time can be done incrementally, and will make it easier to upgrade to v3.\\n\\nThe main breaking change is the upgrade from MDX v1 to MDX v3. Read the [**MDX v2**](https://mdxjs.com/blog/v2/) and [**MDX v3**](https://mdxjs.com/blog/v3/) release notes for details. MDX will now compile your Markdown content **more strictly** and with **subtle differences**.\\n\\nThis article will mostly focus on how to prepare your content for this new MDX version, and will also list a few other breaking changes that you can handle today.\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\n:::warning\\n\\nThis article mentions most Docusaurus v3 breaking changes, but is not exhaustive. Read the [v3.0.0-beta.0 release notes](https://github.com/facebook/docusaurus/discussions/9312) for an exhaustive list.\\n\\n:::\\n\\n:::tip Don\'t be afraid\\n\\nThere\'s a lot of content in this blog post, but many Docusaurus v2 sites can upgrade with very few changes.\\n\\nIf your site is relatively small, with only a few customizations, you can probably [upgrade to Docusaurus v3](#try-docusaurus-v3-today) immediately.\\n\\n:::\\n\\n## Preparatory work\\n\\nBefore preparing for the Docusaurus v3 upgrade, we recommend upgrading to the latest [Docusaurus v2 version](/versions).\\n\\nDepending on the complexity of your site, it may be a good idea to adopt the [visual regression testing workflow](/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing) that we recently presented. It could help you catch unexpected visual side effects occurring during the Docusaurus v3 upgrade.\\n\\nWe also recommend using the `.mdx` extension whenever you use JSX, `import`, or `export` (i.e. MDX features) inside a Markdown file. It is semantically more correct and improves compatibility with external tools (IDEs, formatters, linters, etc.). In future versions of Docusaurus, `.md` files will be parsed as standard [CommonMark](https://commonmark.org/), which does not support these features. In Docusaurus v3, `.md` files keep being compiled as MDX files, but it will be possible to [opt-in for CommonMark](https://github.com/facebook/docusaurus/issues/3018).\\n\\n## Preparing content for MDX v3\\n\\nMDX is a major dependency of Docusaurus responsible for compiling your `.md` and `.mdx` files to React components.\\n\\nMDX v3 is much better, but also comes with changes that probably require you to refactor your content a bit. MDX v3 is stricter, and some components that compiled fine under v1 might now fail to compile under v3, most likely because of `{` and `<` characters.\\n\\nUpgrading MDX comes with all the breaking changes documented on the [MDX v2](https://mdxjs.com/blog/v2/) and [MDX v3](https://mdxjs.com/blog/v3/) release blog posts. Most breaking changes come from MDX v2. The [MDX v2 migration guide](https://mdxjs.com/migrating/v2/) has a section on how to [update MDX files](https://mdxjs.com/migrating/v2/#update-mdx-files) that will be particularly relevant to us. Also make sure to read the [Troubleshooting MDX](https://mdxjs.com/docs/troubleshooting-mdx/) page that can help you interpret common MDX error messages.\\n\\nMake sure to also read our updated [**MDX and React**](/docs/markdown-features/react) documentation page.\\n\\n:::tip Ask for help\\n\\nWe have a dedicated [MDX v3 - Upgrade Support](https://github.com/facebook/docusaurus/discussions/9053) discussion.\\n\\n:::\\n\\n### Using the MDX playground\\n\\nThe MDX playground is your new best friend. It permits to understand how your content is **compiled to React components**, and troubleshoot compilation or rendering issues in isolation.\\n\\nEach MDX version comes with its own playground:\\n\\n- [MDX playground - current version](https://mdxjs.com/playground/)\\n- [MDX playground - v1](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground/)\\n\\n<details>\\n <summary>Configuring the MDX playground options for Docusaurus</summary>\\n\\nTo obtain a compilation behavior similar to what Docusaurus v2 uses, please turn on these options on the [MDX playground](https://mdxjs.com/playground/):\\n\\n- Use `MDX`\\n- Use `remark-gfm`\\n- Use `remark-directive`\\n\\n\\n\\n</details>\\n\\nUsing the two MDX playgrounds side-by-side, you will soon notice that some content is compiled differently or fails to compile in v3.\\n\\n:::tip Making your content future-proof\\n\\nThe goal will be to refactor your problematic content so that it **works fine with both versions of MDX**. This way, when you upgrade to Docusaurus v3, this content will already work out-of-the-box.\\n\\n:::\\n\\n### Using the MDX checker CLI\\n\\nWe provide a [docusaurus-mdx-checker](https://github.com/slorber/docusaurus-mdx-checker) CLI that permits to easily spot problematic content. Run this command today on your Docusaurus v2 site to obtain a list of files that will fail to compile under MDX v3.\\n\\n```bash\\nnpx docusaurus-mdx-checker\\n```\\n\\nFor each compilation issue, the CLI will log the file path and a line number to look at.\\n\\n\\n\\n:::tip\\n\\nUse this CLI to estimate of how much work will be required to make your content compatible with MDX v3.\\n\\n:::\\n\\n:::warning\\n\\nThis CLI is a best effort, and will only report compilation errors.\\n\\nIt 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 [visual regression tests](/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing).\\n\\n:::\\n\\n### Common MDX problems\\n\\nWe upgraded a few Docusaurus sites to Docusaurus v3 and MDX v3:\\n\\n- [Docusaurus PR](https://github.com/facebook/docusaurus/pull/8288)\\n- [React-Native PR](https://github.com/facebook/react-native-website/pull/3780)\\n- [Jest PR](https://github.com/jestjs/jest/pull/14463)\\n\\nThese upgrades permitted us to aggregate the most common content problems, and document how to best handle them.\\n\\n#### Bad usage of `{`\\n\\nThe `{` character is used for opening [JavaScript expressions](https://mdxjs.com/docs/what-is-mdx/#expressions). MDX will now fail if what you put inside `{expression}` is not a valid expression.\\n\\n```md title=\\"example.md\\"\\nThe object shape looks like {username: string, age: number}\\n```\\n\\n:::danger Error message\\n\\n> Could not parse expression with acorn: Unexpected content after expression\\n\\n:::\\n\\n:::tip How to prepare\\n\\nAvailable options to fix this error:\\n\\n- Use inline code: `{username: string, age: number}`\\n- Use the HTML code: `{`\\n- Escape it: `\\\\{`\\n\\n:::\\n\\n#### Bad usage of `<`\\n\\nThe `<` character is used for opening [JSX tags](https://mdxjs.com/docs/what-is-mdx/#jsx). MDX will now fail if it thinks your JSX is invalid.\\n\\n```md title=\\"example.md\\"\\nUse Android version <5\\n\\nYou can use a generic type like Array<T>\\n\\nFollow the template \\"Road to <YOUR_MINOR_VERSION>\\"\\n```\\n\\n:::danger Error messages\\n\\n> Unexpected character `5` (U+0035) before name, expected a character that can start a name, such as a letter, `$`, or `_`\\n\\n> Expected a closing tag for `<T>` (1:6-1:9) before the end of `paragraph` end-tag-mismatch mdast-util-mdx-jsx\\n\\n> Expected a closing tag for `<YOUR_MINOR_VERSION>` (134:19-134:39) before the end of `paragraph`\\n\\n:::\\n\\n:::tip How to prepare\\n\\nAvailable options to fix this error:\\n\\n- Use inline code: `Array<T>`\\n- Use the HTML code: `<` or `<`\\n- Escape it: `\\\\<` (unfortunately the `\\\\` will be displayed under MDX v1)\\n\\n:::\\n\\n#### Bad usage of GFM Autolink\\n\\nDocusaurus supports [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/), but [autolink](https://github.github.com/gfm/#autolinks) using the `<link>` syntax is not supported anymore by MDX.\\n\\n```md title=\\"example.md\\"\\n<sebastien@thisweekinreact.com>\\n\\n<http://localhost:3000>\\n```\\n\\n:::danger Error messages\\n\\n> Unexpected character `@` (U+0040) in name, expected a name character such as letters, digits, `$`, or `_`; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use `[text](url)`)\\n\\n> Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`)\\n\\n:::\\n\\n:::tip How to prepare\\n\\nUse regular Markdown links, or remove the `<` and `>`. MDX and GFM are able to autolink literals already.\\n\\n{/* prettier-ignore */}\\n```md title=\\"example.md\\"\\nsebastien@thisweekinreact.com\\n[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)\\n\\nhttp://localhost:3000\\n[http://localhost:3000](http://localhost:3000)\\n```\\n\\n:::\\n\\n#### Lower-case MDXComponent mapping\\n\\nFor users providing a [custom `MDXComponent`mapping](/docs/markdown-features/react#mdx-component-scope), components are now \\"sandboxed\\":\\n\\n- a `MDXComponent` mapping for `h1` only gets used for `# hi` but not for `<h1>hi</h1>`\\n- a **lower-cased** custom element name will not be substituted by its respective `MDXComponent` component anymore\\n\\n:::danger visual difference\\n\\nYour [`MDXComponent` component mapping](/docs/markdown-features/react#mdx-component-scope) might not be applied as before, and your custom components might no longer be used.\\n\\n:::\\n\\n:::tip How to prepare\\n\\nFor native Markdown elements, you can keep using **lower-case**: `p`, `h1`, `img`, `a`...\\n\\nFor any other element, **use upper-case names**.\\n\\n```diff title=\\"src/theme/MDXComponents.js\\"\\n import MDXComponents from \'@theme-original/MDXComponents\';\\n\\n export default {\\n ...MDXComponents,\\n p: (props) => <p {...props} className=\\"my-paragraph\\"/>\\n- myElement: (props) => <div {...props} className=\\"my-class\\" />,\\n+ MyElement: (props) => <div {...props} className=\\"my-class\\" />,\\n };\\n```\\n\\n:::\\n\\n#### Unintended extra paragraphs\\n\\nIn MDX, it is now possible to interleave JSX and Markdown more easily without requiring extra line breaks. Writing content on multiple lines can also produce new expected `<p>` tags.\\n\\n:::danger visual difference\\n\\nSee how this content is rendered differently by MDX v1 and v3.\\n\\n```md title=\\"example.md\\"\\n<div>Some **Markdown** content</div>\\n<div>\\n Some **Markdown** content\\n</div>\\n```\\n\\n{/* prettier-ignore */}\\n```html title=\\"MDX v1 output\\"\\n<div>Some **Markdown** content</div>\\n<div>Some **Markdown** content</div>\\n```\\n\\n{/* prettier-ignore */}\\n```html title=\\"MDX v3 output\\"\\n<div>Some <strong>Markdown</strong> content</div>\\n<div><p>Some <strong>Markdown</strong> content</p></div>\\n```\\n\\n:::\\n\\n:::tip How to prepare\\n\\nIf you don\'t want an extra `<p>` tag, refactor content on a case by case basis to use a single-line JSX tag.\\n\\n```diff\\n <figure>\\n <img src=\\"/img/myImage.png\\" alt=\\"My alt\\" />\\n- <figcaption>\\n- My image caption\\n- </figcaption>\\n+ <figcaption>My image caption</figcaption>\\n </figure>\\n```\\n\\nIf your content contains \\"Markdown inlines\\" (`**`, `*`, `_`, `[link](/path)`), you might not be able to refactor it ahead of time, and will have to do it alongside the Docusaurus v3 upgrade.\\n\\n:::\\n\\n#### Unintended usage of directives\\n\\nDocusaurus v3 now uses [Markdown Directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) (implemented with [remark-directive](https://github.com/remarkjs/remark-directive)) as a generic way to provide support for admonitions, and other upcoming Docusaurus features.\\n\\n```md title=\\"example.md\\"\\nThis is a :textDirective\\n\\n::leafDirective\\n\\n:::containerDirective\\n\\nContainer directive content\\n\\n:::\\n```\\n\\n:::danger Visual change\\n\\nDirectives 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.\\n\\n```md title=\\"example.md\\"\\nThe AWS re:Invent conf is great\\n```\\n\\nDue to `:Invent` being parsed as a text directive, this will now be rendered as:\\n\\n```\\nThe AWS re\\nconf is great\\n```\\n\\n:::\\n\\n:::tip How to prepare\\n\\n- Use the HTML code: `:`\\n- Add a space after `:` (if it makes sense): `: text`\\n- Escape it: `\\\\:` (unfortunately the `\\\\` will be displayed under MDX v1)\\n\\n:::\\n\\n#### Unsupported indented code blocks\\n\\nMDX does not transform indented text as code blocks anymore.\\n\\n```md title=\\"example.md\\"\\n console.log(\\"hello\\");\\n```\\n\\n:::danger Visual change\\n\\nThe upgrade does not generally produce new MDX compilation errors, but can lead to content being rendered in an unexpected way because there isn\'t a code block anymore.\\n\\n:::\\n\\n:::tip How to prepare\\n\\nUse the regular code block syntax instead of indentation:\\n\\n````md title=\\"example.md\\"\\n```js\\nconsole.log(\'hello\');\\n```\\n````\\n\\n:::\\n\\n### MDX plugins\\n\\nAll the official packages (Unified, Remark, Rehype...) in the MDX ecosystem are now [**ES Modules only**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and do not support [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) anymore.\\n\\nIn practice this means that you can\'t do `require(\\"remark-plugin\\")` anymore.\\n\\n:::tip How to prepare\\n\\nDocusaurus v3 now supports [**ES Modules**](https://flaviocopes.com/es-modules/) configuration files. We recommend that you migrate your config file to ES module, that enables you to import the Remark plugins easily:\\n\\n```js title=\\"docusaurus.config.js\\"\\nimport remarkPlugin from \'remark-plugin\';\\n\\nexport default {\\n title: \'Docusaurus\',\\n /* site config using remark plugins here */\\n};\\n```\\n\\nIf 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 [Docusaurus config supports the usage of an async function](/docs/configuration#syntax-to-declare-docusaurus-config) to let you do so.\\n\\n```js title=\\"docusaurus.config.js\\"\\nmodule.exports = async function () {\\n const myPlugin = (await import(\'remark-plugin\')).default;\\n return {\\n // site config...\\n };\\n};\\n```\\n\\n:::\\n\\n:::info For plugin authors\\n\\nIf 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 [dedicated support discussion](https://github.com/facebook/docusaurus/discussions/9337) to help plugin authors upgrade their code.\\n\\n:::\\n\\n## Other breaking changes\\n\\nApart from MDX, there are other breaking changes that you can already prepare your site for, notably major version upgrades of important dependencies.\\n\\n### Node.js 18.0\\n\\nNode.js 16 [reached End-of-Life](https://nodejs.org/en/blog/announcements/nodejs16-eol), and Docusaurus v3 now requires **Node.js >= 18.0**.\\n\\n:::tip How to prepare\\n\\nUpgrade your Docusaurus v2 site to Node.js 18 before upgrading to Docusaurus v3.\\n\\n:::\\n\\n### React 18.0\\n\\nDocusaurus v3 now requires **React >= 18.0**.\\n\\nReact 18 comes with its own breaking changes that should be relatively easy to handle, depending on the amount of custom React code you created for your site.\\n\\nSimple Docusaurus sites that only use our official theme code without swizzling do not have anything to do.\\n\\n:::tip How to prepare\\n\\nRead the official [React v18.0](https://react.dev/blog/2022/03/29/react-v18) and [How to Upgrade to React 18](https://react.dev/blog/2022/03/08/react-18-upgrade-guide), and look at your first-party React code to figure out which components might be affected this React 18 upgrade.\\n\\nWe recommend to particularly look for:\\n\\n- Automatic batching for stateful components\\n- New React hydration errors reported to the console\\n\\n:::\\n\\n### TypeScript 5.0\\n\\nDocusaurus v3 now requires **TypeScript >= 5.0**.\\n\\n:::tip How to prepare\\n\\nUpgrade your Docusaurus v2 site to TypeScript 5 before upgrading to Docusaurus v3.\\n\\n:::\\n\\n### TypeScript base config\\n\\nThe official Docusaurus TypeScript config has been re-internalized from the external package [`@tsconfig/docusaurus`](https://www.npmjs.com/package/@tsconfig/docusaurus) to our new monorepo package [`@docusaurus/tsconfig`](https://www.npmjs.com/package/@docusaurus/tsconfig).\\n\\nThis new package is versioned alongside all the other Docusaurus core packages, and will be used to ensure TypeScript retro-compatibility and breaking changes on major version upgrades.\\n\\n:::tip How to prepare\\n\\nThe new Docusaurus v3 TypeScript config is sensibly the same as the former Docusaurus v2 TypeScript config. If you upgraded to TypeScript 5, using the Docusaurus v3 config on a v2 site is already possible:\\n\\n```diff title=\\"package.json\\"\\n {\\n \\"devDependencies\\": {\\n- \\"@tsconfig/docusaurus\\": \\"^1.0.7\\",\\n+ \\"@docusaurus/tsconfig\\": \\"^3.0.0-beta.0\\",\\n }\\n }\\n```\\n\\n```diff title=\\"tsconfig.json\\"\\n {\\n- \\"extends\\": \\"@tsconfig/docusaurus/tsconfig.json\\",\\n+ \\"extends\\": \\"@docusaurus/tsconfig\\",\\n \\"compilerOptions\\": {\\n \\"baseUrl\\": \\".\\"\\n }\\n }\\n```\\n\\n:::\\n\\n### Admonition warning\\n\\nFor historical reasons, we support an undocumented admonition `:::warning` that renders with a red color.\\n\\n:::danger Warning\\n\\nThis is a Docusaurus v2 `:::warning` admonition.\\n\\n:::\\n\\nHowever, the color and icon is historically wrong. Docusaurus v3 re-introduces `:::warning` admonition officially, documents it, and fix the color and icon.\\n\\n:::warning\\n\\nThis is a Docusaurus v3 `:::warning` admonition.\\n\\n:::\\n\\n:::tip How to prepare\\n\\nIf you previously used the undocumented `:::warning` admonition, make sure to verify for each usage if yellow is now an appropriate color. If you want to keep the red color, use `:::danger` instead.\\n\\nDocusaurus v3 also [deprecated the `:::caution`](https://github.com/facebook/docusaurus/pull/9308) admonition. Please refactor `:::caution` (yellow) to either `:::warning` (yellow) or `:::danger` (red).\\n\\n:::\\n\\n### Versioned sidebars\\n\\nThis breaking change will only affect **Docusaurus v2 early adopters** who versioned their docs before `v2.0.0-beta.10` (December 2021).\\n\\nWhen creating version `v1.0.0`, the sidebar file contained a prefix `version-v1.0.0/` that [Docusaurus v3 does not support anymore](https://github.com/facebook/docusaurus/pull/9310).\\n\\n```json title=\\"versioned_sidebars/version-v1.0.0-sidebars.json\\"\\n{\\n \\"version-v1.0.0/docs\\": [\\n \\"version-v1.0.0/introduction\\",\\n \\"version-v1.0.0/prerequisites\\"\\n ]\\n}\\n```\\n\\n:::tip How to prepare\\n\\nYour Docusaurus v2 site is able to handle the 2 sidebar formats similarly.\\n\\nYou can remove the useless versioned prefix from your versioned sidebars.\\n\\n```json title=\\"versioned_sidebars/version-v1.0.0-sidebars.json\\"\\n{\\n \\"docs\\": [\\"introduction\\", \\"prerequisites\\"]\\n}\\n```\\n\\n:::\\n\\n## Try Docusaurus v3 today {#try-docusaurus-v3-today}\\n\\nDocusaurus v3 is now [in beta](https://github.com/facebook/docusaurus/discussions/9312), and already used in production by [React-Native](https://reactnative.dev), [Jest](https://jestjs.io), and [our own website](https://docusaurus.io/).\\n\\nWe think this new Docusaurus version is **robust and ready to be deployed in production**. It should be released officially soon, after receiving a positive feedback from early adopters of our community.\\n\\nWe would really appreciate it if you try upgrading and report issues on the [3.0.0-beta.0 release discussion thread](https://github.com/facebook/docusaurus/discussions/9312).\\n\\nFor most sites, the upgrade should be easy. If you prepared your site ahead of time as documented here, upgrading the following dependencies should be enough:\\n\\n```diff title=\\"package.json\\"\\n {\\n \\"dependencies\\": {\\n- \\"@docusaurus/core\\": \\"2.4.3\\",\\n- \\"@docusaurus/preset-classic\\": \\"2.4.3\\",\\n- \\"@mdx-js/react\\": \\"^1.6.22\\",\\n+ \\"@docusaurus/core\\": \\"3.0.0-beta.0\\",\\n+ \\"@docusaurus/preset-classic\\": \\"3.0.0-beta.0\\",\\n+ \\"@mdx-js/react\\": \\"^3.0.0\\",\\n \\"clsx\\": \\"^2.0.0\\",\\n \\"prism-react-renderer\\": \\"^1.3.5\\",\\n- \\"react\\": \\"^17.0.2\\",\\n- \\"react-dom\\": \\"^17.0.2\\"\\n+ \\"react\\": \\"^18.2.0\\",\\n+ \\"react-dom\\": \\"^18.2.0\\"\\n },\\n \\"devDependencies\\": {\\n- \\"@docusaurus/module-type-aliases\\": \\"2.4.3\\"\\n+ \\"@docusaurus/module-type-aliases\\": \\"3.0.0-beta.0\\"\\n }\\n }\\n```\\n\\n## Ask for help\\n\\nWe will be there to help you upgrade through the following support channels:\\n\\n- [Docusaurus v3 - Upgrade Support](https://github.com/facebook/docusaurus/discussions/9336)\\n- [Docusaurus v3 - Discord channel #migration-v2-to-v3](https://discord.com/channels/398180168688074762/1154771869094912090)\\n- [MDX v3 - Upgrade Support](https://github.com/facebook/docusaurus/discussions/9053)\\n- [MDX v3 - Remark/Rehype Plugins Support](https://github.com/facebook/docusaurus/discussions/9337)\\n- [MDX v3 - Discord channel #migration-mdx-v3](https://discord.com/channels/398180168688074762/1116724556976111616)\\n\\nAlternatively, you can look for a paid [Docusaurus Service Provider](https://github.com/facebook/docusaurus/discussions/9281) to execute this upgrade for you. If your site is open source, you can also ask our community for [free, benevolent help](https://github.com/facebook/docusaurus/discussions/9283).\\n\\n## Conclusion\\n\\nDocusaurus v3 is ready to try, and will be released soon. This article already gives you a good idea of all the major changes required to upgrade.\\n\\nThe initial 3.0 release is focusing on dependency and infrastructure upgrades that will permit us to implement new exciting features. It also comes with a few useful features that we will detail in the final release notes."},{"id":"/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing","metadata":{"permalink":"/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2023/09-22-upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing/index.mdx","source":"@site/blog/2023/09-22-upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing/index.mdx","title":"Upgrading frontend dependencies with confidence","description":"Upgrade npm dependencies with confidence thanks to a visual regression testing workflow using GitHub Actions, Playwright and Argos.","date":"2023-09-22T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":8.355,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"authors":["slorber"],"tags":["release"],"slug":"/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing","description":"Upgrade npm dependencies with confidence thanks to a visual regression testing workflow using GitHub Actions, Playwright and Argos.","image":"./img/social-card.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Preparing your site for Docusaurus v3","permalink":"/blog/preparing-your-site-for-docusaurus-v3"},"nextItem":{"title":"Docusaurus 2.4","permalink":"/blog/releases/2.4"}},"content":"Frontend developers often need to **upgrade npm dependencies**, but those upgrades can feel scary and lead to **subtle UI side effects** not caught by your regular test suite.\\n\\nUpgrading Docusaurus is a good example: without reviewing all the pages one by one, it\'s hard to be sure there\'s no visual regression. **Docusaurus v3 is around the corner** (currently in [beta](https://github.com/facebook/docusaurus/discussions/9312)), and we would like to help you do this upgrade with confidence.\\n\\nThis article introduces a **visual regression testing** workflow based on [**GitHub Actions**](https://github.com/features/actions), [**Playwright**](https://playwright.dev/), and [**Argos**](https://argos-ci.com/). It is not directly coupled to Docusaurus or React, and can be adapted to work with other frontend applications and frameworks.\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\nThis workflow has been tested while upgrading Docusaurus v2 to v3, and already helped catch a few visual regressions on sites such as [React Native](https://reactnative.dev/), [Jest](https://jestjs.io/), and the [Docusaurus](https://docusaurus.io/) site itself.\\n\\nDocusaurus v3 comes with infrastructure changes and major dependency upgrades such as [MDX v3](https://mdxjs.com/blog/v3/) and [React 18](https://react.dev/blog/2022/03/29/react-v18), which can produce unexpected side effects. It would have been difficult to notice all the visual regressions without such a workflow. That\'s why we encourage site owners to consider adopting visual regression testing, especially for highly customized sites.\\n\\n## Workflow overview\\n\\nThe general idea is pretty simple:\\n\\n- Build your site in CI with [GitHub Actions](https://github.com/features/actions)\\n- Take screenshots of all `sitemap.xml` pages with [Playwright](https://playwright.dev/)\\n- Upload them to [Argos](https://argos-ci.com/)\\n- Do this for both Git branches `main` and `pr-branch`\\n- Compare the screenshots side-by-side in [Argos](https://argos-ci.com/)\\n\\nArgos will then **report visual differences** found between `main` and `pr-branch` as a GitHub commit status and pull-request comment. This can help you detect visual regressions ahead of time in an automated way.\\n\\n\\n\\n\\n\\nArgos creates a report referencing all the visual differences found while comparing the 2 Git branches sites side-by-side, and provides a convenient UX to easily spot the difference.\\n\\nCheck the [Docusaurus Argos page](https://app.argos-ci.com/meta-open-source/docusaurus) to explore our own website reports.\\n\\nHere is a more concrete example of Argos [reporting a visual regression](https://app.argos-ci.com/slorber/rnw-visual-tests/builds/32/56012838) found while upgrading the React-Native website:\\n\\n[](https://app.argos-ci.com/slorber/rnw-visual-tests/builds/32/56012838)\\n\\n## Workflow implementation\\n\\nThis section will describe the implementation details of each step of the workflow.\\n\\nYou will need to [sign up to Argos](https://app.argos-ci.com/signup) and [connect Argos to your GitHub repository](https://argos-ci.com/docs/github)\\n\\n### Dependencies\\n\\nThis workflow requires the following dev dependencies, in addition to the usual Docusaurus ones:\\n\\n```bash\\nyarn add -D @argos-ci/cli @argos-ci/playwright @playwright/test cheerio\\n```\\n\\n### GitHub Action\\n\\nThe GitHub action is responsible for executing the workflow for each Git branch.\\n\\nA minimal workflow could look like:\\n\\n```yaml title=\\".github/workflows/argos.yml\\"\\nname: Argos CI Screenshots\\n\\non:\\n push:\\n branches: [main]\\n pull_request:\\n branches: [main]\\n\\njobs:\\n take-screenshots:\\n runs-on: ubuntu-latest\\n steps:\\n - name: Check out repository code\\n uses: actions/checkout@v4\\n\\n - name: Use Node.js\\n uses: actions/setup-node@v3\\n with:\\n node-version: current\\n\\n - name: Install dependencies\\n run: yarn install --frozen-lockfile\\n\\n - name: Install Playwright browsers\\n run: yarn playwright install --with-deps chromium\\n\\n - name: Build the website\\n run: yarn docusaurus build\\n\\n - name: Take screenshots with Playwright\\n run: yarn playwright test\\n\\n - name: Upload screenshots to Argos\\n run: yarn argos upload ./screenshots\\n```\\n\\n### Playwright config\\n\\nPlaywright is responsible for taking screenshots of the website previously built locally by the GitHub action.\\n\\nA minimal [Playwright config](https://playwright.dev/docs/test-configuration) could look like:\\n\\n```ts title=\\"playwright.config.ts\\"\\nimport {devices} from \'@playwright/test\';\\nimport type {PlaywrightTestConfig} from \'@playwright/test\';\\n\\nconst config: PlaywrightTestConfig = {\\n webServer: {\\n port: 3000,\\n command: \'yarn docusaurus serve\',\\n },\\n projects: [\\n {\\n name: \'chromium\',\\n use: {\\n ...devices[\'Desktop Chrome\'],\\n },\\n },\\n ],\\n};\\n\\nexport default config;\\n```\\n\\n### Playwright test\\n\\nA Playwright config is not enough: we also need to write a Playwright test file to generate the site screenshots.\\n\\n```ts title=\\"screenshot.spec.ts\\"\\nimport * as fs from \'fs\';\\nimport {test} from \'@playwright/test\';\\nimport {argosScreenshot} from \'@argos-ci/playwright\';\\nimport {extractSitemapPathnames, pathnameToArgosName} from \'./utils\';\\n\\n// Constants\\nconst siteUrl = \'http://localhost:3000\';\\nconst sitemapPath = \'./build/sitemap.xml\';\\nconst stylesheetPath = \'./screenshot.css\';\\nconst stylesheet = fs.readFileSync(stylesheetPath).toString();\\n\\n// Wait for hydration, requires Docusaurus v2.4.3+\\n// Docusaurus adds a <html data-has-hydrated=\\"true\\"> once hydrated\\n// See https://github.com/facebook/docusaurus/pull/9256\\nfunction waitForDocusaurusHydration() {\\n return document.documentElement.dataset.hasHydrated === \'true\';\\n}\\n\\nfunction screenshotPathname(pathname: string) {\\n test(`pathname ${pathname}`, async ({page}) => {\\n const url = siteUrl + pathname;\\n await page.goto(url);\\n await page.waitForFunction(waitForDocusaurusHydration);\\n await page.addStyleTag({content: stylesheet});\\n await argosScreenshot(page, pathnameToArgosName(pathname));\\n });\\n}\\n\\ntest.describe(\'Docusaurus site screenshots\', () => {\\n const pathnames = extractSitemapPathnames(sitemapPath);\\n console.log(\'Pathnames to screenshot:\', pathnames);\\n pathnames.forEach(screenshotPathname);\\n});\\n```\\n\\n<details>\\n <summary>Why do we take screenshots with Argos instead of Playwright?</summary>\\n\\nArgos has a [Playwright integration](https://argos-ci.com/docs/playwright) that wraps the original Playwright screenshot API and provides better defaults to make screenshots more deterministic.\\n\\n</details>\\n\\n<details>\\n<summary>What\'s inside <code>utils.ts</code>?</summary>\\n\\nThis module contains implementation details that we choose to hide for clarity.\\n\\n```ts\\nimport * as cheerio from \'cheerio\';\\nimport * as fs from \'fs\';\\n\\n// Extract a list of pathnames, given a fs path to a sitemap.xml file\\n// Docusaurus generates a build/sitemap.xml file for you!\\nexport function extractSitemapPathnames(sitemapPath: string): string[] {\\n const sitemap = fs.readFileSync(sitemapPath).toString();\\n const $ = cheerio.load(sitemap, {xmlMode: true});\\n const urls: string[] = [];\\n $(\'loc\').each(function handleLoc() {\\n urls.push($(this).text());\\n });\\n return urls.map((url) => new URL(url).pathname);\\n}\\n\\n// Converts a pathname to a decent screenshot name\\nexport function pathnameToArgosName(pathname: string): string {\\n return pathname.replace(/^\\\\/|\\\\/$/g, \'\') || \'index\';\\n}\\n```\\n\\n</details>\\n\\n### Stylesheet\\n\\nScreenshots are not always deterministic, and taking a screenshot of a page twice can lead to subtle variations that will be reported by Argos as **false positive** visual regressions.\\n\\nFor this reason, we recommend injecting an extra stylesheet to hide the problematic elements. You will probably need to add new CSS rules to this base stylesheet, according to flaky elements found on your own site. Read [Argos - About flaky tests docs](https://argos-ci.com/docs/about-flaky) for details.\\n\\n```css title=\\"screenshot.css\\"\\n/* Iframes can load lazily */\\niframe,\\n/* Avatars can be flaky due to using external sources: GitHub/Unavatar */\\n.avatar__photo,\\n/* Gifs load lazily and are animated */\\nimg[src$=\'.gif\'],\\n/* Algolia keyboard shortcuts appear with a little delay */\\n.DocSearch-Button-Keys > kbd,\\n/* The live playground preview can often display dates/counters */\\n[class*=\'playgroundPreview\'] {\\n visibility: hidden;\\n}\\n\\n/* Different docs last-update dates can alter layout */\\n.theme-last-updated,\\n/* Mermaid diagrams are rendered client-side and produce layout shifts */\\n.docusaurus-mermaid-container {\\n display: none;\\n}\\n```\\n\\n:::tip prevent layout shifts\\n\\nWe recommend hiding flaky UI elements affecting layout with `display: none;`.\\n\\nFor example, the docs \\"Last Updated on\\" might render on more than 1 line, eventually \\"pushing\\" the rest of your content further down, leading to Argos detecting many different pixels.\\n\\n:::\\n\\n## Example repository\\n\\nThe [slorber/docusaurus-argos-example](https://github.com/slorber/docusaurus-argos-example) repo shows a complete example of implementing this workflow on a newly initialized Docusaurus v2 site, using a Yarn monorepo.\\n\\n[](https://github.com/slorber/docusaurus-argos-example)\\n\\nRelevant pull-requests:\\n\\n- [PR - Set up GitHub Action + Playwright + Argos](https://github.com/slorber/docusaurus-argos-example/pull/1): implements the minimal workflow described above\\n- [PR - Upgrading Docusaurus from v2 to v3](https://github.com/slorber/docusaurus-argos-example/pull/2): shows how Argos caught 3 visual regressions while upgrading\\n\\n:::tip More advanced example?\\n\\nBrowse the Docusaurus repository for a more advanced integration:\\n\\n- [GitHub Action](https://github.com/facebook/docusaurus/blob/main/.github/workflows/argos.yml)\\n- [Playwright + Argos tests](https://github.com/facebook/docusaurus/tree/main/argos)\\n\\n:::\\n\\n## Make it cheap\\n\\nThe tools we choose are implementation details of this visual regression testing workflow.\\n\\nFor Docusaurus, we choose [Argos](https://argos-ci.com/): it works well for us, and offers [free](https://argos-ci.com/pricing) and [open source](https://argos-ci.com/docs/open-source) plans. However, you are free to adopt alternative tools.\\n\\nIn case you don\'t mind storing large screenshots in Git, you can also try the free, self-hosted [Playwright Visual Comparisons](https://playwright.dev/docs/test-snapshots) and browse visual differences with `npx playwright show-report`. However, we found using a dedicated external tool is more convenient.\\n\\nExternal tools can be expensive, but generally offer free plans with an ample quota of screenshots. You can reduce your screenshot consumption by implementing a few tricks below.\\n\\n### Limit the number of pathnames\\n\\nThe base setup involves taking a screenshot of every single pathname found in `sitemap.xml`. For large sites, that can lead to a lot of screenshots.\\n\\nYou can decide to filter the pathnames to only take screenshots of the most critical pages.\\n\\nFor the Docusaurus website, do not take screenshots for versioned docs pages:\\n\\n```ts title=\\"screenshot.spec.ts\\"\\n// highlight-start\\nfunction isVersionedDocsPathname(pathname: string): boolean {\\n return pathname.match(/^\\\\/docs\\\\/((\\\\d\\\\.\\\\d\\\\.\\\\d)|(next))\\\\//);\\n}\\n// highlight-end\\n\\ntest.describe(\'Docusaurus site screenshots\', () => {\\n const pathnames = extractSitemapPathnames(sitemapPath)\\n // highlight-next-line\\n .filter(isVersionedDocsPathname);\\n\\n pathnames.forEach(screenshotPathname);\\n});\\n```\\n\\n### Limit the workflow concurrency\\n\\nImplementing [GitHub Actions concurrency groups](https://docs.github.com/en/actions/using-jobs/using-concurrency) will prevent successive commits to trigger multiple useless workflow runs. The workflow will only be executed for the last commit, and previous commits will be canceled automatically.\\n\\n```yaml title=\\".github/workflows/argos.yml\\"\\nconcurrency:\\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\\n cancel-in-progress: true\\n```\\n\\n### Run your workflow conditionally\\n\\nIt\'s not worth running this workflow for every single commit and pull-request.\\n\\nFor example, if someone corrects a typo in your documentation, you probably don\'t want to take hundreds of screenshots and have Argos to point out that only the modified page has a visual difference: duh, that\'s a bit expected!\\n\\nFor the Docusaurus website, we only run the workflow for pull-request having the `Argos` label:\\n\\n```yaml title=\\".github/workflows/argos.yml\\"\\nname: Argos CI Screenshots\\n\\non:\\n push:\\n branches: [main]\\n pull_request:\\n branches: [main]\\n # highlight-start\\n types:\\n - opened\\n - synchronize\\n - reopened\\n - labeled\\n # highlight-end\\n\\njobs:\\n take-screenshots:\\n # highlight-start\\n if: ${{ github.ref_name == \'main\' || (github.event_name == \'pull_request\' && contains(github.event.pull_request.labels.*.name, \'Argos\')) }}\\n # highlight-end\\n runs-on: ubuntu-latest\\n steps:\\n # Your job steps here ...\\n```\\n\\nThere are many options to explore, such as [triggering the workflow manually](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow) or [only when files matching a specific pattern are modified](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#example-including-paths).\\n\\n## Conclusion\\n\\nI believe **visual regression testing is underused** in the frontend ecosystem.\\n\\nTaking full-page screenshots is a **low-hanging fruit** that is easy to set up and can help you **catch a new class of bugs** that your regular test suite would miss. This technique shines not only for npm package upgrades, but also for **any kind of refactoring** that shouldn\'t change the user interface.\\n\\nSo why not give it a try?\\n\\nHappy hacking!\\n\\n## See also\\n\\nUseful documentation links:\\n\\n- [Playwright - Installation](https://playwright.dev/docs/intro)\\n- [Playwright - Test config guide](https://playwright.dev/docs/test-configuration)\\n- [Playwright - Test config API](https://playwright.dev/docs/api/class-testconfig)\\n- [Argos - Installation](https://argos-ci.com/docs/installation)\\n- [Argos - Use with GitHub Actions](https://argos-ci.com/docs/github-actions)\\n- [Argos - Use with Playwright](https://argos-ci.com/docs/playwright)\\n- [Argos - About flaky tests](https://argos-ci.com/docs/about-flaky)"},{"id":"/releases/2.4","metadata":{"permalink":"/blog/releases/2.4","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/2.4/index.mdx","source":"@site/blog/releases/2.4/index.mdx","title":"Docusaurus 2.4","description":"We are happy to announce Docusaurus 2.4.","date":"2023-03-23T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":3.05,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 2.4","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2023-03-23T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Upgrading frontend dependencies with confidence","permalink":"/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing"},"nextItem":{"title":"Docusaurus 2.3","permalink":"/blog/releases/2.3"}},"content":"We are happy to announce **Docusaurus 2.4**.\\n\\nThe upgrade should be easy: as explained in our [release process documentation](/community/release-process), minor versions respect [Semantic Versioning](https://semver.org/).\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\nimport BrowserWindow from \'@site/src/components/BrowserWindow\';\\nimport IframeWindow from \'@site/src/components/BrowserWindow/IframeWindow\';\\nimport ErrorBoundaryTestButton from \'@site/src/components/ErrorBoundaryTestButton\';\\n\\n## Highlights\\n\\n### Sidebar item description\\n\\nIn [#8236](https://github.com/facebook/docusaurus/pull/8236), we made it possible to provide a new `description` attribute for docs sidebar items of type `link` and `category`.\\n\\n```tsx title=\\"sidebars.js\\"\\n[\\n {\\n type: \'link\',\\n label: \'Link with description\',\\n href: \'https://docusaurus.io\',\\n // highlight-next-line\\n description: \'Some link description\',\\n },\\n {\\n type: \'category\',\\n label: \'Category with description\',\\n // highlight-next-line\\n description: \'Some category description\',\\n items: [],\\n },\\n];\\n```\\n\\nThese descriptions will be used in category generated index pages.\\n\\n\\n\\n### Theme Query String\\n\\nIn [#8708](https://github.com/facebook/docusaurus/pull/8708), we added the possibility to force Docusaurus to initialize itself in `light` or `dark` mode through a new `docusaurus-theme` query-string parameter.\\n\\nThis is useful to ensure a consistent theme when embedding an existing Docusaurus page into an iframe or WebView.\\n\\n<IframeWindow url=\\"/docs/?docusaurus-theme=light\\" />\\n<IframeWindow url=\\"/docs/?docusaurus-theme=dark\\" />\\n\\n### Remark plugin npm2yarn upgrade\\n\\nIn [#8690](https://github.com/facebook/docusaurus/pull/8690), we upgraded our Remark plugin [@docusaurus/remark-plugin-npm2yarn](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-remark-plugin-npm2yarn) with many conversion bug fixes, first-class support for pnpm, and the ability to register custom converters producing new tabs.\\n\\n````markdown\\nRun these commands!\\n\\n```bash npm2yarn\\nnpm install\\nnpm run build\\nnpm run myCustomScript -- --some-arg\\n```\\n````\\n\\n<BrowserWindow>\\n\\n```bash npm2yarn\\nnpm install\\nnpm run build\\nnpm run myCustomScript -- --some-arg\\n```\\n\\n</BrowserWindow>\\n\\n### gtag support for multiple tracking IDs\\n\\nIn [#8620](https://github.com/facebook/docusaurus/pull/8620) we added support for the [@docusaurus/plugin-google-gtag](/docs/api/plugins/@docusaurus/plugin-google-gtag) plugin to declare multiple tracking IDs.\\n\\n```js title=\\"docusaurus.config.js\\"\\nmodule.exports = {\\n presets: [\\n [\\n \'@docusaurus/preset-classic\',\\n {\\n gtag: {\\n trackingID: [\\n // highlight-next-line\\n \'G-<YOUR-NEW-GA4-ID>\',\\n // highlight-next-line\\n \'UA-<YOUR-OLD-UA-ID>\',\\n ],\\n },\\n },\\n ],\\n ],\\n};\\n```\\n\\n:::warning Google is sunsetting Universal Analytics\\n\\n**[Google will sunset its Universal Analytics](https://blog.google/products/marketingplatform/analytics/prepare-for-future-with-google-analytics-4/)** on **July 1, 2023**.\\n\\nDocusaurus users should migrate to Google Analytics 4. Google **does not permit to migrate your existing Universal Analytics data** to your new Google Analytics 4 property.\\n\\nTo preserve the continuity of your analytics, we temporarily recommend that you report events to 2 tracking IDs at the same time: the old one (`UA-*`) and new one (`G-*`). Refer to the **[dedicated issue](https://github.com/facebook/docusaurus/issues/7221)** for details.\\n\\n:::\\n\\n### Developer Experience\\n\\nIn [#8736](https://github.com/facebook/docusaurus/pull/8736), we improved how we render error messages and added initial support to render the full causal chain of an error (see [ES2022 Error Cause](https://h3manth.com/ES2022/#error-cause)).\\n\\n:::tip\\n\\nTo see it in action, click here: <ErrorBoundaryTestButton cause=\\"Probably undefined is not a function \uD83D\uDE04\\"/>\\n\\n:::\\n\\nIn [#8735](https://github.com/facebook/docusaurus/pull/8735) we also made navbar-related error messages clearer to help users understand what they did wrong.\\n\\n\\n\\n### Translations\\n\\nWe made it possible to translate some new elements:\\n\\n- [#8677](https://github.com/facebook/docusaurus/pull/8677) introduces a new `process.env.DOCUSAURUS_CURRENT_LOCALE` (experimental) allowing you to localize your config file, including site title, tagline, announcement bar, baseUrl...\\n- [#8616](https://github.com/facebook/docusaurus/pull/8616) allows to translate the navbar and footer logo alt text\\n\\nWe added default theme translation support for multiple languages:\\n\\n- \uD83C\uDDED\uD83C\uDDFA [#8668](https://github.com/facebook/docusaurus/pull/8668): Hungarian\\n- \uD83C\uDDF3\uD83C\uDDF4 [#8631](https://github.com/facebook/docusaurus/pull/8631): Norwegian (Bokm\xe5l)\\n\\n:::tip\\n\\nCompleting theme translations is an [ongoing effort](https://github.com/facebook/docusaurus/issues/3526) and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often [need new translations](https://github.com/facebook/docusaurus/issues/3526).\\n\\n:::\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#8674](https://github.com/facebook/docusaurus/pull/8674): respect `prefers-reduced-motion: reduce` media query\\n- [#8712](https://github.com/facebook/docusaurus/pull/8712): use a navbar item of type `docSidebar` in template\\n- [#8801](https://github.com/facebook/docusaurus/pull/8801): allow tabs children to be falsy\\n- [#8757](https://github.com/facebook/docusaurus/pull/8757): make search page react to external query-string changes\\n- [#8803](https://github.com/facebook/docusaurus/pull/8803): fix code block buttons position in RTL\\n- [#8615](https://github.com/facebook/docusaurus/pull/8615): fix color mode toggle when using dark navbar\\n- [#8699](https://github.com/facebook/docusaurus/pull/8699): fix navbar dropdown tab focus bug\\n\\nCheck the **[2.4.0 changelog entry](/changelog/2.4.0)** for an exhaustive list of changes."},{"id":"/releases/2.3","metadata":{"permalink":"/blog/releases/2.3","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/2.3/index.mdx","source":"@site/blog/releases/2.3/index.mdx","title":"Docusaurus 2.3","description":"We are happy to announce Docusaurus 2.3.","date":"2023-01-27T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":2.89,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 2.3","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2023-01-27T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 2.4","permalink":"/blog/releases/2.4"},"nextItem":{"title":"Docusaurus 2.2","permalink":"/blog/releases/2.2"}},"content":"We are happy to announce **Docusaurus 2.3**.\\n\\nThe upgrade should be easy: as explained in our [release process documentation](/community/release-process), minor versions respect [Semantic Versioning](https://semver.org/).\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\n## Highlights\\n\\n### Google Tag Manager plugin\\n\\nGoogle Tag Manager is a tag management system that allows great flexibility. It enables analytics and marketing teams to easily load other third-party trackers and fire analytics tags.\\n\\nWe now have a [`@docusaurus/plugin-google-tag-manager`](/docs/api/plugins/@docusaurus/plugin-google-tag-manager/) package that you can use alongside or as an alternative to the existing [gtag.js plugin](/docs/api/plugins/@docusaurus/plugin-google-gtag/) (refer to [this doc](https://support.google.com/tagmanager/answer/7582054) to understand when to use which solution).\\n\\n:::warning Google is sunsetting Universal Analytics\\n\\n[Google will sunset its Universal Analytics](https://blog.google/products/marketingplatform/analytics/prepare-for-future-with-google-analytics-4/) on **July 1, 2023**, and ask users to migrate to **Google Analytics 4**.\\n\\nTherefore, we are also **deprecating our existing [`@docusaurus/plugin-google-analytics`](/docs/api/plugins/@docusaurus/plugin-google-analytics)** package. Docusaurus users should create a new Google Analytics 4 property, and migrate to the [gtag.js plugin](/docs/api/plugins/@docusaurus/plugin-google-gtag/), or the [Google Tag Manager plugin](/docs/api/plugins/@docusaurus/plugin-google-tag-manager/). Refer to the [dedicated Docusaurus issue](https://github.com/facebook/docusaurus/issues/7221) for details and questions.\\n\\n:::\\n\\n### Tabs Query String Support\\n\\nIt is now possible to link a selected tab to a query string parameter. When a tab is selected, it will be stored in your browser URL as a `?qs-param=tab-value` search parameter.\\n\\nThis feature allows deep-linking to a specific documentation tab that will pre-selected on page load.\\n\\nWhen used alongside the `groupId` prop, the query string tab value takes precedence over the `localStorage` value.\\n\\nMake sure to check the [documentation](/docs/markdown-features/tabs#query-string) and the demo below to understand how it works:\\n\\nimport BrowserWindow from \'@site/src/components/BrowserWindow\';\\nimport Tabs from \'@theme/Tabs\';\\nimport TabItem from \'@theme/TabItem\';\\n\\n```tsx\\n<Tabs groupId=\\"current-os\\" queryString>\\n <TabItem value=\\"android\\" label=\\"Android\\">\\n Android\\n </TabItem>\\n <TabItem value=\\"ios\\" label=\\"iOS\\">\\n iOS\\n </TabItem>\\n</Tabs>\\n```\\n\\n<BrowserWindow>\\n <Tabs groupId=\\"current-os\\" queryString>\\n <TabItem value=\\"android\\" label=\\"Android\\">\\n Android\\n </TabItem>\\n <TabItem value=\\"ios\\" label=\\"iOS\\">\\n iOS\\n </TabItem>\\n </Tabs>\\n</BrowserWindow>\\n\\n### Nested admonitions\\n\\nIt is now possible to nest one admonition within another by adding extra colons for the outer/enclosing admonition:\\n\\n```md\\n::::tip nested admonitions\\n\\nYou can now nest one admonition within another!\\n\\n:::danger\\n\\nUse this sparingly when it makes sense.\\n\\n:::\\n\\n::::\\n```\\n\\n::::tip nested admonitions\\n\\nYou can now nest one admonition within another!\\n\\n:::danger\\n\\nUse this sparingly when it makes sense.\\n\\n:::\\n\\n::::\\n\\n### Blog `createFeedItems`\\n\\nA new blog plugin option [`feedOptions.createFeedItems`](/docs/api/plugins/@docusaurus/plugin-content-blog/#CreateFeedItemsFn) gives you more control over the RSS/Atom feed generation. It is now possible to transform/filter/limit feed items through a new callback.\\n\\n```tsx title=\\"docusaurus.config.js\\"\\n[\\n \'@docusaurus/preset-classic\',\\n {\\n blog: {\\n feedOptions: {\\n // highlight-start\\n createFeedItems: async (params) => {\\n const {blogPosts, defaultCreateFeedItems, ...rest} = params;\\n return defaultCreateFeedItems({\\n // keep only the 10 most recent blog posts in the feed\\n blogPosts: blogPosts.filter((item, index) => index < 10),\\n ...rest,\\n });\\n },\\n // highlight-end\\n },\\n },\\n },\\n];\\n```\\n\\n### Translations\\n\\nWe added or completed the default theme translation support for multiple languages:\\n\\n- \uD83C\uDDF8\uD83C\uDDEE [#8541](https://github.com/facebook/docusaurus/pull/8541) Slovenian\\n- \uD83C\uDDF9\uD83C\uDDF7 [#8289](https://github.com/facebook/docusaurus/pull/8289) Turkish\\n- \uD83C\uDDEE\uD83C\uDDF7 [#8406](https://github.com/facebook/docusaurus/pull/8406) Farsi\\n- \uD83C\uDDF5\uD83C\uDDF1 [#8525](https://github.com/facebook/docusaurus/pull/8525) Polish\\n- \uD83C\uDDE8\uD83C\uDDF3 [#8423](https://github.com/facebook/docusaurus/pull/8423) Chinese\\n- \uD83C\uDDF8\uD83C\uDDEA [#8312](https://github.com/facebook/docusaurus/pull/8312) Swedish\\n- \uD83C\uDDFB\uD83C\uDDF3 [#8450](https://github.com/facebook/docusaurus/pull/8450) Vietnamese\\n\\n:::tip\\n\\nCompleting theme translations is an [ongoing effort](https://github.com/facebook/docusaurus/issues/3526) and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often [need new translations](https://github.com/facebook/docusaurus/issues/3526).\\n\\n:::\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#8463](https://github.com/facebook/docusaurus/pull/8463) and [#8328](https://github.com/facebook/docusaurus/pull/8328): fix some annoying Docusaurus layout issues\\n- [#8539](https://github.com/facebook/docusaurus/pull/8539): Algolia plugin `options.searchPagePath` should be correctly applied to search modal footer\\n- [#8462](https://github.com/facebook/docusaurus/pull/8462): Algolia plugin now makes it easier to transform displayed search results with custom logic\\n- [#8397](https://github.com/facebook/docusaurus/pull/8397): the `deploy` CLI now understands git url `insteadOf` config\\n\\nCheck the **[2.3.0 changelog entry](/changelog/2.3.0)** for an exhaustive list of changes."},{"id":"/releases/2.2","metadata":{"permalink":"/blog/releases/2.2","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/releases/2.2/index.mdx","source":"@site/blog/releases/2.2/index.mdx","title":"Docusaurus 2.2","description":"We are happy to announce Docusaurus 2.2.","date":"2022-10-29T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":2.2,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 2.2","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png","date":"2022-10-29T00:00:00.000Z"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 2.3","permalink":"/blog/releases/2.3"},"nextItem":{"title":"Docusaurus 2.1","permalink":"/blog/2022/09/01/docusaurus-2.1"}},"content":"We are happy to announce **Docusaurus 2.2**.\\n\\nThe upgrade should be easy: as explained in our [release process documentation](/community/release-process), minor versions respect [Semantic Versioning](https://semver.org/).\\n\\n\\n\\n{/* truncate */}\\n\\n## Highlights\\n\\n### Mermaid diagrams\\n\\nIn [#7490](https://github.com/facebook/docusaurus/pull/7490), we added support for Mermaid diagrams. This fills the gap between GitHub Flavored Markdown which also [added support recently](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/). You can create Mermaid diagrams using Markdown code blocks:\\n\\n````md\\n```mermaid\\nsequenceDiagram\\n participant Alice\\n participant Bob\\n Alice->>John: Hello John, how are you?\\n loop Health check\\n John->>John: Fight against hypochondria\\n end\\n Note right of John: Rational thoughts <br/>prevail!\\n John--\x3e>Alice: Great!\\n John->>Bob: How about you?\\n Bob--\x3e>John: Jolly good!\\n```\\n````\\n\\n````mdx-code-block\\nimport BrowserWindow from \'@site/src/components/BrowserWindow\';\\n\\n<BrowserWindow>\\n\\n```mermaid\\nsequenceDiagram\\n participant Alice\\n participant Bob\\n Alice->>John: Hello John, how are you?\\n loop Health check\\n John->>John: Fight against hypochondria\\n end\\n Note right of John: Rational thoughts <br/>prevail!\\n John--\x3e>Alice: Great!\\n John->>Bob: How about you?\\n Bob--\x3e>John: Jolly good!\\n```\\n\\n</BrowserWindow>\\n\\n````\\n\\nMake sure to check the [documentation](/docs/markdown-features/diagrams), and the [more advanced examples](/tests/pages/diagrams)\\n\\n### Config `headTags`\\n\\nIn [#8151](https://github.com/facebook/docusaurus/pull/8151), we added the ability to apply arbitrary HTML `<head>` tags to all pages of your site.\\n\\n```js title=\\"docusaurus.config.js\\"\\nmodule.exports = {\\n headTags: [\\n {\\n tagName: \'link\',\\n attributes: {\\n rel: \'icon\',\\n href: \'/img/docusaurus.png\',\\n },\\n },\\n ],\\n};\\n```\\n\\n### Accessibility\\n\\nWe did several accessibility improvements:\\n\\n- [#8207](https://github.com/facebook/docusaurus/pull/8207): improves keyboard navigation for mobile drawer hamburger button\\n- [#8161](https://github.com/facebook/docusaurus/pull/8161): improves keyboard navigation for tabs\\n- [#8204](https://github.com/facebook/docusaurus/pull/8204): makes the skip to content button support progressive enhancement\\n- [#8174](https://github.com/facebook/docusaurus/pull/8174): improves screen reader announcement when toggling between light/dark mode\\n\\n### Developer Experience\\n\\nWe made validation stricter and improved error messages:\\n\\n- [#8234](https://github.com/facebook/docusaurus/pull/8234): in case of doc processing failure, prints the problematic markdown file path in the error message\\n- [#8192](https://github.com/facebook/docusaurus/pull/8192) and [#8159](https://github.com/facebook/docusaurus/pull/8159): validates `siteConfig.url` more strictly and with better error message\\n- [#8066](https://github.com/facebook/docusaurus/pull/8066): makes config `url` and `baseUrl` fail-safe and less sensitive to the presence or absence of a leading or trailing slash\\n\\n### Translations\\n\\nWe completed the default theme translation support for multiple languages:\\n\\n- \uD83C\uDDF9\uD83C\uDDF7 [#8105](https://github.com/facebook/docusaurus/pull/8105): completes Turkish translations\\n- \uD83C\uDDF7\uD83C\uDDFA [#8253](https://github.com/facebook/docusaurus/pull/8253): completes Russian translations\\n- \uD83C\uDDEB\uD83C\uDDF7 [#8243](https://github.com/facebook/docusaurus/pull/8243): completes French translations\\n- \uD83C\uDDEF\uD83C\uDDF5 [#8075](https://github.com/facebook/docusaurus/pull/8075): completes Japanese translations\\n\\n:::tip\\n\\nCompleting theme translations is an [ongoing effort](https://github.com/facebook/docusaurus/issues/3526) and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often [need new translations](https://github.com/facebook/docusaurus/issues/3526).\\n\\n:::\\n\\n## Other changes\\n\\nOther notable changes include:\\n\\n- [#8210](https://github.com/facebook/docusaurus/pull/8210): the `docusaurus swizzle` CLI has a new `--config` option\\n- [#8109](https://github.com/facebook/docusaurus/pull/8109): mobile navigation performance optimizations, prefetch resources earlier\\n- [#8059](https://github.com/facebook/docusaurus/pull/8059): versions/locales navbar dropdowns preserve hash and querystring on navigation\\n- [#8227](https://github.com/facebook/docusaurus/pull/8227): the client redirect plugin preserves hash and querystring on redirect\\n\\nCheck the **[2.2.0 changelog entry](/changelog/2.2.0)** for an exhaustive list of changes."},{"id":"/2022/09/01/docusaurus-2.1","metadata":{"permalink":"/blog/2022/09/01/docusaurus-2.1","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2022/09-01-docusaurus-2.1/index.mdx","source":"@site/blog/2022/09-01-docusaurus-2.1/index.mdx","title":"Docusaurus 2.1","description":"We are happy to announce Docusaurus 2.1, our very first minor version release.","date":"2022-09-01T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":1.725,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 2.1","authors":["slorber"],"tags":["release"],"image":"./img/social-card.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 2.2","permalink":"/blog/releases/2.2"},"nextItem":{"title":"Announcing Docusaurus 2.0","permalink":"/blog/2022/08/01/announcing-docusaurus-2.0"}},"content":"We are happy to announce **Docusaurus 2.1**, our very first minor version release.\\n\\nThe upgrade should be easy: as explained in our [release process documentation](/community/release-process), minor versions respect [Semantic Versioning](https://semver.org/).\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\n## Highlights\\n\\n### DocCardList improvements\\n\\nIn [#8008](https://github.com/facebook/docusaurus/pull/8008), we simplified the usage of the`<DocCardList>` component, that is notably used on sidebar category generated index pages.\\n\\nThe `items` prop is now optional, and will be automatically inferred from the content of the parent sidebar category:\\n\\n```diff\\nimport DocCardList from \'@theme/DocCardList\';\\n- import {useCurrentSidebarCategory} from \'@docusaurus/theme-common\';\\n\\n- <DocCardList items={useCurrentSidebarCategory().items}/>\\n+ <DocCardList/>\\n```\\n\\nAlso, we made it possible to use it on any document, including regular docs not linked to any sidebar category.\\n\\n\\n\\n### `noindex` improvements\\n\\nWe improved the support of the [`noindex` meta `robots` directive](https://developers.google.com/search/docs/advanced/crawling/block-indexing), a way to signal search engines you don\'t want a specific page to be indexed.\\n\\nIn [#7963](https://github.com/facebook/docusaurus/pull/7963), we allow `noindex` to be configured on a per-docs-version basis.\\n\\nUse the following plugin options to tell crawlers you don\'t want the `1.0.0` version to be indexed:\\n\\n```jsx\\nconst options = {\\n versions: {\\n \'1.0.0\': {\\n noIndex: true,\\n },\\n },\\n};\\n```\\n\\nIn practice, Docusaurus will add the following meta to each page of that version:\\n\\n```html\\n<meta name=\\"robots\\" content=\\"noindex, nofollow\\" />\\n```\\n\\nIn [#7964](https://github.com/facebook/docusaurus/pull/7964), we also fixed a bug where the sitemap plugin would still contain pages that have a `noindex` directive. Now the sitemap plugin will reliably filter out all the pages containing `noindex` directives.\\n\\n### Overriding default meta tags\\n\\nIn [#7952](https://github.com/facebook/docusaurus/pull/7952), it becomes possible to override default html meta tags you couldn\'t before:\\n\\n```jsx\\n<>\\n {siteConfig.noIndex && <meta name=\\"robots\\" content=\\"nofollow, noindex\\" />}\\n <meta name=\\"viewport\\" content=\\"width=device-width, initial-scale=1.0\\" />\\n</>\\n```\\n\\nIt is now possible to use `<Head>` or `themeConfig.metadata`:\\n\\n- to override the `viewport` meta\\n- to override the `robots` meta: you could mark your site as `noIndex`, but except for specific pages that should be indexed\\n\\n### Ukrainian translations\\n\\nIn [#7953](https://github.com/facebook/docusaurus/pull/7953), we added default classic theme translations for the Ukrainian language.\\n\\n## Other changes\\n\\nCheck the [2.1.0 changelog entry](/changelog/2.1.0) for an exhaustive list of changes."},{"id":"/2022/08/01/announcing-docusaurus-2.0","metadata":{"permalink":"/blog/2022/08/01/announcing-docusaurus-2.0","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2022/08-01-announcing-docusaurus-2.0/index.mdx","source":"@site/blog/2022/08-01-announcing-docusaurus-2.0/index.mdx","title":"Announcing Docusaurus 2.0","description":"Today we are extremely happy to finally announce Docusaurus 2.0! \uD83E\uDD73\uFE0F","date":"2022-08-01T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"}],"readingTime":12.075,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"},{"name":"Joshua Chen","title":"Working hard on Docusaurus","url":"https://joshcena.com/","email":"sidachen2003@gmail.com","page":{"permalink":"/blog/authors/josh-cena"},"imageURL":"https://github.com/josh-cena.png","key":"Josh-Cena"},{"name":"Yangshun Tay","title":"Front End Engineer at Meta","url":"https://github.com/yangshun","page":{"permalink":"/blog/authors/yangshun"},"socials":{"x":"https://x.com/yangshunz","github":"https://github.com/yangshun"},"imageURL":"https://github.com/yangshun.png","key":"yangshun"},{"name":"Alexey Pyltsyn","title":"Open-source enthusiast","url":"https://github.com/lex111","email":"lex@php.net","page":{"permalink":"/blog/authors/lex-111"},"imageURL":"https://github.com/lex111.png","key":"lex111"},{"name":"Paul O\u2019Shannessy","title":"Engineering Manager at Meta","url":"https://x.com/zpao","page":{"permalink":"/blog/authors/zpao"},"socials":{"x":"https://x.com/zpao","github":"https://github.com/zpao"},"imageURL":"https://github.com/zpao.png","key":"zpao"},{"name":"Joel Marcey","title":"Co-creator of Docusaurus 1","url":"https://x.com/JoelMarcey","page":{"permalink":"/blog/authors/j-marcey"},"socials":{},"imageURL":"https://github.com/JoelMarcey.png","key":"JMarcey"}],"frontMatter":{"title":"Announcing Docusaurus 2.0","authors":["slorber","Josh-Cena","yangshun","lex111","zpao",{"key":"JMarcey","title":"Co-creator of Docusaurus 1"}],"tags":["release"],"image":"./img/social-card.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 2.1","permalink":"/blog/2022/09/01/docusaurus-2.1"},"nextItem":{"title":"Docusaurus 2021 Recap","permalink":"/blog/2022/01/24/docusaurus-2021-recap"}},"content":"```mdx-code-block\\nimport LiteYouTubeEmbed from \'react-lite-youtube-embed\';\\nimport \'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css\';\\nimport BrowserWindow from \'@site/src/components/BrowserWindow\';\\nimport ProductHuntCard from \'@site/src/components/ProductHuntCard\';\\nimport HackerNewsIcon from \'@site/src/components/HackerNewsIcon\';\\nimport ColorModeToggle from \'@theme/Navbar/ColorModeToggle\';\\nimport useBaseUrl from \'@docusaurus/useBaseUrl\';\\nimport ThemedImage from \'@theme/ThemedImage\';\\nimport {ShowcaseCarouselV1, ShowcaseCarouselV2, ShowcaseCarouselV2Theming} from \'./ShowcaseCarousel\';\\n```\\n\\nToday we are extremely happy to finally **announce Docusaurus 2.0**! \uD83E\uDD73\uFE0F\\n\\nAt [**Meta Open Source**](https://opensource.fb.com/), we believe Docusaurus will help you build the **best documentation websites** with **minimal effort**, letting you **focus on what really matters**: writing the content.\\n\\nAfter **4 years of work, [75 alphas](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.75) and [22 betas](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-beta.22)**, the next generation of Docusaurus is **ready for prime time**. From now on, we now plan to **respect [Semantic Versioning](https://semver.org/)** and will release **major versions more frequently**.\\n\\n\\n\\n{/* truncate */}\\n\\n:::info We are on [ProductHunt](https://www.producthunt.com/posts/docusaurus-2-0) and [Hacker News](https://news.ycombinator.com/item?id=32303052)!\\n\\n**Now** is the best time to show your love for Docusaurus!\\n\\n<div style={{display: \'flex\'}}>\\n <ProductHuntCard />\\n <HackerNewsIcon />\\n</div>\\n\\n:::\\n\\n:::tip\\n\\nIn a hurry? Check [what\'s new in Docusaurus 2.0](#whats-new-in-20)!\\n\\n:::\\n\\n## What is Docusaurus exactly?\\n\\nDocusaurus is a **static site generator** that helps you ship **beautiful documentation websites** in **no time**.\\n\\nFocus on your content: just write **Markdown files**. Docusaurus will generate an optimized **website** for you that\'s easy to **host anywhere**.\\n\\nDocusaurus is **full-featured** and very **flexible**: we ship with well-designed docs and blog layout, as well as out-of-the-box versioning, search, and internationalization functionalities, with a call to accessibility and search engine optimizations. Its flexible theming system permits to **adapt the UI to match your branding** so that it integrates nicely with your main website or documentation portal. Its usage of **React** enables a **modern client-side navigation**, and the ability to build an **interactive documentation**.\\n\\n\\n\\nThe Docusaurus philosophy is akin to the **Pareto principle**: you can get **80% of the results** for **20% of the effort**. This enables you to compete with top-notch documentation sites with **minimal effort**.\\n\\n<TweetQuote\\n url=\\"https://x.com/rachelnabors/status/1452697991039660038\\"\\n handle=\\"rachelnabors\\"\\n name=\\"Rachel Nabors\\"\\n job=\\"Former ReactJS & React-Native docs manager\\">\\n Unless you\'re spinning up a documentation team with engineering resources, you\\n probably want Docusaurus!\\n</TweetQuote>\\n\\nDocusaurus aims to be the **best documentation tool**, but you can use it for **other use-cases** as well: a blog, a knowledge base, a developer portfolio, a second brain, or even to scaffold landing pages!\\n\\n<TweetQuote\\n url=\\"https://x.com/johnny_reilly/status/1551861926334025728\\"\\n handle=\\"johnny_reilly\\"\\n name=\\"Johnny Reilly\\"\\n job=\\"Group Principal Engineer at Investec\\">\\n Using Docusaurus for my tech blog has been a fantastic choice. It looks\\n tremendous out-of-the-box and the awesome DX means I write way more\\n</TweetQuote>\\n\\n:::tip\\n\\nTry Docusaurus now with our [online playgrounds](/docs/playground) and [5 minutes tutorial](https://tutorial.docusaurus.io/) \u23F1\uFE0F\\n\\n:::\\n\\n## The story behind Docusaurus\\n\\nDocusaurus was created at **Facebook Open Source** in **2017** (now [Meta Open Source](https://opensource.fb.com/)). We had a lot of internal and open source projects to document. It\'s **complicated enough to write good documentation**, let alone to create the HTML, CSS, and JavaScript for a good-looking website. We wanted project leaders to be able to **focus on the content**, and **Markdown** is great for that.\\n\\nAt that time, our solution was to **copy/paste a Jekyll template** over and over again. This naturally became **hard to maintain**, so we created a tool to **solve our own pain** once for all.\\n\\n**[Docusaurus v1 was born](/blog/2017/12-14-introducing-docusaurus.mdx)!**\\n\\n\\n\\nIt quickly built momentum at Facebook and in the frontend ecosystem, adopted by many popular projects such as [Prettier](https://prettier.io/), [Babel](https://babeljs.io/), [React-Native](https://archive.reactnative.dev/), [KaTeX](https://katex.org/docs/), and of course [Docusaurus v1](http://v1.docusaurus.io/) itself.\\n\\n<ShowcaseCarouselV1 />\\n\\n<br />\\n\\n:::note\\n\\nNotice that the sample sites above use different colors, but still look quite the same.\\n\\n:::\\n\\n## Toward Docusaurus 2.0\\n\\n[**Docusaurus v1**](http://v1.docusaurus.io/) has been very successful, but we started to **question some architectural choices**:\\n\\n- React was only used as a **server-side templating language**, and not used on the client\\n- **Theming system was pretty limited**, and apart from changing a few colors with CSS, it was difficult to do more advanced customizations\\n- The **docs versioning system was confusing**, since it was based on a diff algorithm\\n- The codebase was **monolithic**, neither well-tested nor easy to extend\\n\\n[**Docusaurus v2**](https://docusaurus.io/) was **rebuilt** from the ground up with a new **modular architecture**:\\n\\n- React is now also used on the client, enabling a **modern Single Page Application navigation**\\n- **Plugins** empower the community to contribute useful features as third-party packages\\n- **Theming** is more **flexible** than ever\\n- Docs versioning is now based on snapshot copies, much easier to understand\\n- We kept **everything good from v1**: docs, blog, pages, versioning, i18n...\\n- We implemented **several new features**\\n\\nMore details in the [Docusaurus 2 project announcement](/blog/2018/09-11-Towards-Docusaurus-2.mdx) and [v1 to v2 migration guide](https://docusaurus.io/docs/migration)\\n\\n## Who uses Docusaurus 2.0?\\n\\nDespite being in pre-release, it didn\'t take long for **Docusaurus v2 to outgrow Docusaurus v1** in terms of NPM downloads:\\n\\n[](https://npmtrends.com/docusaurus-vs-@docusaurus/core)\\n\\nOur GitHub star trend is very positive, competing with major frameworks:\\n\\n[](https://star-history.com/#facebook/docusaurus&vercel/next.js&gatsbyjs/gatsby&hexojs/hexo&nuxt/nuxt.js&vuejs/vuepress&11ty/eleventy&gohugoio/hugo&remix-run/remix&mkdocs/mkdocs&Timeline)\\n\\nToday, Docusaurus v2 has already been a great success even before its launch:\\n\\n- We received so many [lovely testimonials](https://x.com/sebastienlorber/timelines/1392048416872706049)\\n- Companies like [1Password](https://blog.1password.com/docusaurus-documentation-framework/) and [Courier](https://www.courier.com/blog/how-we-built-our-documentation/) are writing down their positive experience\\n- Our [site showcase](/showcase) references hundreds of sites, and this is only the tip of the iceberg.\\n\\n<ShowcaseCarouselV2 />\\n\\n<br />\\n\\n:::tip\\n\\nPlease add your site to our [site showcase](/showcase)! It only takes a few seconds: just [post a comment here](https://github.com/facebook/docusaurus/discussions/7826).\\n\\n:::\\n\\n<TweetQuote\\n url=\\"https://x.com/maxlynch/status/1549415692704825346\\"\\n handle=\\"maxlynch\\"\\n name=\\"Max Lynch\\"\\n job=\\"Ionic co-founder and CEO\\">\\n We use Docusaurus everywhere now and love it\\n</TweetQuote>\\n\\n<TweetQuote\\n url=\\"https://x.com/supabase/status/1328960757149671425\\"\\n handle=\\"supabase\\"\\n name=\\"Supabase\\"\\n job=\\"Open Source Firebase alternative\\">\\n We\'ve been using V2 since January and it has been great\\n</TweetQuote>\\n\\n<TweetQuote\\n url=\\"https://x.com/gabrielcsapo/status/1415061312917233665\\"\\n handle=\\"gabrielcsapo\\"\\n name=\\"Gabriel Csapo\\"\\n job=\\"Staff Software Engineer at LinkedIn\\">\\n Docusaurus is next level easy for literally everything you would need for\\n documentation in your project.\\n</TweetQuote>\\n\\n<TweetQuote\\n url=\\"https://x.com/ItWasMattGregg/status/1526682295075102721\\"\\n handle=\\"ItWasMattGregg\\"\\n name=\\"Matt Gregg\\"\\n job=\\"Senior Front End Developer at Shopify\\">\\n Docusaurus is awesome. We use it\\n</TweetQuote>\\n\\n## What\'s New in 2.0?\\n\\nIt would be difficult to describe every single new feature coming with Docusaurus v2. Let\'s focus on the features we believe are the **most impactful**.\\n\\n### MDX\\n\\n[MDX](https://github.com/mdx-js/mdx) allows you to **interleave React components** in Markdown. This enables you to build top-notch **interactive documentation experiences** very easily.\\n\\nA demo is worth a thousand words:\\n\\n```md title=\\"docs/my-document.mdx\\"\\n### Give it a try: press that button!\\n\\nimport ColorModeToggle from \'@theme/ColorModeToggle\';\\n\\n<ColorModeToggle/>\\n```\\n\\n```mdx-code-block\\n<BrowserWindow>\\n\\n<h3>Give it a try: press that button!</h3>\\n\\n<ColorModeToggle/>\\n\\n</BrowserWindow>\\n```\\n\\n:::info\\n\\nMDX has its own [plugin system](https://mdxjs.com/docs/extending-mdx/). You to customize your Markdown authoring experience, and even create your own Markdown syntax.\\n\\n:::\\n\\n<TweetQuote\\n url=\\"https://x.com/HamelHusain/status/1551962275250053123\\"\\n handle=\\"HamelHusain\\"\\n name=\\"Hamel Husain\\"\\n job=\\"Head Of Data Science at Outerbounds\\">\\n Docusaurus + MDX is great: we were able to implement a beautiful two-pane\\n layout and give the author fine-grained control on the placement of code and\\n corresponding prose.\\n</TweetQuote>\\n\\n### File system conventions\\n\\nOur goal is to make Docusaurus very **intuitive** to use. We added file system conventions, and adding a doc page is as easy as creating one Markdown file.\\n\\n<LiteYouTubeEmbed\\n id=\\"T3S8GyFIXjo\\"\\n params=\\"autoplay=1&autohide=1&showinfo=0&rel=0\\"\\n title=\\"Explain Like I\'m 5: Docusaurus\\"\\n poster=\\"maxresdefault\\"\\n webp\\n/>\\n\\n<br />\\n\\n<TweetQuote\\n url=\\"https://x.com/paularmstrong/status/1552005085168865281\\"\\n handle=\\"paularmstrong\\"\\n name=\\"Paul Armstrong\\"\\n job=\\"Principal Engineer at Microsoft\\">\\n Using the auto-generated sidebars makes it so simple to just create a page and\\n not worry about any other configuration.\\n</TweetQuote>\\n\\n### Plugins\\n\\nDocusaurus now has a **modular architecture** with a plugin system \u2014 our **core features** like docs, blog, pages, and search are all powered by individual plugins.\\n\\nMore importantly, it enables our community to **enhance Docusaurus** with additional features.\\n\\nLet\'s highlight some examples:\\n\\n- [redocusaurus](https://github.com/rohit-gohri/redocusaurus): seamless integration with [OpenAPI](https://www.openapis.org/) and [Redoc](https://github.com/Redocly/redoc)\\n\\n\\n\\n- [docusaurus-preset-shiki-twoslash](https://www.npmjs.com/package/docusaurus-preset-shiki-twoslash): use [Shiki](https://github.com/shikijs/shiki) code block syntax highlighting with [TwoSlash](https://shikijs.github.io/twoslash/) TypeScript compiler hints\\n\\n\\n\\n<TweetQuote\\n url=\\"https://x.com/orta\\"\\n handle=\\"orta\\"\\n name=\\"Orta Therox\\"\\n job=\\"Former TypeScript core team at Microsoft\\">\\n The plugin API was a breeze to use, and powerful enough that I could port the\\n code sample renderer from the TypeScript website site in a couple of hours.\\n</TweetQuote>\\n\\n- [docusaurus-search-local](https://github.com/easyops-cn/docusaurus-search-local): one of the various local search alternatives to the built-in Algolia plugin\\n\\n\\n\\n:::tip\\n\\nWe have a curated list of outstanding plugins in our [community resources](/community/resources) page.\\n\\n:::\\n\\n<TweetQuote\\n url=\\"https://x.com/jodyheavener/status/1551974535452311552\\"\\n handle=\\"jodyheavener\\"\\n name=\\"Jody Heavener\\"\\n job=\\"Senior Developer at 1Password\\">\\n The plugin system in Docusaurus v2 has made expanding 1Password\'s developer\\n portal so easy and fun. Super excited to show you what we\'ve got cooking up.\\n</TweetQuote>\\n\\n### Theming\\n\\nTheming is one of the most important features of Docusaurus: we believe a professional documentation site should **respect your company\'s branding** and create a consistent experience.\\n\\nDocusaurus theming gives a lot of **flexibility** on multiple levels:\\n\\n- Customize CSS variables to adjust colors, fonts, and more\\n- Provide your own CSS stylesheets\\n- Implement your own theme from scratch\\n- **Override any React component** provided by our default theme: we call this [swizzling](https://docusaurus.io/docs/swizzling)\\n\\n<TweetQuote\\n url=\\"https://x.com/hung_dev/status/1546918275065741312\\"\\n handle=\\"hung_dev\\"\\n name=\\"\\nHung Viet Nguyen\\"\\n job=\\"Creator of JestPreview\\">\\n I love Docusaurus Swizzling feature. It\u2019s opinionated and flexible at the same\\n time. This is super cool since a framework usually needs to sacrifice one for\\n the other.\\n</TweetQuote>\\n\\nThis enables users willing to invest a bit more time on **customizations** to build sites that **look different** from others.\\n\\n<ShowcaseCarouselV2Theming />\\n\\n<TweetQuote\\n url=\\"https://x.com/dabit3/status/1382855449813389315\\"\\n handle=\\"dabit3\\"\\n name=\\"Nader Dabit\\"\\n job=\\"Web3 developer, Developer DAO founder\\">\\n So far it\u2019s working out really nicely. It\u2019s been really easy to style up the\\n way that we wanted it to look. No blockers at all.\\n</TweetQuote>\\n\\n### Other features\\n\\nDocusaurus 2 comes with a very long list of useful features:\\n\\n- Theme: dark mode, better UI and UX, flexible `themeConfig` options...\\n- Docs versioning: flexible plugin options to adapt to your workflow\\n- Docs sidebar: collapsible category, category index pages...\\n- Blog: multiple authors, authors map, archive page...\\n- Markdown: tabs, math equations, live code blocks, linking, flexible front matter...\\n- Search: use the new Algolia DocSearch 3 experience\\n- Assets: make it easy to incorporate images and other kinds of files\\n- Internationalization: config options, default theme translations...\\n- Accessibility: aria labels, color contrasts, skip-to-content, keyboard navigation, progressive enhancement...\\n- SEO: sensible defaults, easy to customize, canonical url, social card, no-index, sitemap, microdata, hreflang...\\n- PWA: add offline support to your site, and make it installable\\n- Fail-fast: strict config validation, detect broken links, and prevent bad production deployments\\n- TypeScript support for config files, plugins, custom pages and theme authors\\n- Playgrounds: assess Docusaurus easily from your browser with [docusaurus.new](https://docusaurus.new)\\n- Canary releases: use the @canary npm tag to use the upcoming release before anyone else\\n- Tests: Docusaurus is well-tested, we dogfood features and ensure they keep working\\n\\n<TweetQuote\\n url=\\"https://x.com/alexbdebrie/status/1540010328335032320\\"\\n handle=\\"alexbdebrie\\"\\n name=\\"Alex DeBrie\\"\\n job=\\"AWS Data Hero, author of The DynamoDB Book\\">\\n Recently, I was shocked at how good Docusaurus is out of the box. Super solid,\\n a good bit of configuration without being overwhelming, and the ability to\\n really customize the styling if you\'re braver than I am.\\n</TweetQuote>\\n\\n## Why 2.0 now?\\n\\nMany enthusiastic followers of ours have been curious **why it took us 4 years to release Docusaurus 2.0**, considering the beta is already successful and **widely used in production**.\\n\\nThe reason is that we aim to **respect [Semantic Versioning](https://semver.org/)**, which means we will be incrementing the major version number whenever we release a **breaking change**.\\n\\nIt is important for multiple reasons:\\n\\n- It **guarantees simple minor version upgrades**, as long as you only use the [public API](/community/release-process#public-api-surface)\\n- It follows front-end ecosystem conventions\\n- A new major version is an opportunity to thoroughly document breaking changes\\n- A new major/minor version is an opportunity to communicate new features through a blog post\\n\\nThe problem is that our flexible theming system inherently creates a very **implicit API surface** on which it is **hard to know what is a breaking change** in the first place. Highly customized Docusaurus sites sometimes have a hard time upgrading Docusaurus because they achieve customizations using internal APIs. We dedicated time to extensive theme refactors and clearly defining our [public API](/community/release-process#public-api-surface), so that future code changes can be made more safely. We will continue to expand this public theming API so that the most common site customizations do not need to use any internal API.\\n\\n:::info\\n\\nFrom now on, Docusaurus will **release new major versions more frequently**. In practice, you can expect a **new major version every 2 to 4 months**.\\n\\n[Major version numbers are not sacred](https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html), but we still group breaking changes together and avoid releasing major versions too often.\\n\\nCheck our [release process](/community/release-process) documentation for details.\\n\\n:::\\n\\n## What\'s Next?\\n\\n\\n\\nThe work on Docusaurus 3.0 has started, and this next version will be released only in a few months. We will **backport retro-compatible changes in Docusaurus 2.x** minor versions to make them available as soon as possible to the community on a stable channel.\\n\\nA sample of the features on our roadmap for the upcoming major versions of Docusaurus:\\n\\n- [Upgrade to MDX 2.0](https://github.com/facebook/docusaurus/issues/4029)\\n- [Improve Markdown infrastructure](https://github.com/facebook/docusaurus/issues/4625)\\n- [Improve theming and swizzle](https://github.com/facebook/docusaurus/issues/6114)\\n- [TailwindCSS theme](https://github.com/facebook/docusaurus/issues/2961)\\n- [Theme; support custom item types for navbar, doc sidebar, blog sidebar, footer](https://github.com/facebook/docusaurus/issues/7227)\\n- [Dynamic navbar: navbar item activation strategies](https://github.com/facebook/docusaurus/issues/4389)\\n- [Custom Social Cards](https://github.com/facebook/docusaurus/issues/2968)\\n- [CSS-in-JS support](https://github.com/facebook/docusaurus/issues/3236)\\n- [Use Node.js ES Modules](https://github.com/facebook/docusaurus/issues/6520)\\n- [Improve build time performance](https://github.com/facebook/docusaurus/issues/4765)\\n- [Extend Docusaurus plugins, CMS integration](https://github.com/facebook/docusaurus/issues/4138)\\n\\n## Thank You\\n\\nWe\'d like to express our gratitude to [all our contributors](https://github.com/facebook/docusaurus/graphs/contributors), including:\\n\\n- The Docusaurus core team: [Alexey Pyltsyn](https://github.com/lex111), [Joshua Chen](https://github.com/Josh-Cena), [S\xe9bastien Lorber](https://github.com/slorber), [Yangshun Tay](https://github.com/yangshun) and all our [former team members](https://docusaurus.io/community/team)\\n- [Joel Marcey](https://github.com/JoelMarcey) for creating Docusaurus 1.0 and supporting the Docusaurus 2.0 project at Meta Open Source\\n- [Paul O\u2019Shannessy](https://github.com/zpao) for supporting the development of all the next versions of Docusaurus at Meta Open Source\\n- [Eric Nakagawa](https://github.com/ericnakagawa) for creating our cutest mascot Slash\\n- [Endilie Yacop Sucipto](https://github.com/endiliey) for his significant [initial work on Docusaurus v2](/blog/2020/01-07-tribute-to-endi.mdx)\\n- [Cl\xe9ment Vannicatte](https://github.com/shortcuts), [Kevin Granger](https://github.com/Shipow) and the whole Algolia team for their support\\n- All the community members for making valuable code contributions, improving our documentation, and answering questions on [Discord](https://discordapp.com/invite/docusaurus)\\n\\nWe\'d like to thank in particular all our **Docusaurus 2.0 early adopters** for assessing its alpha, beta and canary releases, providing a ton of **invaluable feedback**. We sincerely hope you had a great experience using it, and that you will continue to provide feedback on the upcoming pre-releases of Docusaurus 3.0.\\n\\nAt [Meta Open Source](https://opensource.fb.com/), Docusaurus is one of our **most successful projects**. We can\'t wait to see all the outstanding documentation websites that you will create! Don\'t forget to **submit them to our [site showcase](/showcase)**!\\n\\n**Now, let your imagination run wild \uD83E\uDD2A!**\\n\\n\u2014 Slash\\n\\n:::info We are on [ProductHunt](https://www.producthunt.com/posts/docusaurus-2-0) and [Hacker News](https://news.ycombinator.com/item?id=32303052)!\\n\\n\uD83D\uDE4F Share your experience using Docusaurus with the community!\\n\\n<div style={{display: \'flex\'}}>\\n <ProductHuntCard />\\n <HackerNewsIcon />\\n</div>\\n\\n:::\\n\\n"},{"id":"/2022/01/24/docusaurus-2021-recap","metadata":{"permalink":"/blog/2022/01/24/docusaurus-2021-recap","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2022/01-24-docusaurus-2021-recap/index.mdx","source":"@site/blog/2022/01-24-docusaurus-2021-recap/index.mdx","title":"Docusaurus 2021 Recap","description":"Docusaurus has made great progress in 2021! We\'ve seen a lot of traction and just crossed 30k stars on GitHub!","date":"2022-01-24T00:00:00.000Z","tags":[{"inline":false,"label":"Recap","permalink":"/blog/tags/recap","description":"Blog posts about Docusaurus\' year recaps"}],"readingTime":6.01,"hasTruncateMarker":true,"authors":[{"name":"Joshua Chen","title":"Working hard on Docusaurus","url":"https://joshcena.com/","email":"sidachen2003@gmail.com","page":{"permalink":"/blog/authors/josh-cena"},"imageURL":"https://github.com/josh-cena.png","key":"Josh-Cena"}],"frontMatter":{"title":"Docusaurus 2021 Recap","authors":["Josh-Cena"],"tags":["recap"],"image":"./img/thumbnail.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Announcing Docusaurus 2.0","permalink":"/blog/2022/08/01/announcing-docusaurus-2.0"},"nextItem":{"title":"DocSearch migration","permalink":"/blog/2021/11/21/algolia-docsearch-migration"}},"content":"Docusaurus has made great progress in 2021! We\'ve seen a lot of traction and just crossed **30k stars on GitHub**!\\n\\nWe\'ve **reached full feature parity** with v1 after [the release of internationalization](/blog/2021/03-09-releasing-docusaurus-i18n.mdx), [announced our **first beta**](/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx), and welcomed **significantly more users** this year.\\n\\nThe **official v2 release** is just around the corner! Follow the [roadmap issue](https://github.com/facebook/docusaurus/issues/6113) for any latest news.\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\n## Highlights\\n\\nLet\'s begin by going over a few highlights this year. Remember the [todo-list](/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx#whats-next) from half a year ago? Time to take it out again and see how far we\'ve come!\\n\\n- **Internationalization**: officially released four months after its initial landing in late 2020. Seen great success in [many projects](/showcase?tags=i18n)\\n- **Autogenerated sidebars**: no need to maintain a big `sidebars.js` anymore\\n- **Webpack 5**: significantly improved build performance\\n- **Trailing slash config**: seamless integration with any content hosting provider\\n- **Redesigned mobile navigation**: mobile users now enjoy all navigation features as on desktop\\n- **UI improvements**: more accessible quotes, better admonitions, back-to-top button...\\n- **Blog multi-authors**: credit all the amazing contributors that collaborated on one blog post!\\n- **More blog features**: archive page, structured data for SEO, full post content in feeds \u2013 empowering you to ship a fully-featured blog in no time\\n- **Asset collocation**: no need for a bloated static folder anymore: colocate your images with Markdown files\\n- **Sidebar category index pages**: category labels can now be associated with pages, enabling better doc organization\\n\\nOur codebase has been polished over time as well. We have improved test coverage, migrated all packages to TypeScript, and reduced our published bundle size by a maximum of 60%!\\n\\n## Trends\\n\\n### npm\\n\\nDocusaurus v2 continues to grow steadily. V2 installation is now 8 times more than v1. In terms of weekly downloads, we have witnessed another three-fold increase (+209.4%), growing from 28,066 in early January to a peak of 86,846 in mid-December.\\n\\n[](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)\\n\\n(Ah, the classic Christmas dip...)\\n\\nWe released 18 versions, going from `2.0.0-alpha.71` to `2.0.0-beta.14`. That\'s one release every 20 days!\\n\\n### GitHub\\n\\n- **Stars**: 20,460 \u2192 29,679 (+45.1% y/y). And, just before this blog post is published, we have reached 30k stars!\\n- **Total contributors**: 512 \u2192 773 (+51.0% y/y)\\n- **Dependents**: 5,039 \u2192 14,579 (+189.3% y/y) for v2, and 6,311 \u2192 7,581 (+20.1% y/y) for v1\\n- **Commits**: 1,187 commits in the past year, averaging 23 commits every week\\n- **Issues**: 619 issues opened, 505 of them eventually resolved\\n- A [**new core team member**](https://github.com/Josh-Cena) (yep, that\'s me \uD83D\uDE1D)\\n\\nOur star trend is also very positive. Compared to similar projects, we are **growing at a faster rate**:\\n\\n\\n\\nWith an 8.4k increase in stars, we are ranked number 3 in this year\'s [JavaScript rising stars of static site generators](https://risingstars.js.org/2021/en#section-ssg), preceded only by Next.js and Astro.\\n\\n\\n\\n## Featured adoptions\\n\\nOur showcase has welcomed a few new [\\"favorite\\" sites](/showcase?tags=favorite) that showcase the true potential of Docusaurus 2\'s pluggable architecture.\\n\\n- [**IOTA-wiki**](https://wiki.iota.org/)\\n\\n\\n\\n- [**Dyte**](https://docs.dyte.io/docs/home/introduction/)\\n\\n\\n\\n- [**Ionic**](https://ionicframework.com/docs)\\n\\n\\n\\n- [**Courier**](https://www.courier.com/docs/)\\n\\n\\n\\nThe creativity of Docusaurus users is beyond our imagination \uD83E\uDD29 We look forward to more and more adopters leveraging the content features of Docusaurus while exploring original theme designs! If your site uses Docusaurus, we would love to [have it in our showcase](https://github.com/facebook/docusaurus/edit/main/website/src/data/users.tsx).\\n\\n## Community\\n\\nAs an active moderator on [Discord](https://discord.gg/docusaurus), I can clearly see the community thriving. Many frequently asked questions are now integrated into our documentation, and some feature requests have been implemented as well. The project and the community reciprocally benefit each other \u2013 case in point, I was formerly a community contributor before becoming a maintainer.\\n\\nWe are constantly mentioned on X with inspirational feedback:\\n\\n> **@docusaurus** is amazing! cant believe it\'s THAT simple to use.\\n\\n> No extra plugins, tooling or compilation steps. It just works out of the box.\\n\\n> I love **@docusaurus**. I couldn\'t have built the APIs, tutorials, and blogs contained in my site efficiently and beautifully in my workflow without Docusaurus.\\n\\nAnd we keep every one of them in [our little box](https://x.com/sebastienlorber/timelines/1392048416872706049) \uD83D\uDE04 If you enjoy Docusaurus yourself, keep tagging us with your comments!\\n\\nAs we approach the official release, we are interested in knowing more about what people are doing out there: [plugin authors](https://github.com/facebook/docusaurus/discussions/4025), [creators of customized sites](https://github.com/facebook/docusaurus/discussions/5468), and [all new users](https://github.com/facebook/docusaurus/discussions/4610) \u2013 please keep us posted about your achievements so we can steer our development to better serve your needs.\\n\\n## Going forward\\n\\nIn the past few months, we have been constantly speaking about the release-candidate phase of Docusaurus, and yes, it\'s almost there. We have created a dedicated [milestone](https://github.com/facebook/docusaurus/milestone/15) to keep track of all issues to solve before we can confidently progress to the next stage. In short, we want to build a **more robust theming workflow**, empowering creative site creators to customize our default theme without fearing breaking changes as they upgrade. This will include:\\n\\n- Guidelines on **component organization**. We want the theme components to have the right granularity so when you want to customize a part of your site, there\'s always a component doing just what you need.\\n- Improvements to the **swizzle CLI**. We want users to use it with delight and let it aid you through all possible swizzling scenarios.\\n- Refactoring our **theme APIs**. We want all swizzlable components to be actually appropriate for swizzling, so non-UI components will be re-located.\\n- **Docs**. We want our docs to be maximally accessible to everyone \u2013 from first-time coders to experienced web developers. We will organize it as a more progressive tutorial that can be beneficial for every skill level.\\n\\nRead more about plans for Docusaurus 2.0 in this [roadmap issue](https://github.com/facebook/docusaurus/issues/6113). 2.0 will be a greater release with the help from the community, so please share your opinions and suggestions under any of the milestone issues!\\n\\nAs the core team is working hard to ship the general availability release, we plan to release other useful features as minor versions after 2.0. We have even made further plans for [architectural changes in 3.0](https://github.com/facebook/docusaurus/milestone/16)!\\n\\nWith the official release of Docusaurus 2.0, we are confident to see much more new adoptions and migrations from v1.\\n\\nWe\'d like to express our gratitude to [all the contributors in 2021](https://github.com/facebook/docusaurus/graphs/contributors?from=2021-01-01&to=2022-01-01&type=c), including:\\n\\n- The core team: [Alexey Pyltsyn](https://github.com/lex111), [S\xe9bastien Lorber](https://github.com/slorber), [Joshua Chen](https://github.com/Josh-Cena), and [Yangshun Tay](https://github.com/yangshun) for moderating the community, publicizing Docusaurus, triaging issues, and implementing new features\\n- [Joel Marcey](https://github.com/JoelMarcey) for creating Docusaurus and supporting its development all along\\n- The Algolia team for helping Docusaurus users [migrate to the new DocSearch](/blog/2021/11-21-algolia-docsearch-migration/index.mdx) and answering search-related questions\\n- All the active community members for making valuable code contributions, improving our documentation, and answering questions on Discord\\n\\nSo long, 2021, and let\'s greet a great 2022!"},{"id":"/2021/11/21/algolia-docsearch-migration","metadata":{"permalink":"/blog/2021/11/21/algolia-docsearch-migration","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2021/11-21-algolia-docsearch-migration/index.mdx","source":"@site/blog/2021/11-21-algolia-docsearch-migration/index.mdx","title":"DocSearch migration","description":"DocSearch is migrating to a new, more powerful system, which gives users their own Algolia application and new credentials.","date":"2021-11-21T00:00:00.000Z","tags":[{"inline":false,"label":"Search","permalink":"/blog/tags/search"}],"readingTime":2.96,"hasTruncateMarker":true,"authors":[{"name":"Cl\xe9ment Vannicatte","title":"Software Engineer @ Algolia","url":"https://github.com/shortcuts","socials":{"x":"https://x.com/sh0rtcts","github":"https://github.com/shortcuts"},"imageURL":"https://github.com/shortcuts.png","key":"shortcuts","page":null},{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"DocSearch migration","authors":["shortcuts","slorber"],"tags":["search"],"image":"./img/social-card.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 2021 Recap","permalink":"/blog/2022/01/24/docusaurus-2021-recap"},"nextItem":{"title":"Announcing Docusaurus 2 Beta","permalink":"/blog/2021/05/12/announcing-docusaurus-two-beta"}},"content":"[DocSearch](https://docsearch.algolia.com/) is migrating to a new, more powerful system, which gives users their own Algolia application and new credentials.\\n\\nDocusaurus site owners should upgrade their configuration with their new credentials **by February 1, 2022**, existing search indexes will be frozen and become read-only after this date.\\n\\n\x3c!--truncate--\x3e\\n\\n## Upgrading your Docusaurus site\\n\\nIn the next few weeks, Docusaurus site owners will receive an email inviting them to join their personal Algolia application.\\n\\nThis email will include a new `appId` and `apiKey` to use in your Docusaurus configuration.\\n\\nThe only things you have to do:\\n\\n- Join the Algolia application (eventually creating a new Algolia account)\\n- Update your site configuration.\\n\\n```js title=\\"docusaurus.config.js\\"\\nconst config = {\\n themeConfig: {\\n algolia: {\\n // highlight-start\\n appId: \'<NEW_APP_ID>\',\\n apiKey: \'<NEW_SEARCH_API_KEY>\',\\n // highlight-end\\n },\\n },\\n};\\n\\nmodule.exports = config;\\n```\\n\\n:::info\\n\\n`appId` is now **required**.\\n\\nThese keys are not secrets and can be added to your Git repository.\\n\\n:::\\n\\n## DocSearch has a new home!\\n\\n### What is DocSearch?\\n\\n[DocSearch](https://docsearch.algolia.com/) is a program created by [Algolia](http://algolia.com/), which offers search to technical documentation of Open Source projects and technical blogs **for free**.\\n\\nYou can [read more here](https://docsearch.algolia.com/docs/what-is-docsearch/), and [apply](https://docsearch.algolia.com/apply) if you\'d like to give it a try!\\n\\n## What is this migration about?\\n\\n### Motivation\\n\\nWith the upcoming stable release of [DocSearch UI](https://docsearch.algolia.com/docs/DocSearch-v3), we wanted to go further and provide better tooling for our users to improve their search, but also leverage the full potential of Algolia.\\n\\n### What\'s new?\\n\\nDocSearch now leverages the [Algolia Crawler](https://www.algolia.com/products/search-and-discovery/crawler/), which includes a web interface that will allow you to:\\n\\n- Start, schedule and monitor your crawls\\n- Edit your config file from a live editor\\n- Test your results with DocSearch v3\\n\\n\\n\\n\\n\\nBut also, more Algolia features in **your own Algolia app**:\\n\\n- Team management\\n- Browse and see how your records are indexed in Algolia\\n- Try other Algolia features with free trials\\n\\n\\n\\n\\n\\nAnd of course, **a lot more, for free**.\\n\\n## FAQ\\n\\n### I\'m using Docusaurus and DocSearch, can I migrate? {#im-using-docusaurus-and-docsearch-can-i-migrate}\\n\\nAt the time we are writing this, we are still at an early stage of the migration. We are doing small batches every week but will increase the load shortly, so please be patient and keep an eye out in your mailbox, you\'ll be contacted as soon as your Algolia app is ready!\\n\\n### Where can I read more about this?\\n\\nWe wrote a small [migration guide](https://docsearch.algolia.com/docs/migrating-from-legacy) but you\'ll have more detailed information in the migration email.\\n\\n### I received the migration email but the invite expired\\n\\nPlease contact us via either [email](mailto:docsearch@algolia.com) or [DocSearch\'s Discord](https://discord.gg/bRTacwYrfX) or on [Docusaurus\'s Discord #algolia channel](https://discordapp.com/invite/docusaurus)\\n\\n### I have feedback!\\n\\nFor any feedback regarding our documentation or the DocSearch UI component, you can open an issue [on our GitHub repository](https://github.com/algolia/docsearch/issues), but also contact us via the methods above.\\n\\n### Can I still run my own DocSearch instance?\\n\\nIn favor of the new infrastructure and DocSearch v3, we will no longer maintain our beloved [DocSearch scraper](https://github.com/algolia/docsearch-scraper) and [DocSearch v2](https://github.com/algolia/docsearch/tree/master), but the repositories will still be available and open to pull requests.\\n\\nThe previous documentation (now called `legacy`) remains available as well as our [`run your own`](https://docsearch.algolia.com/docs/legacy/run-your-own) guide."},{"id":"/2021/05/12/announcing-docusaurus-two-beta","metadata":{"permalink":"/blog/2021/05/12/announcing-docusaurus-two-beta","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx","source":"@site/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx","title":"Announcing Docusaurus 2 Beta","description":"After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first Docusaurus 2 beta.","date":"2021-05-12T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"},{"inline":false,"label":"Beta","permalink":"/blog/tags/beta"}],"readingTime":3.52,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{},"imageURL":"./img/slorber.png","key":"slorber","image_url":"./img/slorber.png"},{"name":"Joel Marcey","title":"Developer Advocate at Meta","url":"https://x.com/JoelMarcey","page":{"permalink":"/blog/authors/j-marcey"},"socials":{"x":"https://x.com/joelmarcey","github":"https://github.com/JoelMarcey"},"imageURL":"https://github.com/JoelMarcey.png","key":"JMarcey"},{"name":"Yangshun Tay","title":"Front End Engineer at Meta","url":"https://github.com/yangshun","page":{"permalink":"/blog/authors/yangshun"},"socials":{"x":"https://x.com/yangshunz","github":"https://github.com/yangshun"},"imageURL":"https://github.com/yangshun.png","key":"yangshun"},{"name":"Alexey Pyltsyn","title":"Open-source enthusiast","url":"https://github.com/lex111","email":"lex@php.net","page":{"permalink":"/blog/authors/lex-111"},"imageURL":"https://github.com/lex111.png","key":"lex111"}],"frontMatter":{"title":"Announcing Docusaurus 2 Beta","authors":[{"key":"slorber","image_url":"./img/slorber.png","imageURL":"./img/slorber.png"},"JMarcey","yangshun","lex111"],"tags":["release","beta"],"image":"./img/social-card.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"DocSearch migration","permalink":"/blog/2021/11/21/algolia-docsearch-migration"},"nextItem":{"title":"Releasing Docusaurus i18n","permalink":"/blog/2021/03/09/releasing-docusaurus-i18n"}},"content":"After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first **[Docusaurus 2 beta](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-beta.0)**.\\n\\nWith the announcement of this beta, the team is even more confident that Docusaurus 2 is **ready for mainstream adoption**!\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\n## Docusaurus adoption\\n\\n**Don\'t fear the beta tag!**\\n\\nDocusaurus 2 is widely adopted and growing fast:\\n\\n[](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)\\n\\nTo get a fuller understanding of the quality of current Docusaurus 2 sites, our new [showcase](https://docusaurus.io/showcase) page allows you to filter Docusaurus sites by features, so you may get inspired by real-world production sites with a similar use-case as yours!\\n\\nDon\'t miss our [favorite](https://docusaurus.io/showcase?tags=favorite) sites; they all stand out with something unique:\\n\\n[](https://docusaurus.io/showcase?tags=favorite)\\n\\n## Why was Docusaurus v2 in alpha for so long?\\n\\nIt\'s hard to believe that the first alpha release [v2.0.0-alpha.0](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.0) was 2 years ago \uD83D\uDE33 , unusually long for a software alpha.\\n\\nAs this was a substantial re-architecture of the code base, we wanted to ensure that we had confidence in the stability and features of Docusaurus 2 before moving on to a beta stage, since beta suggests a high level of quality. We are happy to say that Docusaurus 2 has reached **feature parity** with Docusaurus 1 with **[i18n](https://docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n)**, and it has been **successfully adopted** by many Docusaurus sites (see [i18n showcase](https://docusaurus.io/showcase?tags=i18n)).\\n\\nWe\'re now quite confident that the core features of Docusaurus 2 are stable enough to be in beta.\\n\\n## What are the goals of the beta?\\n\\nNow that Docusaurus 2 is stable and major feature complete, the goal of the beta is to inspire confidence in new users on the production-readiness of Docusaurus 2, migrate more remaining Docusaurus 1 users to version 2, and officially deprecate Docusaurus 1. We will, of course, continue to resolve any issues and bugs that may be discovered.\\n\\nIn addition, we will use the beta phase to **improve our theming system**.\\n\\nWe want to make it:\\n\\n- **easier to implement a custom theme**, including for ourselves. We want to provide [multiple official themes](https://github.com/facebook/docusaurus/issues/3522) (including [Tailwind CSS](https://github.com/facebook/docusaurus/issues/2961)) for a long time.\\n\\n- **safer to extend an existing theme**: it can be painful to upgrade a highly customized Docusaurus site, as customizations can conflict with internal changes. We need to make the theme public API surface more explicit, and make it clear what is safe to customize.\\n\\nWe will build a better **theming infrastructure** and refactor the classic theme to use it.\\n\\nIf you customize your site, you may find these planned improvements quite valuable.\\n\\n## What\'s new?\\n\\nIn case you missed it, we recently shipped two major improvements:\\n\\n- [Auto-generated sidebars](https://docusaurus.io/docs/sidebar#sidebar-item-autogenerated): no need to maintain a `sidebars.js` file anymore!\\n- [Webpack 5 / PostCSS 8](https://github.com/facebook/docusaurus/issues/4027): persistent caching significantly speeds up **rebuild time**!\\n\\n## What\'s next?\\n\\nShipping the official 2.0 release!\\n\\nTo get there, we will continue to **fix bugs** and implement the **most wanted features**, including:\\n\\n- [Sidebar category index pages](https://github.com/facebook/docusaurus/issues/2643)\\n- [Better mobile navigation UX](https://github.com/facebook/docusaurus/issues/2220)\\n- [Better admonition design](https://github.com/facebookincubator/infima/issues/55)\\n- [CSS-in-JS support](https://github.com/facebook/docusaurus/issues/3236)\\n- [Improve build time performance](https://github.com/facebook/docusaurus/issues/4765)\\n- [Extend Docusaurus plugins, CMS integration](https://github.com/facebook/docusaurus/issues/4138)\\n- [Fix trailing slashes and relative link issues](https://github.com/facebook/docusaurus/issues/3372)\\n- [Better compatibility with CommonMark](https://github.com/facebook/docusaurus/issues/3018)\\n- [Upgrade to MDX 2.0](https://github.com/facebook/docusaurus/issues/4029)\\n\\n## Conclusion\\n\\nThis is an exciting time for Docusaurus.\\n\\nWe are inspired by the [positive feedback](https://x.com/sebastienlorber/timelines/1392048416872706049) about Docusaurus, and discover new sites online every single day.\\n\\nWe are so excited for this beta release. We strove for quality and stability while continuing to try to increase the adoption of Docusaurus. For those that have been on the fence from migrating an existing Docusaurus site to Docusaurus 2, it is a great time to upgrade. We want you running on the latest infrastructure when we deprecate Docusaurus 1 at the end of this beta period. Let us know how we can help.\\n\\nThank you to everyone for reading and to the entire community who supports Docusaurus. \uD83E\uDD17"},{"id":"/2021/03/09/releasing-docusaurus-i18n","metadata":{"permalink":"/blog/2021/03/09/releasing-docusaurus-i18n","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2021/03-09-releasing-docusaurus-i18n.mdx","source":"@site/blog/2021/03-09-releasing-docusaurus-i18n.mdx","title":"Releasing Docusaurus i18n","description":"Today, we officially release Docusaurus 2 i18n (internationalization), as part of 2.0.0-alpha.71.","date":"2021-03-09T00:00:00.000Z","tags":[{"inline":false,"label":"Release","permalink":"/blog/tags/release","description":"Blog posts about Docusaurus\' new releases"},{"inline":false,"label":"I18n","permalink":"/blog/tags/i-18-n"}],"readingTime":3.445,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Releasing Docusaurus i18n","authors":["slorber"],"tags":["release","i18n"],"image":"/img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Announcing Docusaurus 2 Beta","permalink":"/blog/2021/05/12/announcing-docusaurus-two-beta"},"nextItem":{"title":"Docusaurus 2020 Recap","permalink":"/blog/2021/01/19/docusaurus-2020-recap"}},"content":"Today, we officially release **[Docusaurus 2 i18n](https://docusaurus.io/docs/i18n/introduction)** ([internationalization](https://en.wikipedia.org/wiki/Internationalization_and_localization)), as part of [2.0.0-alpha.71](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.71).\\n\\nDocusaurus 2 has now reached **full feature parity with Docusaurus 1**. \uD83C\uDF89 And soon, after a few additional infrastructure updates and a bit more testing, the **first Docusaurus 2 beta** will be released.\\n\\n**We went the extra mile**, and the new i18n support is **even better than in Docusaurus 1**.\\n\\nIn this post, we will present you the **translation workflow**, explain some **design decisions** and **showcase early adopter sites** that just went live: [Jest](https://jestjs.io/), [Redwood](https://learn.redwoodjs.com/), and [Datagit](https://datagit.ir/).\\n\\nWe also **dogfood** the i18n support on the **Docusaurus 2 site itself**, and this post is already available in [English](https://docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n) and [French](https://docusaurus.io/fr/blog/2021/03/09/releasing-docusaurus-i18n)!\\n\\n\x3c!--truncate--\x3e\\n\\n## Translate your site\\n\\nYou can translate a Docusaurus site in **3 simple steps**:\\n\\n1. **Configure**: declare the default locale and alternative locales in `docusaurus.config.js`\\n1. **Translate**: put the translation files at the [correct filesystem location](https://docusaurus.io/docs/next/i18n/introduction#translation-files-location)\\n1. **Deploy**: build and deploy your site using a single or multi-domain strategy\\n\\nThe i18n support is **very flexible** and based on the **filesystem**.\\n\\nThe **[i18n tutorial](https://docusaurus.io/docs/i18n/tutorial)** is the best way to get started, and we provide help to use **[Git](https://docusaurus.io/docs/i18n/git)** or **[Crowdin](https://docusaurus.io/docs/i18n/crowdin)**.\\n\\n## Design decisions\\n\\nThe goals of the Docusaurus i18n system are:\\n\\n- **Simple**: just put the translated files in the [correct filesystem location](https://docusaurus.io/docs/next/i18n/introduction#translation-files-location)\\n- **Flexible translation workflows**: use Git (monorepo, forks, or submodules), SaaS software, FTP\\n- **Flexible deployment options**: single, multiple domains, or hybrid\\n- **Modular**: allow plugin authors to provide i18n support\\n- **Low-overhead runtime**: documentation is mostly static and does not require a heavy JS library or polyfills\\n- **Scalable build-times**: allow building and deploying localized sites independently\\n- **Localize assets**: an image of your site might contain text that should be translated\\n- **No coupling**: not forced to use any SaaS, yet integrations are possible\\n- **Easy to use with [Crowdin](https://crowdin.com/)**: multiple Docusaurus 1 sites use Crowdin, and should be able to migrate to v2\\n- **Good SEO defaults**: we set useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you\\n- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement\\n- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales)\\n\\n## Showcase\\n\\nWe worked with a few volunteers to **dogfood the i18n support** before releasing it.\\n\\n### Jest: upgrading Docusaurus\\n\\nWe have made it possible to **upgrade** a **translated Docusaurus 1 site** to Docusaurus 2.\\n\\n**[Jest](https://jestjs.io)**, using Docusaurus 1 and Crowdin was one of those sites.\\n\\nThe Docusaurus 2 migration was successful and the new site is now deployed in production ([announcement post](https://jestjs.io/blog/2021/03/09/jest-website-upgrade)).\\n\\n[](https://jestjs.io)\\n\\n### Redwood: adopting Docusaurus\\n\\n[Redwood](https://redwoodjs.com/) is a React full-stack Jamstack framework.\\n\\nThey were looking for a solution to create an **internationalized learning platform**, and became early adopters of Docusaurus 2 i18n for [learn.redwoodjs.com](https://learn.redwoodjs.com/), using Crowdin to get it translated to French.\\n\\n[](https://learn.redwoodjs.com/)\\n\\n### Datagit: using LTR support\\n\\nThe i18n system should work with any language, including **Right-to-Left languages**.\\n\\n[Datagit.ir](https://datagit.ir/) is using Farsi, and a simple configuration option is able to **flip the Docusaurus theme** to add the required Right-to-Left support.\\n\\n[](https://datagit.ir/)\\n\\n## Conclusion\\n\\nWe sincerely hope you will adopt and like the new i18n support.\\n\\nThis feature has not been an easy one, and we would like to thank everyone that got involved in this journey:\\n\\n- [Alexey](https://github.com/lex111) for his help to make the i18n support exhaustive and even better than v1\\n- [Simen](https://github.com/SimenB) for volunteering and supporting the Jest migration\\n- [Claire](https://github.com/clairefro) for adopting Docusaurus 2 on the new Redwood platform and providing many feedbacks\\n- [Massoud](https://github.com/massoudmaboudi) for reviewing my work on LTR and adopting it on Datagit\\n- [Crowdin](https://crowdin.com/) for their support and willingness to improve their translation SaaS\\n- The Docusaurus community for their patience, and providing many useful feedbacks on GitHub\\n\\nThanks for reading.\\n\\n\uD83D\uDE4F And please, add your brand new i18n sites to our [showcase page](https://docusaurus.io/showcase). We accept any all polished Docusaurus site here, and we are working on a [redesign](https://github.com/facebook/docusaurus/issues/4238) allowing you to filter sites by features."},{"id":"/2021/01/19/docusaurus-2020-recap","metadata":{"permalink":"/blog/2021/01/19/docusaurus-2020-recap","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2021/01-19-docusaurus-2020-recap.mdx","source":"@site/blog/2021/01-19-docusaurus-2020-recap.mdx","title":"Docusaurus 2020 Recap","description":"2020 was great for Docusaurus, despite a regrettable start and a tumultuous year for everyone.","date":"2021-01-19T00:00:00.000Z","tags":[{"inline":false,"label":"Recap","permalink":"/blog/tags/recap","description":"Blog posts about Docusaurus\' year recaps"}],"readingTime":5.04,"hasTruncateMarker":true,"authors":[{"name":"S\xe9bastien Lorber","title":"Docusaurus maintainer, This Week In React editor","url":"https://thisweekinreact.com","page":{"permalink":"/blog/authors/slorber"},"description":"A freelance React and React-Native developer near Paris and Docusaurus maintainer. Also runs ThisWeekInReact.com, a newsletter to stay updated with the React ecosystem.","socials":{"bluesky":"https://bsky.app/profile/sebastienlorber.com","x":"https://x.com/sebastienlorber","linkedin":"https://www.linkedin.com/in/sebastienlorber/","github":"https://github.com/slorber","instagram":"https://www.instagram.com/thisweekinreact","newsletter":"https://thisweekinreact.com"},"imageURL":"https://github.com/slorber.png","key":"slorber"}],"frontMatter":{"title":"Docusaurus 2020 Recap","authors":["slorber"],"tags":["recap"],"image":"/img/docusaurus-2020-recap.png"},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Releasing Docusaurus i18n","permalink":"/blog/2021/03/09/releasing-docusaurus-i18n"},"nextItem":{"title":"Tribute to Endi","permalink":"/blog/2020/01/07/tribute-to-endi"}},"content":"**2020 was great for Docusaurus**, despite [a regrettable start](https://docusaurus.io/blog/2020/01/07/tribute-to-endi) and a tumultuous year for everyone.\\n\\nWe continued to invest in [Docusaurus 2](https://docusaurus.io/), and made it reach **full feature parity** with [Docusaurus 1](https://v1.docusaurus.io/).\\n\\nWe now **recommend Docusaurus 2** as the **default choice** to start a new Docusaurus project and encourage v1 users to [migrate to Docusaurus 2](https://docusaurus.io/docs/migration).\\n\\nWe are **still in alpha**, but expect **some good news very soon**!\\n\\n\\n\\n\x3c!--truncate--\x3e\\n\\n## Docusaurus 2 highlights\\n\\nWe have worked on many features this year, and would like to highlight the most significant ones:\\n\\n- **i18n**: easily translate your Docusaurus site, released soon! ([preview](https://github.com/facebook/docusaurus/pull/3325), [doc](https://docusaurus.io/docs/next/i18n/introduction))\\n- **Version dropdown**: enable contextual version switch\\n- **Versioning options**: solving the most common pain-points users had with versioning\\n- **Contextual search**: search in the current version, use the brand-new DocSearch 3 experience\\n- **Markdown pages**: use Markdown instead of React components to create standalone pages\\n- **Better theme**: various UI, UX and accessibility improvements\\n- **PWA**: add offline support to your site, and make it installable\\n- **Fail-fast**: strict config validation, detect broken links, and prevent bad production deployments\\n- **Multi-instance**: use the docs plugin twice on a single site (e.g. iOS/Android SDK docs)\\n- **Migration CLI**: automate the upgrade from Docusaurus 1\\n- **CodeSandbox**: assess Docusaurus easily from your browser with [new.docusaurus.io](https://new.docusaurus.io/)\\n- **Canary releases**: use the `@canary` npm tag to use the upcoming release before anyone else\\n- **TypeScript**: progressive adoption for internal code, and improve usage for users\\n- **Publish Infima**: it is now [open-source](https://github.com/facebookincubator/infima)\\n\\n## Docusaurus 2 growth\\n\\nThe plan to [rebuild Docusaurus from scratch in 2019](https://docusaurus.io/blog/2019/12/30/docusaurus-2019-recap) paid off: after a slow start, Docusaurus 2 has been widely adopted and has **already outgrown Docusaurus 1** usage.\\n\\n\\n\\nNotable **projects, startups, large companies, and individuals** adopted Docusaurus 2 ([showcase](https://docusaurus.io/showcase)):\\n\\n- [Supabase](https://supabase.io)\\n- [React Navigation](https://reactnavigation.org)\\n- [React Redux](https://react-redux.js.org/)\\n- [Vector](https://vector.dev)\\n- [Algolia DocSearch](https://docsearch.algolia.com)\\n- [SAP Cloud SDK](https://sap.github.io/cloud-sdk)\\n- [Palo Alto Cortex XSOAR](https://xsoar.pan.dev)\\n- [Qudd\xfas George\'s website](https://portfoliosaurus.now.sh)\\n\\nWe helped **large scale Docusaurus 1 sites to upgrade**, ensuring a proper **migration path** and **feature parity**.\\n\\n[React Native](https://reactnative.dev/) was successfully upgraded to Docusaurus 2 ([archived v1 site](http://archive.reactnative.dev/)):\\n\\n\\n\\nLocalized Docusaurus 1 sites (like **Jest**) will be able to upgrade too:\\n\\n\\n\\nWe also saw the **[first right-to-left](https://datagit.ir/)** Docusaurus 2 site published:\\n\\n\\n\\n## GitHub Activity\\n\\n- **Stars**: 14632 \u2192 20946 (+43.2% y/y)\\n- **Total Contributors**: 303 \u2192 512 (+68.9% y/y). Most of which are non-Facebook contributors\\n- **Weekly npm Downloads**: 2356 \u2192 25592 (+986% y/y)\\n- **On GitHub**, Docusaurus 1 is used by 6311 projects (+62.9% y/y) while Docusaurus 2 is used by 5039 projects (+1940% y/y)\\n\\n## Collaboration with Major League Hacking\\n\\nWe have welcomed [Major League Hacking](https://mlh.io/) (MLH) fellows for 2 seasons already.\\n\\nWe are very thankful for the **various contributions** they made, such as:\\n\\n- Writing the foundations of the v1 to v2 migration CLI\\n- Help migrate the React Native website from v1 to v2\\n- Making the config validation more strict and exhaustive, returning helpful error messages\\n- Adding CodeSandbox support\\n- Improving the CI pipelines: build size and Lighthouse bots\\n\\nWe look forward to continuing this collaboration in 2021.\\n\\n## Media\\n\\nDmitry Vinnik (Developer Advocate @ Facebook) explains Docusaurus in [60 seconds](https://www.youtube.com/watch?v=_An9EsKPhp0) or [15min](https://www.youtube.com/watch?v=Yhyx7otSksg) videos.\\n\\nRachel Nabors (Documentation Engineer @ Facebook) talked a bit about Docusaurus in [React Native Radio 178 (podcast)](https://reactnativeradio.com/episodes/178-documenting-react-native-with-rachel-nabors-gWxwySPl), and William Candillon the [React Native website migration (video)](https://www.youtube.com/watch?v=-zhjq2ECKq4).\\n\\nMany blog posts have been published:\\n\\n- [To the Makers of Docusaurus](https://portfoliosaurus.now.sh/blog/toTheMakers) by Quddus George\\n- [Richer API documentation with Redoc and Docusaurus](https://davidgoss.co/blog/api-documentation-redoc-docusaurus/) by David Goss\\n- [How to Build a Plugin for Docusaurus v2](https://aknapen.nl/blog/how-to-build-a-plugin-for-docusaurus-v2/) by Adriaan Knapen\\n- [React Tracked Documentation Website with Docusaurus v2](https://blog.axlight.com/posts/react-tracked-documentation-website-with-docusaurus-v2/) by Daishi Kato\\n- [Easy documentation with Docusaurus](https://blog.logrocket.com/easy-documentation-with-docusaurus/) by Anshul Goyal (MLH fellow)\\n- [Build Beautiful Documentation Websites with Docusaurus](https://lo-victoria.com/build-beautiful-documentation-websites-with-docusaurus) by Victoria Lo\\n\\n## Community\\n\\nThe Docusaurus community continues to grow, the [Discord](https://discord.gg/docusaurus) server is quite active, and [Stack Overflow questions](https://stackoverflow.com/questions/tagged/docusaurus) keep being posted.\\n\\nThe **modular architecture** of Docusaurus 2 allowed the community to build and publish [third-party plugins](https://docusaurus.io/community/resources#community-plugins-). As we would like to federate better our community, if you are building a plugin, please [let us know](https://github.com/facebook/docusaurus/discussions/4025).\\n\\n## What\'s next?\\n\\nAs the **core features of Docusaurus 2** have finally been built, we will be able to dedicate more time to solve the pain points and bugs reported by the community, and make Docusaurus stable and convenient enough to enter the **beta and release-candidate phase**.\\n\\nWith proper support for **i18n and versioning**, and **large scale migrations** such as **React Native** and **Jest**, we now have a clear migration path for all Docusaurus 1 sites.\\n\\nWe still have a few **major features** that we would like to work on:\\n\\n- [Create a theme gallery](https://github.com/facebook/docusaurus/issues/3522), make it easy to switch from one another, and include **first-class Tailwind support**\\n- [Upgrade to Webpack 5](https://github.com/facebook/docusaurus/issues/4027), improve performances and build times\\n- [Better compatibility with CommonMark](https://github.com/facebook/docusaurus/issues/3018), as MDX and makes it harder for CommonMark-based sites to adopt Docusaurus\\n- [Upgrade to MDX 2.0](https://github.com/facebook/docusaurus/issues/4029)\\n- Other tasks that we might discover during 2021\\n\\nHuge thanks to the community for [their contributions in 2020](https://github.com/facebook/docusaurus/graphs/contributors?from=2020-01-01&to=2021-01-01&type=c), especially:\\n\\n- [Joel Marcey](https://github.com/JoelMarcey) for creating Docusaurus and supporting the project all this time\\n- the core team - [Alexey Pyltsyn](https://github.com/lex111), [S\xe9bastien Lorber](https://sebastienlorber.com), [Yangshun Tay](https://x.com/yangshunz)\\n- the Major League Hacking and Facebook interns for their significant impact\\n- the Algolia team for DocSearch 3 and their support\\n- [Bartosz Kaszubowski](https://github.com/Simek) for his investment in the React Native migration\\n- the whole community for their contributions, and providing support to each other\\n\\nCheers to a great 2021! \uD83C\uDF89"},{"id":"/2020/01/07/tribute-to-endi","metadata":{"permalink":"/blog/2020/01/07/tribute-to-endi","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2020/01-07-tribute-to-endi.mdx","source":"@site/blog/2020/01-07-tribute-to-endi.mdx","title":"Tribute to Endi","description":"It is with great sadness to announce that our primary external Docusaurus contributor, Endilie Yacop Sucipto (Endi to those who knew him), passed away over the weekend after an illness associated with his bout with cancer.","date":"2020-01-07T00:00:00.000Z","tags":[{"inline":false,"label":"Endi","permalink":"/blog/tags/endi"},{"inline":false,"label":"Tribute","permalink":"/blog/tags/tribute"}],"readingTime":0.895,"hasTruncateMarker":true,"authors":[{"name":"Joel Marcey","title":"Developer Advocate at Meta","url":"https://x.com/JoelMarcey","page":{"permalink":"/blog/authors/j-marcey"},"socials":{"x":"https://x.com/joelmarcey","github":"https://github.com/JoelMarcey"},"imageURL":"https://github.com/JoelMarcey.png","key":"JMarcey"}],"frontMatter":{"title":"Tribute to Endi","authors":"JMarcey","tags":["endi","tribute"]},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 2020 Recap","permalink":"/blog/2021/01/19/docusaurus-2020-recap"},"nextItem":{"title":"Docusaurus 2019 Recap","permalink":"/blog/2019/12/30/docusaurus-2019-recap"}},"content":"It is with great sadness to announce that our primary external Docusaurus contributor, [Endilie Yacop Sucipto](https://github.com/endiliey) (Endi to those who knew him), [passed away](https://give.asia/campaign/help_endi_beat_cancer#/updates) over the weekend after an illness associated with his bout with cancer.\\n\\n\x3c!--truncate--\x3e\\n\\nIt is impossible to overstate Endi\'s impact on this project:\\n\\n- Docusaurus\' top contributor, [by far](https://github.com/facebook/docusaurus/graphs/contributors).\\n- [Lead developer](https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2) on the nearly complete [version 2 of Docusaurus](https://docusaurus.io/blog/2019/12/30/docusaurus-2019-recap).\\n- Overall passionate advocate of the project on [X](https://x.com/endiliey), [Discord](https://discord.gg/docusaurus) and other social media\\n\\nThinking about it now, it is absolutely amazing how much Endi accomplished on Docusaurus given what he was battling with his health.\\n\\nWe are working on ways to honor Endi\'s contributions - a commemorative sticker, possibly - and we are open to ideas. Leave a comment here or [tweet](https://x.com/docusaurus) if you have a suggestion.\\n\\nThe Docusaurus project will not be the same without Endi, and those of us who worked with him will miss him greatly. \uD83D\uDE14\\n\\n"},{"id":"/2019/12/30/docusaurus-2019-recap","metadata":{"permalink":"/blog/2019/12/30/docusaurus-2019-recap","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2019/12-30-docusaurus-2019-recap.mdx","source":"@site/blog/2019/12-30-docusaurus-2019-recap.mdx","title":"Docusaurus 2019 Recap","description":"2019 was a great year for Docusaurus - we\'ve made tremendous progress on Docusaurus 2. Current Docusaurus 1 users who aren\'t using the translations feature can feel free to check it out and migrate to it! Otherwise we will work with you to make that happen in 2020 :)","date":"2019-12-30T00:00:00.000Z","tags":[{"inline":false,"label":"Recap","permalink":"/blog/tags/recap","description":"Blog posts about Docusaurus\' year recaps"}],"readingTime":2.72,"hasTruncateMarker":true,"authors":[{"name":"Yangshun Tay","title":"Front End Engineer at Meta","url":"https://github.com/yangshun","page":{"permalink":"/blog/authors/yangshun"},"socials":{"x":"https://x.com/yangshunz","github":"https://github.com/yangshun"},"imageURL":"https://github.com/yangshun.png","key":"yangshun"}],"frontMatter":{"title":"Docusaurus 2019 Recap","authors":"yangshun","tags":["recap"]},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Tribute to Endi","permalink":"/blog/2020/01/07/tribute-to-endi"},"nextItem":{"title":"Happy 1st Birthday Slash!","permalink":"/blog/2018/12/14/Happy-First-Birthday-Slash"}},"content":"2019 was a great year for Docusaurus - we\'ve made tremendous progress on [Docusaurus 2](https://docusaurus.io/). Current Docusaurus 1 users who aren\'t using the translations feature can feel free to check it out and [migrate](https://docusaurus.io/docs/migration) to it! Otherwise we will work with you to make that happen in 2020 :)\\n\\n\x3c!--truncate--\x3e\\n\\n## Docusaurus 2 (D2)\\n\\nIn 2018, we proposed to rebuild [Docusaurus from the ground up](https://github.com/facebook/docusaurus/issues/789). It involved a major rearchitecture effort - we created a content-centric CSS framework from scratch, a plugins system, and moved from static HTML pages to be a single page-app with prerendered routes. It was a wild adventure and a tough feat, especially with no dedicated FTE working on the project. With the help of [@endilie](https://github.com/endiliey), our ex-intern-turned-contributor-turned-maintainer, we made really good progress on D2 and are currently on version 2.0.0-alpha.40. All features in Docusaurus 1 except for translations have been ported over.\\n\\nD2\'s killer features are **Dark Mode** and its **superb performance**. D2 has dark mode support out-of-the-box and it is near effortless to create a dark mode-friendly documentation site. Endilie put in great effort into optimizing the performance of the site and a bunch of performance optimization tricks have been done under the hood by default - optimized images, prerendering every route to static HTML and client-side routing thereafter, prefetching assets needed by future navigations whenever the user hovers over a navigation link, etc.\\n\\nLast but not least, we implemented a plugins architecture and turned the repo into a [Lerna monorepo](https://github.com/facebook/docusaurus/tree/main/packages). We believe this plugin architecture will be helpful towards building a community and also allowing users to build their own features for their unique use cases.\\n\\n## GitHub Activity\\n\\n- Stars: 10050 \u2192 14632 (+45.6% y/y)\\n- Total Contributors: 182 \u2192 303 (+66.4% y/y). Most of which are non-Facebook contributors\\n- Daily npm Downloads: 728 \u2192 2320 (+218.7% y/y). The peak was in November\\n- D1 is currently used by 3872 projects on GitHub while D2 is used by 247 projects on GitHub\\n- We now have 4 active core contributors! (+100% y/y)\\n\\n## Notable Users\\n\\nA good portion of the projects within the Open Source community use Docusaurus. This half we also onboarded more notable projects onto Docusaurus 2:\\n\\n- [Create React App](https://create-react-app.dev/)\\n- [Redux](https://redux.js.org/)\\n- [Draft.js](https://draftjs.org/)\\n- [Flux](http://facebook.github.io/flux/)\\n\\nAnd welcomed more projects to Docusaurus 1:\\n\\n- [Libra](https://developers.libra.org/)\\n- [MobX](https://mobx.js.org/)\\n- [Immer](https://immerjs.github.io/immer/)\\n- [Sorbet](https://sorbet.org/)\\n\\n## Media\\n\\nYangshun gave a classroom session during F8 about [Using Docusaurus to Create Open Source Websites](https://www.youtube.com/watch?v=QcGJsf6mgZE).\\n\\n## Community\\n\\nA few third-party hosting/development services also has first-class integration with a Docusaurus setup:\\n\\n- [Vercel deployment](https://github.com/vercel/vercel/tree/main/examples/docusaurus)\\n- [CodeSandbox](https://codesandbox.io/s/docusaurus-template-x3vg9)\\n- [Render](https://render.com/docs/deploy-docusaurus)\\n\\n## Looking Ahead\\n\\nD2 has gained some traction among the [developer community](https://docusaurus.io/showcase). In 2020, we want to achieve full feature parity with D1 by the first half and help the remaining Facebook projects on D1 move to D2. It would also be great if we could use Docusaurus for internal documentation, but that is a non-trivial undertaking. If you have a need for it or have some ideas, come speak with us!\\n\\nHuge thanks to the community for their contributions, especially the core team - [Endilie Yacop Sucipto](https://github.com/endiliey), [Alexey Pyltsyn](https://github.com/lex111), [Wei Gao](https://github.com/wgao19). Lastly, thank you [Joel Marcey](https://github.com/JoelMarcey) for starting Docusaurus and supporting the project all this time.\\n\\nCheers to a great 2020! \uD83C\uDF89"},{"id":"/2018/12/14/Happy-First-Birthday-Slash","metadata":{"permalink":"/blog/2018/12/14/Happy-First-Birthday-Slash","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2018/12-14-Happy-First-Birthday-Slash.mdx","source":"@site/blog/2018/12-14-Happy-First-Birthday-Slash.mdx","title":"Happy 1st Birthday Slash!","description":"Docusaurus makes 1 year! Happy Birthday Slash!","date":"2018-12-14T00:00:00.000Z","tags":[{"inline":false,"label":"Birth","permalink":"/blog/tags/birth"}],"readingTime":0.615,"hasTruncateMarker":true,"authors":[{"name":"Joel Marcey","title":"Co-creator of Docusaurus","url":"https://x.com/JoelMarcey","page":{"permalink":"/blog/authors/j-marcey"},"socials":{},"imageURL":"https://github.com/JoelMarcey.png","key":"JMarcey"}],"frontMatter":{"title":"Happy 1st Birthday Slash!","authors":[{"key":"JMarcey","title":"Co-creator of Docusaurus"}],"tags":["birth"]},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Docusaurus 2019 Recap","permalink":"/blog/2019/12/30/docusaurus-2019-recap"},"nextItem":{"title":"Towards Docusaurus 2","permalink":"/blog/2018/09/11/Towards-Docusaurus-2"}},"content":"\\n\\nDocusaurus [went live](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus) on December 14, 2017. At the time, we had [8 early adopters](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus#acknowledgements).\\n\\n\x3c!--truncate--\x3e\\n\\nWe now have nearly [60 known users of Docusaurus](https://v1.docusaurus.io/en/users), and probably more that we don\'t know about. We have [9K GitHub stars](https://github.com/facebook/docusaurus) and an active community, particularly [Yangshun Tay](https://x.com/yangshunz) and [Endilie Yacop Sucipto](https://x.com/endiliey), both of whom are the lead maintainers helping keep this project [moving forward](https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2).\\n\\nThank you to everyone for your support and use of this project! I am super proud of how far this project has come in just a year.\\n\\n> Special thanks to [Eric Nakagawa](https://x.com/ericnakagawa), creator of Slash, for creating this 1-year image of Slash enjoying cake. The Slash brand has been a boon for us!"},{"id":"/2018/09/11/Towards-Docusaurus-2","metadata":{"permalink":"/blog/2018/09/11/Towards-Docusaurus-2","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2018/09-11-Towards-Docusaurus-2.mdx","source":"@site/blog/2018/09-11-Towards-Docusaurus-2.mdx","title":"Towards Docusaurus 2","description":"Docusaurus was officially announced over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as React Native, Babel, Jest, Reason and Prettier.","date":"2018-09-11T00:00:00.000Z","tags":[{"inline":false,"label":"New","permalink":"/blog/tags/new"},{"inline":false,"label":"Adoption","permalink":"/blog/tags/adoption"}],"readingTime":9.25,"hasTruncateMarker":true,"authors":[{"name":"Endilie Yacop Sucipto","title":"Maintainer of Docusaurus","url":"https://github.com/endiliey","imageURL":"https://github.com/endiliey.png","key":"endiliey","page":null}],"frontMatter":{"title":"Towards Docusaurus 2","authors":"endiliey","tags":["new","adoption"]},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Happy 1st Birthday Slash!","permalink":"/blog/2018/12/14/Happy-First-Birthday-Slash"},"nextItem":{"title":"How I Converted Profilo to Docusaurus in Under 2 Hours","permalink":"/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus"}},"content":"Docusaurus was [officially announced](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/).\\n\\nThere is a saying that the very best software is constantly evolving, and the very worst is not. In case you are not aware, we have been planning and working on the next version of Docusaurus \uD83C\uDF89.\\n\\n\x3c!--truncate--\x3e\\n\\n## Introduction\\n\\nIt all started with this [RFC issue](https://github.com/facebook/docusaurus/issues/789) opened by [Yangshun](https://github.com/yangshun) towards the end of June 2018.\\n\\n<blockquote>\\n <h4>\\n <a href=\\"https://github.com/facebook/docusaurus/issues/789\\">\\n {\'[RFC] Docusaurus v2 \xb7 Issue #789 \xb7 facebook/docusaurus\'}\\n </a>\\n </h4>\\n These are some of the problems I\'m seeing in Docusaurus now and also how we can\\n address them in v2. A number of the ideas here were inspired by VuePress and other\\n static site generators. In the current static site generators ecosystem, t...\\n</blockquote>\\n\\nMost of the suggested improvements are mentioned in the issue; I will provide details on some of issues in Docusaurus 1 and how we are going to address them in Docusaurus 2.\\n\\n## Infrastructure\\n\\n### Content\\n\\nA Docusaurus 1 website is, in fact, built into a bunch of static HTML pages. Despite using React, we were not fully utilizing the features React offered, such as component state, which allows for dynamic and interactive pages. React was only used as a templating engine for static content and interactivity has to be added through script tags and `dangerouslySetInnerHTML` \uD83D\uDE31.\\n\\nIn addition, there is not an easy way to change how Docusaurus loads content. For example, adding CSS preprocessors such as Sass and Less was not supported natively and involved many user hacks of adding custom scripts.\\n\\nFor Docusaurus 2, we will be using [webpack](https://webpack.js.org/) as a module bundler and we are changing the way we serve content. Adding CSS preprocessors will be as easy as adding a webpack loader. Instead of a pure static HTML, **during build time we will create a server-rendered version of the app** and render the corresponding HTML. A Docusaurus site will be essentially an isomorphic/universal application. This approach is heavily inspired by [Gatsby](https://github.com/gatsbyjs/gatsby).\\n\\n### Versioning\\n\\nIf you have been using Docusaurus for a while, you might notice that Docusaurus creates versioned docs **if and only if** the docs content are **different**.\\n\\nFor example, if we have `docs/hello.md`:\\n\\n```text\\n---\\nid: hello\\ntitle: hello\\n---\\nHello world !\\n```\\n\\nAnd **we cut version 1.0.0,** Docusaurus will create `versioned_docs/version-1.0.0/hello.md`:\\n\\n```text\\n---\\nid: version-1.0.0-hello\\ntitle: hello\\noriginal_id: hello\\n---\\nHello world !\\n```\\n\\nHowever, if there are no changes to `hello.md` when cutting v2.0.0, Docusaurus will not create any versioned docs for that document. In other words, `versioned_docs/version-2.0.0/hello.md` will not exist.\\n\\nThis can be very confusing for users; if they want to edit the v2.0.0 docs, they have to edit `versioned_docs/version-1.0.0/hello.md` or manually add `versioned_docs/version-2.0.0/hello.md`. This could potentially lead to unwanted bugs. Here is a [real scenario in Jest](https://github.com/facebook/jest/pull/6758#issuecomment-408274413).\\n\\nIn addition, this adds complexity within the codebase as we require a mechanism for version fallbacks. And during build time, Docusaurus has to replace the linking to the correct version. This is also the cause of a bug where [renaming docs breaks links in old versions](https://github.com/facebook/docusaurus/issues/845).\\n\\nFor Docusaurus 2, **every time we cut a new version, we will instead take a snapshot of all the docs**. We will not require the content of a document to have changed. This is a space complexity trade-off for a better developer and user experience. We will use more space for better separation of concerns and guaranteed correctness.\\n\\n### Translation\\n\\nDocusaurus allows for easy translation functionality by using [Crowdin](https://crowdin.com/). Documentation files written in English are uploaded to Crowdin for translation by users within a community. We always assumed that **English** is the default language, but this might not be the case for all users. We have seen plenty of non-English open source projects using Docusaurus.\\n\\nFor Docusaurus 2, **we will not assume English is the default language**. When a user enables internationalization, they have to set a default language in `siteConfig.js`. We will then assume that all the files in `docs` are written in that language.\\n\\nIn addition, after working on the MVP of Docusaurus 2, I realized that it is possible not to use Crowdin for translations. Thus, we might need to add an additional workflow to enable that scenario. However, we will still strongly recommend people use Crowdin for easier integration.\\n\\n## Customizability\\n\\n### Layout\\n\\nThe current state of Docusaurus is that it is in charge of the entire layout and styling, unintentionally making it very hard for users to customize their site\'s appearance to their wishes.\\n\\nFor Docusaurus 2, **layout and styling should be controlled by the user**. Docusaurus will handle the content generation, routing, translation, and versioning. Inspired by [create-react-app](https://github.com/facebook/create-react-app) and [VuePress](https://vuepress.vuejs.org/), Docusaurus will still provide a default theme, which the user can eject from, for further layout and styling customization. This means that it is very possible for the user to even change the HTML meta by using [React Helmet](https://github.com/nfl/react-helmet). Community-based themes are also very possible. This approach of allowing users to be in charge of layout and styling is taken by most static site generators.\\n\\n### Markdown\\n\\nOur Markdown parsing is currently powered by [Remarkable](https://github.com/jonschlinkert/remarkable). What if the user wants to use [Markdown-it](https://github.com/Markdown-it/Markdown-it) or even [MDX](https://github.com/mdx-js/mdx)? And then there is an issue of which syntax highlighter to use, (e.g: [Prism](https://prismjs.com/) vs [Highlight.js](https://highlightjs.org/)). We should leave these choices open to the user.\\n\\nFor Docusaurus 2, **users can eject and choose their own Markdown parser**. It does not matter if they want to use another Markdown parser such as [Remark](https://github.com/remarkjs/remark), or even their own in-house Markdown parser. As a rule of thumb, the user has to provide a React component, in which we will provide a children props containing the _RAW string of Markdown_. By default, we will use Remarkable for the Markdown parser and Highlight.js for the syntax highlighting. The default parser could still change in the future as we\'re still experimenting with different Markdown parsers.\\n\\n### Search\\n\\nOur core search functionality is based on [Algolia](https://www.algolia.com/). There are requests by users to be able to use different search offerings, such as `lunrjs` for offline search.\\n\\nI personally like Algolia and we have a great experience working with them. They are very responsive; we can easily submit a pull request to Algolia since their `DocSearch` is open source. For example, I recently submitted [this PR that enables DocSearch to scrape alternate languages in sitemap](https://github.com/algolia/docsearch-scraper/pull/387).\\n\\nFor Docusaurus 2, **we will allow users to customize the search box**. Users simply need to eject from the default theme and modify the Search UI (a React component). However, we will still use Algolia in the default theme.\\n\\n## Stability\\n\\nSoftware is never going to be perfect, but we want Docusaurus to not break as we add new features. When Docusaurus was first released, it did not have any strong automated test suites. As a result, there were a lot of regressions not caught early. Although we have recently added a lot of tests, the test coverage is still relatively low.\\n\\nFor Docusaurus 2, **we are adding tests as we develop** since we are going for a fresh rewrite. Hence, I believe that it should be more stable than ever and it should be harder to break things compared to Docusaurus 1.\\n\\n## Frequently Asked Questions\\n\\n### Will there be any breaking changes?\\n\\nIf you\'ve read the post up until to this point, you should be able to notice that there will be breaking changes. While we will try to **minimize the number of breaking changes** and make it backward compatible as much as possible, we believe that some breaking changes are required. This is mostly due to Docusaurus 2 being a **major rewrite and re-architecting** of the codebase.\\n\\nThe exact list of breaking changes is not totally known yet as development is not 100% finalized. However, one thing that I will highlight is that we will deprecate a lot of options in `siteConfig.js` and we plan to keep it as lean as possible. For example, the `cleanUrl` siteConfig will be deprecated as all the URL for Docusaurus 2 sites will be without the `.html` suffix.\\n\\nOur goal is that most sites should be able to upgrade to Docusaurus 2 without a lot of pain. We will also include a migration guide when we release Docusaurus 2. When the times come, feel free to ping us on [Discord](https://discord.gg/docusaurus) or [X](https://x.com/docusaurus) for questions and help.\\n\\n### When is the release of Docusaurus 2?\\n\\nAs of now, we do not have an exact date planned for the release. I personally estimate that we might be able to release an alpha version in the next one to two months, but this is, of course, just an estimate.\\n\\nOne thing that I would like to share is that while Docusaurus is part of [Facebook Open Source](https://opensource.fb.com/) and most of the team are Facebook employees, the maintenance and development work is mostly done outside of normal working hours. I am currently a final year undergraduate student at [NTU Singapore](https://x.com/NTUsg), so I had to juggle between doing my coursework, my final year project and maintaining/developing Docusaurus. However, that does not mean that we do not want to make Docusaurus better. In fact, **we want to make it as awesome as possible**.\\n\\nFor now, the actual Docusaurus 2 work is still hosted in a private repository. In the near future, we will move them into the [public repository](https://github.com/facebook/docusaurus). When that time arrives, I encourage everyone to look into it and hopefully contribute in some way. Before then, please stay tuned \uD83D\uDE09!\\n\\n## Final Thoughts\\n\\nDocusaurus has had a large impact on the open source community as seen from the [many popular projects](https://v1.docusaurus.io/en/users) which use Docusaurus for documentation. In order to move faster in the future, we are taking the opportunity to fix some core problems with Docusaurus 1 and striving to make Docusaurus better for everyone. In fact, it is safe to say that Docusaurus 2 is not just a plan any longer; the work on it has started and, hopefully, we will be able to see it materialize in the near future.\\n\\nDocusaurus\' mission has always been to make it really easy for you to get a website with documentation up and running out of the box. That mission does not change with Docusaurus 2.\\n\\nWe also want to let people know that **due to work on Docusaurus 2, we will be less likely to accept new features/major changes on Docusaurus 1.**\\n\\nIf you are using Docusaurus, you are part of our community; keep letting us know how we can make Docusaurus better for you. If you appreciate the work we\'re doing, you can support [Docusaurus on Open Collective](https://opencollective.com/Docusaurus).\\n\\n> If you are sponsoring our work on [Open Collective](https://opencollective.com/Docusaurus), we\'ll personally offer you a helping hand for maintenance and upgrading of Docusaurus website.\\n\\nLastly, if you haven\'t done so already, click the **star** and **watch** button on [GitHub](https://github.com/facebook/docusaurus), and follow us on [X](https://x.com/docusaurus)."},{"id":"/2018/04/30/How-I-Converted-Profilo-To-Docusaurus","metadata":{"permalink":"/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2018/04-30-How-I-Converted-Profilo-To-Docusaurus.mdx","source":"@site/blog/2018/04-30-How-I-Converted-Profilo-To-Docusaurus.mdx","title":"How I Converted Profilo to Docusaurus in Under 2 Hours","description":"\u201CJoel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I\'m going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn\'t be much different from editing those Markdown files.\u201D","date":"2018-04-30T00:00:00.000Z","tags":[{"inline":false,"label":"Profilo","permalink":"/blog/tags/profilo"},{"inline":false,"label":"Adoption","permalink":"/blog/tags/adoption"}],"readingTime":5.95,"hasTruncateMarker":true,"authors":[{"name":"Christine Abernathy","url":"http://x.com/abernathyca","socials":{"x":"https://x.com/abernathyca"},"imageURL":"https://github.com/caabernathy.png","key":"abernathyca","page":null}],"frontMatter":{"title":"How I Converted Profilo to Docusaurus in Under 2 Hours","authors":["abernathyca"],"tags":["profilo","adoption"]},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"Towards Docusaurus 2","permalink":"/blog/2018/09/11/Towards-Docusaurus-2"},"nextItem":{"title":"Introducing Docusaurus","permalink":"/blog/2017/12/14/introducing-docusaurus"}},"content":"> _\u201CJoel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I\'m going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn\'t be much different from editing those Markdown files.\u201D_\\n>\\n> _\u2014 Note sent to the Profilo team_\\n\\nThis is the story of the rather short journey it took to create the [Profilo](https://facebookincubator.github.io/profilo/) website using Docusaurus.\\n\\nProfilo, an Android library for collecting performance traces from production, [was announced](https://code.fb.com/android/profilo-understanding-app-performance-in-the-wild/) earlier this year. The project was [published on GitHub](https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8) with a less than [a handful or Markdown files](https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8/docs) to describe its functionality and no website to showcase any branding and highlight the logo. The task at hand was to turn these existing docs and logo into a website.\\n\\n\x3c!--truncate--\x3e\\n\\nIn general, when creating a website with Docusaurus you do the following:\\n\\n1. Generate a template website using Docusaurus scripts.\\n1. Customize the generated template files for your desired site colors and your project configuration (ex: website and GitHub links).\\n1. Create the website content:\\n 1. Add your docs and any supporting assets.\\n 1. Customize the default landing page provided by Docusaurus to suit your needs.\\n 1. Configure the default site navigation file.\\n1. Publish the website and set up how it will be published for future changes.\\n\\nGiven I had pre-existing Markdown files, I didn\'t have to generate the core content but simply make sure that Docusaurus could process the files by adding the expected metadata to them. Most of the work would therefore consist of customizing the defaults provided by Docusaurus.\\n\\n## Overview of Steps Taken\\n\\nHere\'s an overview of the steps taken to convert to a website. I\'ll discuss some of the design aspects in a later section.\\n\\n**Design and colors:**\\n\\n1. Got all the desired logo formats from designer. I had to create the _.favicon_ one.\\n1. Worked out some passable primary and secondary website colors using the http://paletton.com/ tools - very handy!\\n\\n**Initial website setup:**\\n\\n1. Forked the [Profilo project](https://github.com/facebookincubator/profilo/) on GitHub and created a local clone of the fork to set up the website.\\n1. Created the initial Docusaurus website using the [installation instructions](https://v1.docusaurus.io/docs/en/installation.html).\\n1. Deleted the `docs-examples-from-docusaurus` and `website/blog-examples-from-docusaurus` folders as these would not be needed. Profilo had existing docs we could use and there was no need for blogs at this time.\\n\\n**Content creation:**\\n\\n1. Added metadata to the existing Markdown files found in the `docs` folder, for example:\\n\\n ```md\\n ---\\n id: architecture\\n title: Architecture\\n sidebar_label: Architecture\\n ---\\n ```\\n\\n2. Added the logo assets to the `website/static/img` folder.\\n3. Modified `website/pages/en/index.js`, the landing page, to highlight Profilo features.\\n4. Modified `website/core/Footer.js`, the footer, to simplify it for Profilo.\\n5. Edited `website/siteConfig.js` (website configuration file) to specify the previously chosen primary and secondary colors.\\n6. Modified `website/sidebars.json` that specifies the sidebar navigation. Listed all the docs and customized it based on the metadata added to the Markdown files.\\n7. Edited the website configuration file to specify the GitHub properties, logo images, header links, and the website link.\\n8. Tested the website locally throughout this phase. (I ran `yarn start` from the `website` folder to start the server.)\\n\\n**Feedback and review changes:**\\n\\n1. Sent a [pull request](https://github.com/facebookincubator/profilo/pull/6) to the project.\\n2. Updated the colors after the designer rightly gasped at the ones I had chosen (IANAD).\\n3. Updated the colors and updated the PR.\\n4. The PR was then accepted and [merged](https://github.com/facebookincubator/profilo/commit/6ad033aaf5a7d54e6d842f45a5bccd051a8e45ad). Yay!\\n\\n**Website publishing:**\\n\\n1. Pushed the first website version by running the Docusaurus publish script from the command line:\\n\\n ```bash\\n USE_SSH=true \\\\\\n GIT_USER=caabernathy \\\\\\n CURRENT_BRANCH=master \\\\\\n yarn run publish-gh-pages\\n ```\\n\\n2. Configured CircleCI using the [provided Docusaurus instructions](https://v1.docusaurus.io/docs/en/publishing.html#automating-deployments-using-continuous-integration). There were 2 PRs for this, [the first](https://github.com/facebookincubator/profilo/pull/8)for the initial config and [the second](https://github.com/facebookincubator/profilo/pull/12) to make sure CircleCI only triggered for changes in the master branch (thanks Joel Marcey!).\\n\\nThe final website was published on https://facebookincubator.github.io/profilo/. It had taken 1.5 hours to get to the initial PR stage and another half an hour or so to respond to review feedback and publish the website.\\n\\n## Design\\n\\nHere\'s what the initial website looked like when the first pull request was sent out:\\n\\n\\n\\nMost of the time in the content creation was spent picking colors that worked reasonably well with the given logo. These colors were a good jumping off point for designer feedback. I used Photoshop to sample various portions of the logo.\\n\\n\\n\\nI then took the RGB representation of the color and set it as the baseline color on [Paletton](http://paletton.com/). The website then gave me various color options to try on the website by editing the Docusaurus website configuration file.\\n\\n\\n\\nThe selected primary and secondary colors were a good jumping off point for designer feedback.\\n\\nThere were also modifications made to the default website generated by Docusaurus. These changes were mainly around simplifying the footer and creating a customized landing page for Profilo that listed the project\'s features.\\n\\nHere\'s what the final website looked like:\\n\\n\\n\\nThis is an example page showing the core content, in this case the Getting Started page:\\n\\n\\n\\nThis also shows the sidebar structure that was set up through editing `website/sidebars.json`.\\n\\nLastly, I didn\'t have to worry about handling responsive design. You get this out of the box with Docusaurus!\\n\\n\\n\\n## Final Thoughts\\n\\nThe Profilo engineers were happy to see that they didn\'t have to change their workflow to update existing content. They were able to continue working with Markdown files. This will still be true in the future if new docs are added, although there may be some config changes needed if the sidebar navigation needs to be updated.\\n\\nThe infrastructure provided by Docusaurus made it easy to convert Markdown files into a working website. Even though the project had only three docs, this gave Profilo a more professional look. So, it was well worth the short time investment to get it done."},{"id":"/2017/12/14/introducing-docusaurus","metadata":{"permalink":"/blog/2017/12/14/introducing-docusaurus","editUrl":"https://github.com/facebook/docusaurus/edit/main/website/blog/2017/12-14-introducing-docusaurus.mdx","source":"@site/blog/2017/12-14-introducing-docusaurus.mdx","title":"Introducing Docusaurus","description":"We are very happy to introduce Docusaurus to help you manage one or many open source websites.","date":"2017-12-14T00:00:00.000Z","tags":[{"inline":false,"label":"Documentation","permalink":"/blog/tags/documentation"},{"inline":false,"label":"Blog","permalink":"/blog/tags/blog"},{"inline":false,"label":"Docusaurus","permalink":"/blog/tags/docusaurus"}],"readingTime":8.215,"hasTruncateMarker":true,"authors":[{"name":"Joel Marcey","title":"Developer Advocate at Meta","url":"https://x.com/JoelMarcey","page":{"permalink":"/blog/authors/j-marcey"},"socials":{"x":"https://x.com/joelmarcey","github":"https://github.com/JoelMarcey"},"imageURL":"https://github.com/JoelMarcey.png","key":"JMarcey"}],"frontMatter":{"title":"Introducing Docusaurus","authors":"JMarcey","tags":["documentation","blog","docusaurus"]},"unlisted":false,"lastUpdatedAt":1738843713000,"lastUpdatedBy":"S\xe9bastien Lorber","prevItem":{"title":"How I Converted Profilo to Docusaurus in Under 2 Hours","permalink":"/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus"}},"content":"\\n\\nWe are very happy to introduce [Docusaurus](https://github.com/facebook/docusaurus) to help you manage one or many open source websites.\\n\\nWe created [Docusaurus](https://docusaurus.io) for the following reasons:\\n\\n1. To put the focus on writing good documentation instead of worrying about the infrastructure of a website.\\n1. To provide features that many of our open source websites need like blog support, search and versioning.\\n1. To make it easy to push updates, new features, and bug fixes to everyone all at once.\\n1. And, finally, to provide a consistent look and feel across all of our open source projects.\\n\\n\x3c!--truncate--\x3e\\n\\nDocusaurus is a tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details. At its core, all a user has to provide are documentation files written in Markdown, customization of a provided home page written in React, and a few configuration modifications. Docusaurus handles the rest by providing default styles, site formatting, and simple document navigation. Getting started is easy, as users can [install](https://v1.docusaurus.io/docs/en/installation.html) it using `npm` or `yarn` via a simple initialization script that [creates a working example website out of the box](https://v1.docusaurus.io/docs/en/site-preparation.html).\\n\\nDocusaurus also provides core website and documentation features out-of-the-box including [blog support](https://v1.docusaurus.io/docs/en/blog.html), [internationalization](https://v1.docusaurus.io/docs/en/translation.html), [search](https://v1.docusaurus.io/docs/en/search.html), and [versioning](https://v1.docusaurus.io/docs/en/versioning.html). While some projects may not require any of these features, enabling them is generally a matter of updating configuration options instead of having to add the infrastructure from the ground up. As more features get added to Docusaurus, users just can easily update to the latest version. This can be done by simply running npm or yarn update and updating configuration options. Users or teams will no longer need to manually rework their entire website infrastructure each time a new feature gets added.\\n\\n## The Birth of docusaurus\\n\\n\\n\\nWhen Facebook first started their open source program, many teams implemented a custom website for each of their open source projects. This approach presented challenges when the open source program team was asked to help the project teams improve their documentation. Since each site was unique, adding basic infrastructure such as a blog, consistent navigation, search, etc. became challenging undertakings.\\n\\nThe open source team tried to help mitigate this problem by coming up with a standard template, based on Jekyll, that could be used as a starting point for a project website. We asked our new projects to manually copy our template source to their repo, write their docs, and publish. This template approach was adopted by most of open source projects launched; some existing projects even converted their custom website implementations to the new template as well.\\n\\nThe problem with the \\"copy the template to your repo\\" approach is that, even though the platform is consistent, pushing updates becomes unmaintainable across an entire suite of projects already using the template. This is because we lost control of the template after a project copied it to their repo. Projects were free to modify the template as desired and apply their own project-specific features to it. So while projects share the same site generation platform, they have now diverted enough where they cannot take advantage of the new features we have added to the template over time. There was no easy way we could ask all current projects to \\"copy\\" a new version of the template since it might break their existing site or remove features that they have added on their own. Instead, we would have to apply the updates manually to each project one-by-one. This became very problematic when projects started asking for our team for internationalization support within the template, requiring low-level changes to how the template was structured and generated.\\n\\nSo we started thinking about what we could do to help mitigate the challenge of keeping sites updated and consistent across our entire portfolio. We also wanted multiple projects to share the same site generation software. We wanted them to start out with the same template, and yet have the flexibility to customize and adapt their site theme to suit their needs. They should be able to extend and customize their site, but when we update the underlying infrastructure with fixes and features, the project should be able update simply and without any breaking changes.\\n\\nDocusaurus was born!\\n\\nAt Facebook, Docusaurus allows us to quickly get different projects up and running with documentation websites, especially for teams who don\'t have much experience with web development or primarily want a basic site to showcase their project. Docusaurus already supports sites needing more advanced features like internationalization for Jest and versioning for React Native. As different projects request new features for their sites, they are added to Docusaurus and simultaneously provided to all projects! All together, this ends up greatly reducing the work needed to maintain different sites for different projects. Our teams are able to focus on keeping their projects healthier by spending more time adding features, fixing bugs, and writing documentation.\\n\\n## Getting Up and Running\\n\\n\\n\\nAt its core, we wanted sites running Docusaurus to be simple to use. With one [installation](https://v1.docusaurus.io/docs/en/installation.html) command and some simple [configuration](https://v1.docusaurus.io/docs/en/site-preparation.html), you can actually have a default running website.\\n\\nWhen you run `docusaurus-init`, you will see a structure similar to:\\n\\n```bash\\nroot-of-repo\\n\u251C\u2500\u2500 docs-examples-from-docusaurus\\n\u2502 \u251C\u2500\u2500 doc1.md\\n\u2502 \u251C\u2500\u2500 doc2.md\\n\u2502 \u251C\u2500\u2500 doc3.md\\n\u2502 \u251C\u2500\u2500 example-doc4.md\\n\u2502 \u2514\u2500\u2500 example-doc5.md\\n\u251C\u2500\u2500 website\\n\u2502 \u251C\u2500\u2500 blog-examples-from-docusaurus\\n\u2502 \u2502 \u251C\u2500\u2500 2016-03-11-blog-post.md\\n\u2502 \u2502 \u2514\u2500\u2500 2017-04-10-blog-post-two.md\\n\u2502 \u251C\u2500\u2500 core\\n\u2502 \u2502 \u2514\u2500\u2500 Footer.js\\n\u2502 \u251C\u2500\u2500 node_modules\\n\u2502 \u251C\u2500\u2500 package.json\\n\u2502 \u251C\u2500\u2500 pages\\n\u2502 \u251C\u2500\u2500 sidebars.json\\n\u2502 \u251C\u2500\u2500 siteConfig.js\\n\u2502 \u2514\u2500\u2500 static\\n```\\n\\nWith the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your Markdown that represents your documentation; the blog folder is where you add your Markdown for your [blog posts](https://v1.docusaurus.io/docs/en/blog.html); `siteConfig.js` is where you make most of the [customizations](https://v1.docusaurus.io/docs/en/site-config.html) for your site; `sidebars.json` is where you maintain the layout and content of the [sidebar](https://v1.docusaurus.io/docs/en/navigation.html) for your documentation; the `pages` folder is where you add [custom](https://v1.docusaurus.io/docs/en/custom-pages.html) pages for your site; the `static` folder is where all of your static assets go (e.g., CSS stylesheets and images); and the `core` folder is where you can customize core components of the site, in this case the footer.\\n\\n## How does Docusaurus work?\\n\\nDocusaurus is written primarily in JavaScript and [React](https://facebook.github.io/react), replacing Jekyll which we used in the old template. We use [Remarkable](https://github.com/jonschlinkert/remarkable) for our Markdown rendering and [highlight.js](https://highlightjs.org/) for our code block syntax highlighting. The core of Docusaurus\' functionality is in the [lib directory](https://github.com/facebookexperimental/Docusaurus/tree/master/lib) of the [Docusaurus repo](https://github.com/facebook/docusaurus/). The general structure looks like:\\n\\n```bash\\nroot-of-Docusaurus\\n\u251C\u2500\u2500 lib\\n\u2502 \u251C\u2500\u2500 core\\n\u2502 \u251C\u2500\u2500 server\\n\u2502 \u2502 \u251C\u2500\u2500 generate.js\\n\u2502 \u2502 \u251C\u2500\u2500 server.js\\n\u2502 \u2502 \u2514\u2500\u2500 ...and more files\\n\u2502 \u251C\u2500\u2500 static\\n\u2502 \u251C\u2500\u2500 build-files.js\\n\u2502 \u251C\u2500\u2500 copy-examples.js\\n\u2502 \u251C\u2500\u2500 generate-feed.js\\n\u2502 \u251C\u2500\u2500 publish-gh-pages.js\\n\u2502 \u251C\u2500\u2500 rename-version.js\\n\u2502 \u251C\u2500\u2500 start-server.js\\n\u2502 \u251C\u2500\u2500 versions.js\\n\u2502 \u2514\u2500\u2500 write-translations.js\\n```\\n\\nThe key files here are build-files.js and start-server.js. There are many similarities between these two files: `build-files.js` is used to build the physical artifacts for serving by an external web server. `start-server.js` is used to run the Docusaurus server and locally test your site. Both go through the following general process to take all of the Markdown and configuration to create a runnable website:\\n\\n1. Process your website settings in `siteConfig.js`\\n1. Read the document metadata that exists in all the Markdown files in your docs directory.\\n1. Create a table of contents for your documents based upon the IDs extracted from the metadata.\\n1. Convert the Markdown to HTML, including doing link replacement.\\n1. These files will go in a build/docs directory of the compiled site, and any translated versions will go into a language specific folder within the build/docs folder.\\n1. Repeat 1-3 for blog posts.\\n1. The blog file will go in a build/blog directory of the compiled site.\\n1. Read the main.css file and concatenate any user-defined css into master css file that will be in the build/css directory of the compiled site.\\n1. Copy images into an build/img directory of the compiled site.\\n1. Take any custom pages that were added to the pages folder of the site and compile/copy those into the root build directory of the compiled site. Any translated versions will go into a language specific folder within build.\\n1. Create CNAME and sitemap.xml files and add those to build.\\n\\nNote that this process does not take into full account how translations or versioning works. The underlying details of those features will be saved for future blog posts.\\n\\nThe final structure of your compiled site will look similar to:\\n\\n```bash\\nbuild\\n\u251C\u2500\u2500 website\\n\u2502 \u251C\u2500\u2500 CNAME\\n\u2502 \u251C\u2500\u2500 blog\\n\u2502 \u251C\u2500\u2500 css\\n\u2502 \u251C\u2500\u2500 docs\\n\u2502 \u251C\u2500\u2500 en\\n\u2502 \u251C\u2500\u2500 help.html # custom page\\n\u2502 \u251C\u2500\u2500 img\\n\u2502 \u251C\u2500\u2500 index.html # landing page\\n\u2502 \u251C\u2500\u2500 sitemap.xml\\n\u2502 \u2514\u2500\u2500 users.html # custom page\\n```\\n\\n## Community\\n\\n\\n\\nWe welcome your [contributions](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md) to Docusaurus, whether you want to use it for your own site, you want to [contribute](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md) to the Docusaurus core or just have questions. Follow us on [GitHub](https://github.com/facebook/docusaurus) and [X)](https://x.com/docusaurus).\\n\\n## Acknowledgements\\n\\nDocusaurus wouldn\'t exist without the work of the rest of the core Docusaurus team: [Eric Nakagawa](http://x.com/ericnakagawa), [Hector Ramos](https://x.com/hectorramos), [Eric Vicenti](https://x.com/EricVicenti) and [Frank Li](https://github.com/deltice) \u2014 a former intern at Facebook who implemented the core technology and features.\\n\\nSpecial thanks also goes out to our earliest [adopters](https://v1.docusaurus.io/en/users.html) of Docusaurus:\\n\\n- [BuckleScript](https://bucklescript.github.io/)\\n- [FastText](https://fasttext.cc)\\n- [Jest](https://jestjs.io)\\n- [Make It Open](http://makeitopen.com)\\n- [Prettier](https://prettier.io/)\\n- [Reason-react](https://reasonml.github.io/reason-react/)\\n- [React Native](https://facebook.github.io/react-native/)\\n- [Relay](https://facebook.github.io/relay/)\\n\\nWithout their dedication to creating or migrating their websites over to the platform, we would have not have been in the position where we are today.\\n\\n## Resources\\n\\n- [Read our documentation](https://v1.docusaurus.io)\\n- [Follow our X feed](https://x.com/docusaurus)\\n- [Follow us on GitHub](https://github.com/facebook/docusaurus)\\n- [About Slash, the Docusaurus mascot](https://v1.docusaurus.io/about-slash.html)"}]}}')}}]);
|