![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-73a479db9ad439c10153f05dc03fdc91.png\")
We are happy to announce Docusaurus 3.7.
\nDocusaurus is now compatible with React 19.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n
In #10763, we added support for React 19, and the Docusaurus website is running on React 19 already.
\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.
\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{
\"name\": \"my-docusaurus-site\",
\"dependencies\": {
- \"react\": \"^18.0.0\",
- \"react-dom\": \"^18.0.0\"
+ \"react\": \"^19.0.0\",
+ \"react-dom\": \"^19.0.0\"
}
}
There's no urge to upgrade your site immediately.
React 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.
However, upgrading to React 19 prepares your site for Docusaurus v4, that will drop support for React 18.
Here are good reasons to upgrade your site before Docusaurus v4:
Along the way, we fixed all the remaining hydration errors reported by React 19, some of them produced by our aggressive HTML minifier settings.
\nDocusaurus has built-in support for SVGR, allowing you to seamlessly import and use SVG files as React components:
\nimport DocusaurusSvg from './docusaurus.svg';
<DocusaurusSvg />;
This built-in support has been the source of various bug reports due to the inability to customize the SVGR Options, in particular the SVG Optimizer options.
\nIn #10677, we extracted a new @docusaurus/plugin-svgr that you can now configure according to your needs. It is included by default in our classic preset:
export default {
presets: [
[
'classic',
{
svgr: {
svgrConfig: {
// Your SVGR options ...
svgoConfig: {
// Your SVGO options ...
// Use \"svgoConfig: undefined\" to use a svgo.config.js file
},
},
},
},
],
],
};
Other notable changes include:
\nfrontMatter.sidebar_label@docusaurus/remark-plugin-npm2yarn now supports Bun conversions.algoliasearch v5.Check the 3.7.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/3.7", "title": "Docusaurus 3.7", "summary": "We are happy to announce Docusaurus 3.7.", "date_modified": "2025-01-03T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/3.6", "content_html": "We are happy to announce Docusaurus 3.6.
\nDocusaurus is now ⚡️⚡️⚡️ much faster to build your site.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-5214adcb56c496fa6afc571fb4d378f6.png\")
This release has been mostly focused on build performance through the Docusaurus Faster project.
\nThe Docusaurus Faster project's goal is to reduce the build times and memory consumption.
\nWe have worked on multiple optimizations and modernized our infrastructure to use faster Rust-based tools, notably:
\nAdopting a new infrastructure can have various impacts. It's impossible to list them all exhaustively, so let's focus on the major ones.
\nTo help you adopt it easily, we have been fairly conservative in terms of expected static site output and browser support.
\nBenchmarks on community site show that you can expect your production site to build ⚡️2 to 4 times faster! 🔥:
\nRspack doesn't support persistent caching yet, 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.
You should also notice an improvement in memory consumption:
\nprocess.exit(0) that can hide memory leaks in your own code and third-party pluginsThis new infrastructure is a breaking change, but it is opt-in and does not require a new major version of Docusaurus.
\nBefore using Docusaurus Faster, add this new package:
\nnpm install @docusaurus/faster
yarn add @docusaurus/faster
pnpm add @docusaurus/faster
bun add @docusaurus/faster
To help you adopt it incrementally under Docusaurus v3, we're introducing a set of feature flags that you can activate progressively.
\nWe recommend turning them on all at once with this simple boolean shortcut:
\nconst config = {
future: {
experimental_faster: true,
},
};
In case one of the flags does not work for your site, it's possible to turn feature flags on independently:
\nconst config = {
future: {
experimental_faster: {
swcJsLoader: true,
swcJsMinimizer: true,
swcHtmlMinimizer: true,
lightningCssMinimizer: true,
rspackBundler: true,
mdxCrossCompilerCache: true,
},
},
};
swcJsLoader: Use SWC to transpile JS (instead of Babel)swcJsMinimizer: Use SWC to minify JS (instead of Terser)swcHtmlMinimizer : Use SWC to minify HTML and inlined JS/CSS (instead of html-minifier-terser)lightningCssMinimizer: Use Lightning CSS to minify CSS (instead of cssnano and clean-css)rspackBundler: Use Rspack to bundle your app (instead of webpack)mdxCrossCompilerCache: Compile MDX files once for both browser/Node.js environments instead of twiceDon't be afraid to turn this feature on. What's experimental is the config options.
The new infrastructure is robust and well-tested by our CI pipeline. The Docusaurus site already uses it in production, and we plan to use it on other Meta docs sites as well.
The new infrastructure uses Rspack. By chance, Rspack is almost 100% compatible with webpack, and Rspack shouldn't break our plugin ecosystem.
\nMost Docusaurus plugins should work out of the box with Rspack, even those implementing configureWebpack.
However, 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:
-import webpack from 'webpack';
export default function (context, options) {
return {
name: 'custom-docusaurus-plugin',
- configureWebpack(config, isServer) {
+ configureWebpack(config, isServer, {currentBundler}) {
return {
plugins: [
- new webpack.DefinePlugin({}),
+ new currentBundler.instance.DefinePlugin({}),
]
};
},
};
}
Check the dedicated issue for guidelines and support.
It's only the beginning: we will continue working on the Docusaurus Faster project and already have a few more performance improvements planned.
\nDepending on your feedback, we plan to make this new infrastructure the default in an upcoming major version of Docusaurus.
\n🙏 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 that supported us along the way, handled our feedback very quickly and implemented all the missing features we needed to make it happen. 👏
\nIn #10588, we created a Docusaurus plugin for Rsdoctor. 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![\"Loader](\"https://coinsgpt.github.io/assets/images/rsdoctor-36963a4eaca95f83538208463e62eae2.jpg\")
To use it, install the new @docusaurus/plugin-rsdoctor package, and then use the plugin in your config:
export default {
plugins: [
[
'rsdoctor',
{
/* options */
},
],
],
};
Turn it on conditionally, based on an environment variable:
export default {
plugins: [
process.env.RSDOCTOR === 'true' && [
'rsdoctor',
{
/* options */
},
],
],
};
# Build without Rsdoctor
npm run build
# Build with Rsdoctor
RSDOCTOR=true npm run build
In #10510, we relaxed our Mermaid diagrams 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.
\nThis unlocks new types of diagrams, such as Architecture Diagrams:
\n\nOther notable changes include:
\nfrontMatter.title_meta to override frontMatter.title for SEO reason.docusaurus build and docusaurus deploy now support multiple --locale CLI args.docusaurus-remark-plugin-npm2yarn upgrades to npm-to-yarn v3 and can convert npx commands.3.5.2-canary-<number> instead of 0.0.0-canary-<number> to respect plugins peerDependency constraints.@docusaurus/tsconfig upgrades to target: 'es2022'.babel.config.js from Docusaurus init templates to discourage customizing Babel.Check the 3.6.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/3.6", "title": "Docusaurus 3.6", "summary": "We are happy to announce Docusaurus 3.6.", "date_modified": "2024-11-04T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/3.5", "content_html": "We are happy to announce Docusaurus 3.5.
\nThis release contains many new exciting blog features.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-7b2ed059f27fc8b64f3f20025ebb382f.png\")
In #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.
slorber:
name: Sébastien Lorber
# other author properties...
socials:
x: sebastienlorber
linkedin: sebastienlorber
github: slorber
newsletter: https://thisweekinreact.com
![\"Author](\"https://coinsgpt.github.io/assets/images/author-socials-93483e664b2d095b137cf10c4769c100.png\")
Icons 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.
In #10216, we added the possibility for global blog authors (declared in authors.yml) to have their own dedicated page listing all the blog posts they contributed to.
This 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:
slorber:
name: Sébastien Lorber
# the description will be displayed on the author's page
description: 'A freelance React and React-Native developer...'
page: true # Turns the feature on
This creates a dedicated author page at /blog/authors/slorber.
![\"Author](\"https://coinsgpt.github.io/assets/images/author-page-4a9753641b116ddfeecc46ed1dcee907.png\")
An authors index page is also created, listing all the blog authors.
\n![\"Author](\"https://coinsgpt.github.io/assets/images/author-index-4abd3b8b777b2c1b3958768559896262.png\")
Check the blog authors pages guide for details.
\nIn #9252, we added support for styling your blog feeds 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.
const blogOptions = {
feedOptions: {
xslt: {
rss: 'custom-rss.xsl',
atom: 'custom-atom.xsl',
},
},
};
Writing your own XSLT can be complex, but you can also use xslt: true to turn on the built-in style:
const blogOptions = {
feedOptions: {
xslt: true,
},
};
![\"Screenshot](\"https://coinsgpt.github.io/assets/images/blog-feed-xslt-22194c2a971aba7f3bbf6115d3aa1d49.png\")
In #10252, we added support for grouping blog posts by years in the blog sidebar.
\n![\"Screenshot](\"https://coinsgpt.github.io/assets/images/blog-sidebar-years-1d0be02836d9a3307386c365b9969a37.png\")
This feature is now turned on by default, but can be disabled with themeConfig.blog.sidebar.groupByYear: false.
We added new blog options to enforce recommended practices for your blog posts:
\nonInlineAuthorsWe believe large multi-blogs are easier to manage by using 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.
In #10224, we added the onInlineAuthors option. Use onInlineAuthors: 'throw' to forbid inline authors, and enforce a consistent usage of global authors.
onUntruncatedBlogPostsWe believe blog posts are better using truncation markers (<!-- truncate --> 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.
In #10375, we added the onUntruncatedBlogPosts option. Use onUntruncatedBlogPosts: 'throw' to enforce a consistent usage of truncation markers.
Other notable changes include:
\n# title are automatically wrapped in <header> for consistency with front matter title: Title.null.recmaPlugins option to modify the MDX Estree AST._category_.json accepts a new description property that gets displayed on generated index pages.docusaurus --version now actually returns the Docusaurus version.mdx-code-block now supports indentation.<TabItem lazy> support the for className prop.@docusaurus/theme-common/internal APIs have been moved to @docusaurus/plugin-content-blog/client.@docusaurus/theme-common/internal APIs have been moved to @docusaurus/plugin-content-docs/client.Check the 3.5.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/3.5", "title": "Docusaurus 3.5", "summary": "We are happy to announce Docusaurus 3.5.", "date_modified": "2024-08-09T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/3.4", "content_html": "We are happy to announce Docusaurus 3.4.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-66116702bb73f0bf68a095ddaecc0fe4.png\")
The 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.
With #10137, you can now declare a list of pre-defined tags in a tags.yml file:
tag1:
label: 'Tag 1'
description: 'Tag 1 description'
permalink: /tag-1-permalink
tag2:
label: 'Tag 2'
description: 'Tag 2 description'
permalink: /tag-2-permalink
These predefined tags can be used in the front matter of your blog or docs files:
\n---
tags: [tag1, tag2]
---
# Title
Content
Use the new onInlineTags: 'throw' plugin option to enforce the usage of predefined tags and prevent contributors from creating new unwanted tags.
With 9859, we added a new experimental hash router config option, useful for offline browsing by opening your site locally through the file:// protocol.
export default {
future: {
experimental_router: 'hash',
},
};
This mode is not recommended for sites deployed through a web server.
When 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.
![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/hash-96c9ef1044dc1febfe3eefdc9350e2a0.png\")
Try browsing our own Docusaurus site built with the hash router:
\nThis feature is experimental. If you try it out, please let us know how it works for you here.
Docusaurus uses the browser localStorage API to persist UI state.
But sometimes the storage space is \"shared\" between multiple sites using the same domain, leading to storage key conflicts. This generally happens in two cases
\nhttp://localhost:3000 siteshttps://example.com/site1/ and https://example.com/site2/For this reason, we introduced a new experimental siteStorage configuration option:
export default {
future: {
experimental_storage: {
type: 'localStorage',
namespace: true,
},
},
};
When 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.
This feature is experimental. If you try it out, please let us know how it works for you here.
Other notable changes include:
\n/search page now respects the contextualSearch: false settingCheck the 3.4.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/3.4", "title": "Docusaurus 3.4", "summary": "We are happy to announce Docusaurus 3.4.", "date_modified": "2024-05-31T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/3.3", "content_html": "We are happy to announce Docusaurus 3.3.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-105335e6b4ebb3f62aa9b04e33a76dea.png\")
The React core team recently released the first React 19 beta. They also published an upgrade guide and a React v18.3 release with new warnings to help us identify issues before upgrading to React 19.
\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.
It 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\nWarning: 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
In #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 if you see them, to us but also to other Docusaurus third-party plugin authors.
\ncreateSitemapItemsIn #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.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
sitemap: {
createSitemapItems: async ({
defaultCreateSitemapItems,
...params
}) => {
const items = await defaultCreateSitemapItems(params);
return items.filter((item) => !item.url.includes('/tags/'));
},
},
},
],
],
};
The Docusaurus pages plugin has historically been lagging behind the docs and blog plugins in terms of available feature.
\nIn #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.
\nexport default {
presets: [
[
'@docusaurus/preset-classic',
{
pages: {
editUrl:
'https://github.com/facebook/docusaurus/tree/main/website/src/pages',
editLocalizedFiles: true,
showLastUpdateAuthor: true,
showLastUpdateTime: true,
},
},
],
],
};
These 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.
Other notable changes include:
\nsiteConfig.markdown.anchors.maintainCasedocusaurus deploy --target-dir optionroute.props<Admonition> component can render properly without heading/icon<Tabs> props can now override defaultsdocusaurus serve works better with a /baseUrl/ pathname prefixpt-BRCheck the 3.3.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/3.3", "title": "Docusaurus 3.3", "summary": "We are happy to announce Docusaurus 3.3.", "date_modified": "2024-05-03T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/3.2", "content_html": "We are happy to announce Docusaurus 3.2.
\nThe upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-8ca15c1adaeb77ca302178575136a0b6.png\")
We worked hard to reduce the time it takes to build a Docusaurus site in production mode.
\nBetween v3.1.0 and v3.2.0, several changes have been made, leading to significantly faster production builds for many sites.
\nLet's take an example. Our benchmark on the React Native website upgrading to v3.2 reports the following results:
\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.
\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 for upcoming improvements.
\nA cold build is when the Docusaurus caches are empty, generally after running docusaurus clear.
An 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. To enable incremental builds on your CI server, you can persist the node_modules/.cache folder across builds.
We also worked on improving the performance of the dev server, so that you can get a faster feedback when editing Markdown/MDX files.
\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 🔥.
\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.
\nWith #9684, Docusaurus is now able to render headings coming from an imported partial into the table-of-contents.
\nDocusaurus and MDX allows you to import one Markdown file into another. 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.
# My Doc
## Doc heading
Content is imported from another MDX file:
import ImportedDoc from './\\_importedDoc.mdx';
<ImportedDoc />
## Partial heading
Some paragraph
Previously, the heading Partial heading did not appear in the table-of-contents, but now it will!
We improved the blog plugin with several new options to make it even more powerful and flexible:
\nprocessBlogPosts option allow you to filter/transform/sort blog posts.pageBasePath option allows you to customize the blog pagination URL segment (/blog/page/2)With #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.
We also made it possible to opt-out of emitting <priority> and <frequency> tags, which are generally ignored by crawlers (notably Google).
We recommend using the following sitemap plugin config, that will become the default in Docusaurus V4:
\n{
lastmod: 'date',
priority: null,
changefreq: null,
}
docusaurus swizzle and create-docusaurus CLIs now ask users if they prefer to use TypeScriptallContentLoaded plugin lifecycle (experimental)Check the 3.2.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/3.2", "title": "Docusaurus 3.2", "summary": "We are happy to announce Docusaurus 3.2.", "date_modified": "2024-03-29T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/3.1", "content_html": "We are happy to announce Docusaurus 3.1.
\nThe upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-e1b6e0c51be29d4ab2d4c966d220410c.png\")
In #9528, we improved the built-in broken links checker to also detect broken anchors.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/broken-anchor-4191e5dd94aef9e8c5e3524880670f0f.jpg\")
The new onBrokenAnchors option has value warn by default, for retro-compatibility reasons.
We recommend to turn it to throw and fail your CI builds instead of deploying broken anchors to productions.
For users and plugin authors implementing custom <Heading> and <Link> components, we provide a new useBrokenLinks React hook API.
Most Docusaurus users don't need to care about it, built-in components (docusaurus/Link and @theme/Heading) already use it internally.
parseFrontMatter hookIn #9624, we added a new siteConfig.markdown.parseFrontMatter function hook.
This 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.
\nexport default {
markdown: {
parseFrontMatter: async (params) => {
// Reuse the default parser
const result = await params.defaultParseFrontMatter(params);
// Process front matter description placeholders
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
// Create your own front matter shortcut
if (result.frontMatter.i_do_not_want_docs_pagination) {
result.frontMatter.pagination_prev = null;
result.frontMatter.pagination_next = null;
}
// Rename an unsupported front matter coming from another system
if (result.frontMatter.cms_seo_summary) {
result.frontMatter.description = result.frontMatter.cms_seo_summary;
delete result.frontMatter.cms_seo_summary;
}
return result;
},
},
};
Read the front matter guide and the parseFrontMatter API ref for details.
Other notable changes include:
\nsiteConfig.markdown.remarkRehypeOptions to pass options to remark-rehype, letting you customize things such as MDX footnote labelPORT environment variableCheck the 3.1.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/3.1", "title": "Docusaurus 3.1", "summary": "We are happy to announce Docusaurus 3.1.", "date_modified": "2024-01-05T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/3.0", "content_html": "Today, we are happy to announce Docusaurus 3.0! 🥳
\nAt Meta Open Source, we believe Docusaurus will help you build the best documentation websites with minimal effort, letting you focus on what really matters: writing the content.
\nThis is a new major version of Docusaurus, coming with new exciting features and upgraded dependencies.
\nIn line with the Semantic Versioning principles, this release includes breaking changes we documented thoroughly in the v3 upgrade guide. 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![\"v3.0](\"https://coinsgpt.github.io/assets/images/social-card-75819f68ecbb579fe176843bb2e3df82.png\")
We 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.
\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:
\nAccording to our release process, 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.
This section only gives you a quick glance. All the breaking changes are thoroughly documented in the v3 upgrade guide.
\nDocusaurus v3 upgraded a few dependencies to new major versions, each coming with its own breaking changes:
\nA typical package.json dependency upgrade looks like:
{
\"dependencies\": {
// upgrade to Docusaurus v3
- \"@docusaurus/core\": \"2.4.3\",
- \"@docusaurus/preset-classic\": \"2.4.3\",
+ \"@docusaurus/core\": \"3.0.0\",
+ \"@docusaurus/preset-classic\": \"3.0.0\",
// upgrade to MDX v3
- \"@mdx-js/react\": \"^1.6.22\",
+ \"@mdx-js/react\": \"^3.0.0\",
// upgrade to prism-react-renderer v2.0+
- \"prism-react-renderer\": \"^1.3.5\",
+ \"prism-react-renderer\": \"^2.1.0\",
// upgrade to React v18.0+
- \"react\": \"^17.0.2\",
- \"react-dom\": \"^17.0.2\"
+ \"react\": \"^18.2.0\",
+ \"react-dom\": \"^18.2.0\"
},
\"devDependencies\": {
// upgrade Docusaurus dev dependencies to v3
- \"@docusaurus/module-type-aliases\": \"2.4.3\",
- \"@docusaurus/types\": \"2.4.3\"
+ \"@docusaurus/module-type-aliases\": \"3.0.0\",
+ \"@docusaurus/types\": \"3.0.0\"
}
\"engines\": {
// require Node.js 18.0+
- \"node\": \">=16.14\"
+ \"node\": \">=18.0\"
}
}
Apart 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:::warning admonition, deprecate :::cautionv2.0.0-beta.10 (December 2021)Below 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.
\nDocusaurus v3 upgraded from MDX v1 to MDX v3:
\nThis new MDX version is much better for content writers and plugin authors, and lays the ground for implementing new exciting Markdown features.
\nThe transition from MDX v1 to MDX v3 is the main challenge to the adoption of Docusaurus v3.
Some documents that compiled successfully under Docusaurus v2 might now fail to compile under Docusaurus v3, while others might render differently.
Most breaking changes come from MDX v2, and MDX v3 is a relatively small release. The MDX v2 migration guide has a section on how to update MDX files that will be particularly relevant to us. Also make sure to read the Troubleshooting MDX page that can help you interpret common MDX error messages.
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 to help you get an estimate of the work to be done, and we recommend to prepare your site in advance.
If you created custom MDX plugins (Remark/Rehype), the AST is slightly different, and you might need to refactor them.
This notably enables us to add a CommonMark mode 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). 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.
We also introduced a new way to configure Markdown globally for your site, and plan to add more flexible options later.
\nexport default {
markdown: {
format: 'mdx',
mermaid: true,
preprocessor: ({filePath, fileContent}) => {
return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
},
mdx1Compat: {
comments: true,
admonitions: true,
headingIds: true,
},
},
};
Docusaurus now uses the 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 such as :textDirective, ::leafDirective or :::containerDirective.
In #9317, we added support for ES Modules and TypeScript config files, including site config, docs sidebars, plugins and presets.
\nHere are 2 TypeScript examples, giving you a modern experience with IDE autocompletion:
\nimport type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
const config: Config = {
title: 'My Site',
favicon: 'img/favicon.ico',
// your site config ...
presets: [
[
'classic',
{
// your preset config ...
} satisfies Preset.Options,
],
],
themeConfig: {
// your theme config ...
} satisfies Preset.ThemeConfig,
};
export default config;
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: ['introduction'],
};
export default sidebars;
Docusaurus 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.
In #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.
Unlisted content will:
\nsitemap.xml<meta name=\"robots\" content=\"noindex, nofollow\" />Unlisted 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:
\nIn #8961, we upgraded to React 18. This is important, notably for the gradual adoption of Concurrent React features, as well as upcoming exciting features such as build-time React Server Components.
\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, notably the new automatic batching behavior.
\nReact 18 comes with new features:
<Suspense>React.lazy()startTransition()Their Docusaurus support is considered as experimental. We might have to adjust the integration in the future, leading to a different runtime behavior.
Docusaurus now uses the \"automatic\" JSX runtime.
\nIt is not needed anymore to import React in JSX files that do not use any React API.
\n- import React from 'react';
export default function MyComponent() {
return <div>Hello</div>;
}
It is now possible to build your static site in dev mode.
\ndocusaurus build --dev
Docusaurus will log more errors to the console, notably React 18 hydration errors through the new onRecoverableError callback.
This 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.
Docusaurus v3 now requires a minimum version of TypeScript 5.0.
\nWe re-internalized the base recommended TypeScript config to a new official package:
\n {
- \"extends\": \"@tsconfig/docusaurus/tsconfig.json\",
+ \"extends\": \"@docusaurus/tsconfig\",
\"compilerOptions\": {
\"baseUrl\": \".\"
}
}
We also have cleaner, normalized exports for Docusaurus core type, plugin, and preset options, which you can use within the brand-new TypeScript config files:
\nimport type {Config} from '@docusaurus/types';
import type {Options, ThemeConfig} from '@docusaurus/preset-classic';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
In #9316, we improved on syntax highlighting thanks to the prism-react-renderer v2 upgrade. For example, a bash param --save is now colored:
npm install --save some-package
The interactive code editor also upgrades to react-live v4, coming with a new sucrase compiler. It is faster, lighter, and supports modern features, notably TypeScript type annotations.
\nfunction Hello() {\n const name: string = 'World';\n return <div>Hello {name}</div>;\n}\n
In #8982 and #8870, we also added magic comments support for TeX-like, Haskell-like, and WebAssembly comment syntax.
\nstringLength :: String -> Int
stringLength [] = 0
stringLength (x:xs) = 1 + stringLength xs
function result = times2(n)
result = n * 2;
end
x = 10;
y = times2(x);
In #9305, we upgraded to Mermaid v10.4 and added support for async diagram rendering. Docusaurus is now able to render new types of diagrams.
\nIn #9028, we made it possible to set custom HTML data attributes 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.
html[data-navbar='false'] .navbar {
display: none;
}
html[data-red-border] div#__docusaurus {
border: red solid thick;
}
Other new features worth mentioning:
\nfeedOptions.limit optionno-html-linksprefer-docusaurus-headingRead Docusaurus v3.0.0 release notes for an exhaustive list of changes.
\nThis release comes with a few features, but more importantly upgrades many pieces of the Docusaurus infrastructure.
\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.
\nNow that we've caught up with our infrastructure, we'll be back delivering useful documentation features very soon, in upcoming minor versions.
\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.
", "url": "https://coinsgpt.github.io/blog/releases/3.0", "title": "Announcing Docusaurus 3.0", "summary": "Today, we are happy to announce Docusaurus 3.0! 🥳", "date_modified": "2023-10-31T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/preparing-your-site-for-docusaurus-v3", "content_html": "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.
Docusaurus v3 is now in beta and the official release is around the corner. This is the perfect time to start preparing your site for this new major version.
\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.
\nThe main breaking change is the upgrade from MDX v1 to MDX v3. Read the MDX v2 and MDX v3 release notes for details. MDX will now compile your Markdown content more strictly and with subtle differences.
\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![\"Preparing](\"https://coinsgpt.github.io/assets/images/social-card-1c688c53b51bdaa6e15ae532bf756276.png\")
This article mentions most Docusaurus v3 breaking changes, but is not exhaustive. Read the v3.0.0-beta.0 release notes for an exhaustive list.
There's a lot of content in this blog post, but many Docusaurus v2 sites can upgrade with very few changes.
If your site is relatively small, with only a few customizations, you can probably upgrade to Docusaurus v3 immediately.
Before preparing for the Docusaurus v3 upgrade, we recommend upgrading to the latest Docusaurus v2 version.
\nDepending on the complexity of your site, it may be a good idea to adopt the visual regression testing workflow that we recently presented. It could help you catch unexpected visual side effects occurring during the Docusaurus v3 upgrade.
\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, 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.
MDX is a major dependency of Docusaurus responsible for compiling your .md and .mdx files to React components.
MDX v3 is much better, but also comes with changes that probably require you to refactor your content a bit. MDX v3 is stricter, and some components that compiled fine under v1 might now fail to compile under v3, most likely because of { and < characters.
Upgrading MDX comes with all the breaking changes documented on the MDX v2 and MDX v3 release blog posts. Most breaking changes come from MDX v2. The MDX v2 migration guide has a section on how to update MDX files that will be particularly relevant to us. Also make sure to read the Troubleshooting MDX page that can help you interpret common MDX error messages.
\nMake sure to also read our updated MDX and React documentation page.
\nWe have a dedicated MDX v3 - Upgrade Support discussion.
The 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.
\nEach MDX version comes with its own playground:
\n\nTo obtain a compilation behavior similar to what Docusaurus v2 uses, please turn on these options on the MDX playground:
MDXremark-gfmremark-directive![\"Screenshot](\"https://coinsgpt.github.io/assets/images/mdx2-playground-options-eab88e8328a6902759c4236ffc93d9c6.png\")
Using the two MDX playgrounds side-by-side, you will soon notice that some content is compiled differently or fails to compile in v3.
\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.
We provide a 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.
\nnpx docusaurus-mdx-checker
For each compilation issue, the CLI will log the file path and a line number to look at.
\n![\"Screenshot](\"https://coinsgpt.github.io/assets/images/mdx-checker-output-0f96cc19fd3ed4d55901ca90ad657c14.png\")
Use this CLI to estimate of how much work will be required to make your content compatible with MDX v3.
This CLI is a best effort, and will only report compilation errors.
It will not report subtle compilation changes that do not produce errors but can affect how your content is displayed. To catch these problems, we recommend using visual regression tests.
We upgraded a few Docusaurus sites to Docusaurus v3 and MDX v3:
\n\nThese upgrades permitted us to aggregate the most common content problems, and document how to best handle them.
\n{The { character is used for opening JavaScript expressions. MDX will now fail if what you put inside {expression} is not a valid expression.
The object shape looks like {username: string, age: number}
\nCould not parse expression with acorn: Unexpected content after expression
\n
Available options to fix this error:
{username: string, age: number}{\\{<The < character is used for opening JSX tags. MDX will now fail if it thinks your JSX is invalid.
Use Android version <5
You can use a generic type like Array<T>
Follow the template \"Road to <YOUR_MINOR_VERSION>\"
\nUnexpected character
\n5(U+0035) before name, expected a character that can start a name, such as a letter,$, or_
\nExpected a closing tag for
\n<T>(1:6-1:9) before the end ofparagraphend-tag-mismatch mdast-util-mdx-jsx
\nExpected a closing tag for
\n<YOUR_MINOR_VERSION>(134:19-134:39) before the end ofparagraph
Available options to fix this error:
Array<T>< or <\\< (unfortunately the \\ will be displayed under MDX v1)Docusaurus supports GitHub Flavored Markdown (GFM), but autolink using the <link> syntax is not supported anymore by MDX.
<sebastien@thisweekinreact.com>
<http://localhost:3000>
\nUnexpected character
\n@(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))
\nUnexpected character
\n/(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))
Use regular Markdown links, or remove the < and >. MDX and GFM are able to autolink literals already.
sebastien@thisweekinreact.com
[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)
http://localhost:3000
[http://localhost:3000](http://localhost:3000)
For users providing a custom MDXComponentmapping, components are now \"sandboxed\":
MDXComponent mapping for h1 only gets used for # hi but not for <h1>hi</h1>MDXComponent component anymoreYour MDXComponent component mapping might not be applied as before, and your custom components might no longer be used.
For native Markdown elements, you can keep using lower-case: p, h1, img, a...
For any other element, use upper-case names.
import MDXComponents from '@theme-original/MDXComponents';
export default {
...MDXComponents,
p: (props) => <p {...props} className=\"my-paragraph\"/>
- myElement: (props) => <div {...props} className=\"my-class\" />,
+ MyElement: (props) => <div {...props} className=\"my-class\" />,
};
In MDX, it is now possible to interleave JSX and Markdown more easily without requiring extra line breaks. Writing content on multiple lines can also produce new expected <p> tags.
See how this content is rendered differently by MDX v1 and v3.
<div>Some **Markdown** content</div>
<div>
Some **Markdown** content
</div>
<div>Some **Markdown** content</div>
<div>Some **Markdown** content</div>
<div>Some <strong>Markdown</strong> content</div>
<div><p>Some <strong>Markdown</strong> content</p></div>
If you don't want an extra <p> tag, refactor content on a case by case basis to use a single-line JSX tag.
<figure>
<img src=\"/img/myImage.png\" alt=\"My alt\" />
- <figcaption>
- My image caption
- </figcaption>
+ <figcaption>My image caption</figcaption>
</figure>
If 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.
Docusaurus v3 now uses Markdown Directives (implemented with remark-directive) as a generic way to provide support for admonitions, and other upcoming Docusaurus features.
\nThis is a :textDirective
::leafDirective
:::containerDirective
Container directive content
:::
Directives are parsed with the purpose of being handled by other Remark plugins. Unhandled directives will be ignored, and won't be rendered back in their original form.
The AWS re:Invent conf is great
Due to :Invent being parsed as a text directive, this will now be rendered as:
The AWS re
conf is great
:: (if it makes sense): : text\\: (unfortunately the \\ will be displayed under MDX v1)MDX does not transform indented text as code blocks anymore.
\n console.log(\"hello\");
The upgrade does not generally produce new MDX compilation errors, but can lead to content being rendered in an unexpected way because there isn't a code block anymore.
Use the regular code block syntax instead of indentation:
```js
console.log('hello');
```
All the official packages (Unified, Remark, Rehype...) in the MDX ecosystem are now ES Modules only and do not support CommonJS anymore.
\nIn practice this means that you can't do require(\"remark-plugin\") anymore.
Docusaurus v3 now supports ES Modules configuration files. We recommend that you migrate your config file to ES module, that enables you to import the Remark plugins easily:
import remarkPlugin from 'remark-plugin';
export default {
title: 'Docusaurus',
/* site config using remark plugins here */
};
If you want to keep using CommonJS modules, you can use dynamic imports as a workaround that enables you to import ES modules inside a CommonJS module. Fortunately, the Docusaurus config supports the usage of an async function to let you do so.
module.exports = async function () {
const myPlugin = (await import('remark-plugin')).default;
return {
// site config...
};
};
If you created custom Remark or Rehype plugins, you may need to refactor those, or eventually rewrite them completely, due to how the new AST is structured. We have created a dedicated support discussion to help plugin authors upgrade their code.
Apart from MDX, there are other breaking changes that you can already prepare your site for, notably major version upgrades of important dependencies.
\nNode.js 16 reached End-of-Life, and Docusaurus v3 now requires Node.js >= 18.0.
\nUpgrade your Docusaurus v2 site to Node.js 18 before upgrading to Docusaurus v3.
Docusaurus v3 now requires React >= 18.0.
\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.
\nSimple Docusaurus sites that only use our official theme code without swizzling do not have anything to do.
\nRead the official React v18.0 and How to Upgrade to React 18, and look at your first-party React code to figure out which components might be affected this React 18 upgrade.
We recommend to particularly look for:
Docusaurus v3 now requires TypeScript >= 5.0.
\nUpgrade your Docusaurus v2 site to TypeScript 5 before upgrading to Docusaurus v3.
The official Docusaurus TypeScript config has been re-internalized from the external package @tsconfig/docusaurus to our new monorepo package @docusaurus/tsconfig.
This new package is versioned alongside all the other Docusaurus core packages, and will be used to ensure TypeScript retro-compatibility and breaking changes on major version upgrades.
\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:
{
\"devDependencies\": {
- \"@tsconfig/docusaurus\": \"^1.0.7\",
+ \"@docusaurus/tsconfig\": \"^3.0.0-beta.0\",
}
}
{
- \"extends\": \"@tsconfig/docusaurus/tsconfig.json\",
+ \"extends\": \"@docusaurus/tsconfig\",
\"compilerOptions\": {
\"baseUrl\": \".\"
}
}
For historical reasons, we support an undocumented admonition :::warning that renders with a red color.
This is a Docusaurus v2 :::warning admonition.
However, the color and icon is historically wrong. Docusaurus v3 re-introduces :::warning admonition officially, documents it, and fix the color and icon.
This is a Docusaurus v3 :::warning admonition.
If 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.
Docusaurus v3 also deprecated the :::caution admonition. Please refactor :::caution (yellow) to either :::warning (yellow) or :::danger (red).
This breaking change will only affect Docusaurus v2 early adopters who versioned their docs before v2.0.0-beta.10 (December 2021).
When creating version v1.0.0, the sidebar file contained a prefix version-v1.0.0/ that Docusaurus v3 does not support anymore.
{
\"version-v1.0.0/docs\": [
\"version-v1.0.0/introduction\",
\"version-v1.0.0/prerequisites\"
]
}
Your Docusaurus v2 site is able to handle the 2 sidebar formats similarly.
You can remove the useless versioned prefix from your versioned sidebars.
{
\"docs\": [\"introduction\", \"prerequisites\"]
}
Docusaurus v3 is now in beta, and already used in production by React-Native, Jest, and our own website.
\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.
\nWe would really appreciate it if you try upgrading and report issues on the 3.0.0-beta.0 release discussion thread.
\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 {
\"dependencies\": {
- \"@docusaurus/core\": \"2.4.3\",
- \"@docusaurus/preset-classic\": \"2.4.3\",
- \"@mdx-js/react\": \"^1.6.22\",
+ \"@docusaurus/core\": \"3.0.0-beta.0\",
+ \"@docusaurus/preset-classic\": \"3.0.0-beta.0\",
+ \"@mdx-js/react\": \"^3.0.0\",
\"clsx\": \"^2.0.0\",
\"prism-react-renderer\": \"^1.3.5\",
- \"react\": \"^17.0.2\",
- \"react-dom\": \"^17.0.2\"
+ \"react\": \"^18.2.0\",
+ \"react-dom\": \"^18.2.0\"
},
\"devDependencies\": {
- \"@docusaurus/module-type-aliases\": \"2.4.3\"
+ \"@docusaurus/module-type-aliases\": \"3.0.0-beta.0\"
}
}
We will be there to help you upgrade through the following support channels:
\nAlternatively, you can look for a paid Docusaurus Service Provider to execute this upgrade for you. If your site is open source, you can also ask our community for free, benevolent help.
\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.
\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.
", "url": "https://coinsgpt.github.io/blog/preparing-your-site-for-docusaurus-v3", "title": "Preparing your site for Docusaurus v3", "summary": "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_modified": "2023-09-29T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Maintenance" ] }, { "id": "https://coinsgpt.github.io/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing", "content_html": "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.
\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), and we would like to help you do this upgrade with confidence.
\nThis article introduces a visual regression testing workflow based on GitHub Actions, Playwright, and Argos. It is not directly coupled to Docusaurus or React, and can be adapted to work with other frontend applications and frameworks.
\n![\"Upgrading](\"https://coinsgpt.github.io/assets/images/social-card-0662a6f419d0032829f99915ccf8918b.png\")
This workflow has been tested while upgrading Docusaurus v2 to v3, and already helped catch a few visual regressions on sites such as React Native, Jest, and the Docusaurus site itself.
\nDocusaurus v3 comes with infrastructure changes and major dependency upgrades such as MDX v3 and React 18, 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.
\nThe general idea is pretty simple:
\nsitemap.xml pages with Playwrightmain and pr-branchArgos 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.
![\"Argos](\"https://coinsgpt.github.io/assets/images/argos-github-status-05e8264c59fa4f8a21292f59665edf3d.png\")
![\"Argos](\"https://coinsgpt.github.io/assets/images/argos-github-comment-8b62a1561b13881608d5c9f8a8f833a5.png\")
Argos 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.
\nCheck the Docusaurus Argos page to explore our own website reports.
\nHere is a more concrete example of Argos reporting a visual regression found while upgrading the React-Native website:
\n![\"Argos](\"https://coinsgpt.github.io/assets/images/argos-react-native-regression-216ace77baedfaf873a770112ec817ac.png\")
This section will describe the implementation details of each step of the workflow.
\nYou will need to sign up to Argos and connect Argos to your GitHub repository
\nThis workflow requires the following dev dependencies, in addition to the usual Docusaurus ones:
\nyarn add -D @argos-ci/cli @argos-ci/playwright @playwright/test cheerio
The GitHub action is responsible for executing the workflow for each Git branch.
\nA minimal workflow could look like:
\nname: Argos CI Screenshots
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
take-screenshots:
runs-on: ubuntu-latest
steps:
- name: Check out repository code
uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: current
- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Install Playwright browsers
run: yarn playwright install --with-deps chromium
- name: Build the website
run: yarn docusaurus build
- name: Take screenshots with Playwright
run: yarn playwright test
- name: Upload screenshots to Argos
run: yarn argos upload ./screenshots
Playwright is responsible for taking screenshots of the website previously built locally by the GitHub action.
\nA minimal Playwright config could look like:
\nimport {devices} from '@playwright/test';
import type {PlaywrightTestConfig} from '@playwright/test';
const config: PlaywrightTestConfig = {
webServer: {
port: 3000,
command: 'yarn docusaurus serve',
},
projects: [
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
},
},
],
};
export default config;
A Playwright config is not enough: we also need to write a Playwright test file to generate the site screenshots.
\nimport * as fs from 'fs';
import {test} from '@playwright/test';
import {argosScreenshot} from '@argos-ci/playwright';
import {extractSitemapPathnames, pathnameToArgosName} from './utils';
// Constants
const siteUrl = 'http://localhost:3000';
const sitemapPath = './build/sitemap.xml';
const stylesheetPath = './screenshot.css';
const stylesheet = fs.readFileSync(stylesheetPath).toString();
// Wait for hydration, requires Docusaurus v2.4.3+
// Docusaurus adds a <html data-has-hydrated=\"true\"> once hydrated
// See https://github.com/facebook/docusaurus/pull/9256
function waitForDocusaurusHydration() {
return document.documentElement.dataset.hasHydrated === 'true';
}
function screenshotPathname(pathname: string) {
test(`pathname ${pathname}`, async ({page}) => {
const url = siteUrl + pathname;
await page.goto(url);
await page.waitForFunction(waitForDocusaurusHydration);
await page.addStyleTag({content: stylesheet});
await argosScreenshot(page, pathnameToArgosName(pathname));
});
}
test.describe('Docusaurus site screenshots', () => {
const pathnames = extractSitemapPathnames(sitemapPath);
console.log('Pathnames to screenshot:', pathnames);
pathnames.forEach(screenshotPathname);
});
Argos has a Playwright integration that wraps the original Playwright screenshot API and provides better defaults to make screenshots more deterministic.
utils.ts?This module contains implementation details that we choose to hide for clarity.
import * as cheerio from 'cheerio';
import * as fs from 'fs';
// Extract a list of pathnames, given a fs path to a sitemap.xml file
// Docusaurus generates a build/sitemap.xml file for you!
export function extractSitemapPathnames(sitemapPath: string): string[] {
const sitemap = fs.readFileSync(sitemapPath).toString();
const $ = cheerio.load(sitemap, {xmlMode: true});
const urls: string[] = [];
$('loc').each(function handleLoc() {
urls.push($(this).text());
});
return urls.map((url) => new URL(url).pathname);
}
// Converts a pathname to a decent screenshot name
export function pathnameToArgosName(pathname: string): string {
return pathname.replace(/^\\/|\\/$/g, '') || 'index';
}
Screenshots 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.
\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 for details.
\n/* Iframes can load lazily */
iframe,
/* Avatars can be flaky due to using external sources: GitHub/Unavatar */
.avatar__photo,
/* Gifs load lazily and are animated */
img[src$='.gif'],
/* Algolia keyboard shortcuts appear with a little delay */
.DocSearch-Button-Keys > kbd,
/* The live playground preview can often display dates/counters */
[class*='playgroundPreview'] {
visibility: hidden;
}
/* Different docs last-update dates can alter layout */
.theme-last-updated,
/* Mermaid diagrams are rendered client-side and produce layout shifts */
.docusaurus-mermaid-container {
display: none;
}
We recommend hiding flaky UI elements affecting layout with display: none;.
For 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.
The 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![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/docusaurus-argos-example-repo-screenshot-a56583e16aa02c7fa96c592f1339928f.png\")
Relevant pull-requests:
\nBrowse the Docusaurus repository for a more advanced integration:
The tools we choose are implementation details of this visual regression testing workflow.
\nFor Docusaurus, we choose Argos: it works well for us, and offers free and open source plans. However, you are free to adopt alternative tools.
\nIn case you don't mind storing large screenshots in Git, you can also try the free, self-hosted Playwright Visual Comparisons and browse visual differences with npx playwright show-report. However, we found using a dedicated external tool is more convenient.
External 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.
\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.
You can decide to filter the pathnames to only take screenshots of the most critical pages.
\nFor the Docusaurus website, do not take screenshots for versioned docs pages:
\nfunction isVersionedDocsPathname(pathname: string): boolean {
return pathname.match(/^\\/docs\\/((\\d\\.\\d\\.\\d)|(next))\\//);
}
test.describe('Docusaurus site screenshots', () => {
const pathnames = extractSitemapPathnames(sitemapPath)
.filter(isVersionedDocsPathname);
pathnames.forEach(screenshotPathname);
});
Implementing GitHub Actions concurrency groups 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.
\nconcurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true
It's not worth running this workflow for every single commit and pull-request.
\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!
\nFor the Docusaurus website, we only run the workflow for pull-request having the Argos label:
name: Argos CI Screenshots
on:
push:
branches: [main]
pull_request:
branches: [main]
types:
- opened
- synchronize
- reopened
- labeled
jobs:
take-screenshots:
if: ${{ github.ref_name == 'main' || (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'Argos')) }}
runs-on: ubuntu-latest
steps:
# Your job steps here ...
There are many options to explore, such as triggering the workflow manually or only when files matching a specific pattern are modified.
\nI believe visual regression testing is underused in the frontend ecosystem.
\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.
\nSo why not give it a try?
\nHappy hacking!
\nUseful documentation links:
\nWe are happy to announce Docusaurus 2.4.
\nThe upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-3239a62bb56c9529ff255bc2c72e94f6.png\")
In #8236, we made it possible to provide a new description attribute for docs sidebar items of type link and category.
[
{
type: 'link',
label: 'Link with description',
href: 'https://docusaurus.io',
description: 'Some link description',
},
{
type: 'category',
label: 'Category with description',
description: 'Some category description',
items: [],
},
];
These descriptions will be used in category generated index pages.
\n![\"Show](\"https://coinsgpt.github.io/assets/images/sidebar-item-description-f38981b17f486bc09fb811c6992ef668.jpg\")
In #8708, we added the possibility to force Docusaurus to initialize itself in light or dark mode through a new docusaurus-theme query-string parameter.
This is useful to ensure a consistent theme when embedding an existing Docusaurus page into an iframe or WebView.
\nIn #8690, we upgraded our Remark plugin @docusaurus/remark-plugin-npm2yarn with many conversion bug fixes, first-class support for pnpm, and the ability to register custom converters producing new tabs.
\nRun these commands!
```bash npm2yarn
npm install
npm run build
npm run myCustomScript -- --some-arg
```
npm install
npm run build
npm run myCustomScript -- --some-arg
yarn install
yarn build
yarn myCustomScript --some-arg
pnpm install
pnpm run build
pnpm run myCustomScript --some-arg
bun install
bun run build
bun run myCustomScript --some-arg
In #8620 we added support for the @docusaurus/plugin-google-gtag plugin to declare multiple tracking IDs.
\nmodule.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
gtag: {
trackingID: [
'G-<YOUR-NEW-GA4-ID>',
'UA-<YOUR-OLD-UA-ID>',
],
},
},
],
],
};
Google will sunset its Universal Analytics on July 1, 2023.
Docusaurus 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.
To 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 for details.
In #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).
\nTo see it in action, click here:
In #8735 we also made navbar-related error messages clearer to help users understand what they did wrong.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/navbar-error-15eefab8e8d77aa4d605939956987164.jpg\")
We made it possible to translate some new elements:
\nprocess.env.DOCUSAURUS_CURRENT_LOCALE (experimental) allowing you to localize your config file, including site title, tagline, announcement bar, baseUrl...We added default theme translation support for multiple languages:
\n\nCompleting theme translations is an ongoing effort and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often need new translations.
Other notable changes include:
\nprefers-reduced-motion: reduce media querydocSidebar in templateCheck the 2.4.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/2.4", "title": "Docusaurus 2.4", "summary": "We are happy to announce Docusaurus 2.4.", "date_modified": "2023-03-23T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/2.3", "content_html": "We are happy to announce Docusaurus 2.3.
\nThe upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-7e038d19ea67c686e90e1f599f7256d0.png\")
Google 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.
\nWe now have a @docusaurus/plugin-google-tag-manager package that you can use alongside or as an alternative to the existing gtag.js plugin (refer to this doc to understand when to use which solution).
Google will sunset its Universal Analytics on July 1, 2023, and ask users to migrate to Google Analytics 4.
Therefore, we are also deprecating our existing @docusaurus/plugin-google-analytics package. Docusaurus users should create a new Google Analytics 4 property, and migrate to the gtag.js plugin, or the Google Tag Manager plugin. Refer to the dedicated Docusaurus issue for details and questions.
It 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.
This feature allows deep-linking to a specific documentation tab that will pre-selected on page load.
\nWhen used alongside the groupId prop, the query string tab value takes precedence over the localStorage value.
Make sure to check the documentation and the demo below to understand how it works:
\n\n<Tabs groupId=\"current-os\" queryString>
<TabItem value=\"android\" label=\"Android\">
Android
</TabItem>
<TabItem value=\"ios\" label=\"iOS\">
iOS
</TabItem>
</Tabs>
Android
iOS
It is now possible to nest one admonition within another by adding extra colons for the outer/enclosing admonition:
\n::::tip[nested admonitions]
You can now nest one admonition within another!
:::danger
Use this sparingly when it makes sense.
:::
::::
You can now nest one admonition within another!
Use this sparingly when it makes sense.
createFeedItemsA new blog plugin option feedOptions.createFeedItems gives you more control over the RSS/Atom feed generation. It is now possible to transform/filter/limit feed items through a new callback.
[
'@docusaurus/preset-classic',
{
blog: {
feedOptions: {
createFeedItems: async (params) => {
const {blogPosts, defaultCreateFeedItems, ...rest} = params;
return defaultCreateFeedItems({
// keep only the 10 most recent blog posts in the feed
blogPosts: blogPosts.filter((item, index) => index < 10),
...rest,
});
},
},
},
},
];
We added or completed the default theme translation support for multiple languages:
\nCompleting theme translations is an ongoing effort and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often need new translations.
Other notable changes include:
\noptions.searchPagePath should be correctly applied to search modal footerdeploy CLI now understands git url insteadOf configCheck the 2.3.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/2.3", "title": "Docusaurus 2.3", "summary": "We are happy to announce Docusaurus 2.3.", "date_modified": "2023-01-27T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/releases/2.2", "content_html": "We are happy to announce Docusaurus 2.2.
\nThe upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-402517ac2205718a22585e627fe1351c.png\")
In #7490, we added support for Mermaid diagrams. This fills the gap between GitHub Flavored Markdown which also added support recently. You can create Mermaid diagrams using Markdown code blocks:
\n```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Health check
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
Make sure to check the documentation, and the more advanced examples
\nheadTagsIn #8151, we added the ability to apply arbitrary HTML <head> tags to all pages of your site.
module.exports = {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'icon',
href: '/img/docusaurus.png',
},
},
],
};
We did several accessibility improvements:
\nWe made validation stricter and improved error messages:
\nsiteConfig.url more strictly and with better error messageurl and baseUrl fail-safe and less sensitive to the presence or absence of a leading or trailing slashWe completed the default theme translation support for multiple languages:
\nCompleting theme translations is an ongoing effort and an easy way to contribute to Docusaurus. We add new theme features regularly, for which we often need new translations.
Other notable changes include:
\ndocusaurus swizzle CLI has a new --config optionCheck the 2.2.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/releases/2.2", "title": "Docusaurus 2.2", "summary": "We are happy to announce Docusaurus 2.2.", "date_modified": "2022-10-29T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/2022/09/01/docusaurus-2.1", "content_html": "We are happy to announce Docusaurus 2.1, our very first minor version release.
\nThe upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/social-card-8dc2413b4f9e86328bf77575e91171d7.png\")
In #8008, we simplified the usage of the<DocCardList> component, that is notably used on sidebar category generated index pages.
The items prop is now optional, and will be automatically inferred from the content of the parent sidebar category:
import DocCardList from '@theme/DocCardList';
- import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
- <DocCardList items={useCurrentSidebarCategory().items}/>
+ <DocCardList/>
Also, we made it possible to use it on any document, including regular docs not linked to any sidebar category.
\n![\"simplified](\"https://coinsgpt.github.io/assets/images/doc-card-list-e52d727eadceb3d21cfc0f851f09aa93.png\")
noindex improvementsWe improved the support of the noindex meta robots directive, a way to signal search engines you don't want a specific page to be indexed.
In #7963, we allow noindex to be configured on a per-docs-version basis.
Use the following plugin options to tell crawlers you don't want the 1.0.0 version to be indexed:
const options = {
versions: {
'1.0.0': {
noIndex: true,
},
},
};
In practice, Docusaurus will add the following meta to each page of that version:
\n<meta name=\"robots\" content=\"noindex, nofollow\" />
In #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.
In #7952, it becomes possible to override default html meta tags you couldn't before:
\n<>
{siteConfig.noIndex && <meta name=\"robots\" content=\"nofollow, noindex\" />}
<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />
</>
It is now possible to use <Head> or themeConfig.metadata:
viewport metarobots meta: you could mark your site as noIndex, but except for specific pages that should be indexedIn #7953, we added default classic theme translations for the Ukrainian language.
\nCheck the 2.1.0 changelog entry for an exhaustive list of changes.
", "url": "https://coinsgpt.github.io/blog/2022/09/01/docusaurus-2.1", "title": "Docusaurus 2.1", "summary": "We are happy to announce Docusaurus 2.1, our very first minor version release.", "date_modified": "2022-09-01T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release" ] }, { "id": "https://coinsgpt.github.io/blog/2022/08/01/announcing-docusaurus-2.0", "content_html": "Today we are extremely happy to finally announce Docusaurus 2.0! 🥳️
\nAt Meta Open Source, we believe Docusaurus will help you build the best documentation websites with minimal effort, letting you focus on what really matters: writing the content.
\nAfter 4 years of work, 75 alphas and 22 betas, the next generation of Docusaurus is ready for prime time. From now on, we now plan to respect Semantic Versioning and will release major versions more frequently.
\n![\"social-card](\"https://coinsgpt.github.io/assets/images/social-card-736cfe55fc7bba07204176852d67c0d5.png\")
In a hurry? Check what's new in Docusaurus 2.0!
Docusaurus is a static site generator that helps you ship beautiful documentation websites in no time.
\nFocus on your content: just write Markdown files. Docusaurus will generate an optimized website for you that's easy to host anywhere.
\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![\"Introducing](\"https://coinsgpt.github.io/assets/images/slash-introducing-411a16dd05086935b8e9ddae38ae9b45.svg\")
The 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.
\nUnless you're spinning up a documentation team with engineering resources, you\nprobably want Docusaurus!
Docusaurus 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!
\nUsing Docusaurus for my tech blog has been a fantastic choice. It looks\ntremendous out-of-the-box and the awesome DX means I write way more
Try Docusaurus now with our online playgrounds and 5 minutes tutorial ⏱️
Docusaurus was created at Facebook Open Source in 2017 (now Meta Open Source). 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.
\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\nIt quickly built momentum at Facebook and in the frontend ecosystem, adopted by many popular projects such as Prettier, Babel, React-Native, KaTeX, and of course Docusaurus v1 itself.
\n\nNotice that the sample sites above use different colors, but still look quite the same.
Docusaurus v1 has been very successful, but we started to question some architectural choices:
\nDocusaurus v2 was rebuilt from the ground up with a new modular architecture:
\nMore details in the Docusaurus 2 project announcement and v1 to v2 migration guide
\nDespite being in pre-release, it didn't take long for Docusaurus v2 to outgrow Docusaurus v1 in terms of NPM downloads:
\n![\"NPM](\"https://coinsgpt.github.io/assets/images/npm-downloads-f9d754a81ff372a5bae83c8751195e2b.png\")
Our GitHub star trend is very positive, competing with major frameworks:
\n![\"GitHub](\"https://coinsgpt.github.io/assets/images/star-history-72ae014f60d05445753e9f690e41d347.png\")
Today, Docusaurus v2 has already been a great success even before its launch:
\nPlease add your site to our site showcase! It only takes a few seconds: just post a comment here.
We use Docusaurus everywhere now and love it
We've been using V2 since January and it has been great
Docusaurus is next level easy for literally everything you would need for\ndocumentation in your project.
Docusaurus is awesome. We use it
It 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.
\nMDX allows you to interleave React components in Markdown. This enables you to build top-notch interactive documentation experiences very easily.
\nA demo is worth a thousand words:
\n![\"Docusaurus](\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=353916&theme=light\")
### Give it a try: press that button!
import ColorModeToggle from '@theme/ColorModeToggle';
<ColorModeToggle/>
MDX has its own plugin system. You to customize your Markdown authoring experience, and even create your own Markdown syntax.
Docusaurus + MDX is great: we were able to implement a beautiful two-pane\nlayout and give the author fine-grained control on the placement of code and\ncorresponding prose.
Our 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\nUsing the auto-generated sidebars makes it so simple to just create a page and\nnot worry about any other configuration.
Docusaurus now has a modular architecture with a plugin system — our core features like docs, blog, pages, and search are all powered by individual plugins.
\nMore importantly, it enables our community to enhance Docusaurus with additional features.
\nLet's highlight some examples:
\n![\"redocusaurus](\"https://coinsgpt.github.io/assets/images/redocusaurus-5cf08a76be6f85090544417b82986cfb.png\")
![\"shiki-twoslash](\"https://coinsgpt.github.io/assets/images/shiki-twoslash-b74271684fa819a0175595409b2f323b.png\")
The plugin API was a breeze to use, and powerful enough that I could port the\ncode sample renderer from the TypeScript website site in a couple of hours.
![\"local](\"https://coinsgpt.github.io/assets/images/search-848f1f1b9eb0d1b710e1d1dec50fb84a.png\")
We have a curated list of outstanding plugins in our community resources page.
The plugin system in Docusaurus v2 has made expanding 1Password's developer\nportal so easy and fun. Super excited to show you what we've got cooking up.
Theming 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.
\nDocusaurus theming gives a lot of flexibility on multiple levels:
\nI love Docusaurus Swizzling feature. It’s opinionated and flexible at the same\ntime. This is super cool since a framework usually needs to sacrifice one for\nthe other.
This enables users willing to invest a bit more time on customizations to build sites that look different from others.
\n\nSo far it’s working out really nicely. It’s been really easy to style up the\nway that we wanted it to look. No blockers at all.
Docusaurus 2 comes with a very long list of useful features:
\n
themeConfig options...Recently, I was shocked at how good Docusaurus is out of the box. Super solid,\na good bit of configuration without being overwhelming, and the ability to\nreally customize the styling if you're braver than I am.
Many 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.
\nThe reason is that we aim to respect Semantic Versioning, which means we will be incrementing the major version number whenever we release a breaking change.
\nIt is important for multiple reasons:
\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, 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.
\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.
Major version numbers are not sacred, but we still group breaking changes together and avoid releasing major versions too often.
Check our release process documentation for details.
![\"Slash](\"https://coinsgpt.github.io/assets/images/slash-up-and-running-1c1f83f3064dcd56be41632c51be62ac.png\")
The 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.
\nA sample of the features on our roadmap for the upcoming major versions of Docusaurus:
\nWe'd like to express our gratitude to all our contributors, including:
\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.
\nAt Meta Open Source, 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!
\nNow, let your imagination run wild 🤪!
\n— Slash
\n![\"Slash](\"https://coinsgpt.github.io/assets/images/slash-plushies-71b7a47477442dfcf890627669aba97d.jpg\")
Docusaurus has made great progress in 2021! We've seen a lot of traction and just crossed 30k stars on GitHub!
\nWe've reached full feature parity with v1 after the release of internationalization, announced our first beta, and welcomed significantly more users this year.
\nThe official v2 release is just around the corner! Follow the roadmap issue for any latest news.
\n![](\"https://coinsgpt.github.io/assets/images/thumbnail-dbb46fec970f4431a6846603224dd2fe.png\")
Let's begin by going over a few highlights this year. Remember the todo-list from half a year ago? Time to take it out again and see how far we've come!
\nsidebars.js anymoreOur 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%!
\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![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/npm-trend-1e69b5c9e35be8bd6d9ac6fbaaf313d7.png\")
(Ah, the classic Christmas dip...)
\nWe released 18 versions, going from 2.0.0-alpha.71 to 2.0.0-beta.14. That's one release every 20 days!
Our star trend is also very positive. Compared to similar projects, we are growing at a faster rate:
\n![\"Stars](\"https://coinsgpt.github.io/assets/images/star-history-c7ba492b822fed1336d08fe449f87840.png\")
With an 8.4k increase in stars, we are ranked number 3 in this year's JavaScript rising stars of static site generators, preceded only by Next.js and Astro.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/rising-stars-56326450d25b95f221f56db3b352c724.png\")
Our showcase has welcomed a few new \"favorite\" sites that showcase the true potential of Docusaurus 2's pluggable architecture.
\n![\"Iota](\"https://coinsgpt.github.io/assets/images/iota-light-d899be0c1eb939a5ad13e2ecca4eb951.png#gh-light-mode-only\")
![\"Iota](\"https://coinsgpt.github.io/assets/images/iota-dark-986d9518ba0e03583d734212ba93539d.png#gh-dark-mode-only\")
![\"Dyte](\"https://coinsgpt.github.io/assets/images/dyte-light-24caa76f96400453386185ae6bc06b8a.png#gh-light-mode-only\")
![\"Dyte](\"https://coinsgpt.github.io/assets/images/dyte-dark-b9748e4bcb4281880ff1856519d58b38.png#gh-dark-mode-only\")
![\"Ionic](\"https://coinsgpt.github.io/assets/images/ionic-light-b8a9c77c71a99f4c71a16584dac8ccf3.png#gh-light-mode-only\")
![\"Ionic](\"https://coinsgpt.github.io/assets/images/ionic-dark-17086f816052f02e84054fe002256ed9.png#gh-dark-mode-only\")
![\"Courier\"](\"https://coinsgpt.github.io/assets/images/courier-624bbae7cbef3b4e7533d1976e35f842.png\")
The creativity of Docusaurus users is beyond our imagination 🤩 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.
\nAs an active moderator on Discord, 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 – case in point, I was formerly a community contributor before becoming a maintainer.
\nWe are constantly mentioned on X with inspirational feedback:
\n\n\n@docusaurus is amazing! cant believe it's THAT simple to use.
\n
\n\nNo extra plugins, tooling or compilation steps. It just works out of the box.
\n
\n\nI 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
And we keep every one of them in our little box 😄 If you enjoy Docusaurus yourself, keep tagging us with your comments!
\nAs we approach the official release, we are interested in knowing more about what people are doing out there: plugin authors, creators of customized sites, and all new users – please keep us posted about your achievements so we can steer our development to better serve your needs.
\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 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:
\nRead more about plans for Docusaurus 2.0 in this roadmap issue. 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!
\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!
\nWith the official release of Docusaurus 2.0, we are confident to see much more new adoptions and migrations from v1.
\nWe'd like to express our gratitude to all the contributors in 2021, including:
\nSo long, 2021, and let's greet a great 2022!
", "url": "https://coinsgpt.github.io/blog/2022/01/24/docusaurus-2021-recap", "title": "Docusaurus 2021 Recap", "summary": "Docusaurus has made great progress in 2021! We've seen a lot of traction and just crossed 30k stars on GitHub!", "date_modified": "2022-01-24T00:00:00.000Z", "author": { "name": "Joshua Chen", "url": "https://joshcena.com/" }, "tags": [ "Recap" ] }, { "id": "https://coinsgpt.github.io/blog/2021/11/21/algolia-docsearch-migration", "content_html": "DocSearch is migrating to a new, more powerful system, which gives users their own Algolia application and new credentials.
\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.
\nIn the next few weeks, Docusaurus site owners will receive an email inviting them to join their personal Algolia application.
\nThis email will include a new appId and apiKey to use in your Docusaurus configuration.
The only things you have to do:
\nconst config = {
themeConfig: {
algolia: {
appId: '<NEW_APP_ID>',
apiKey: '<NEW_SEARCH_API_KEY>',
},
},
};
module.exports = config;
appId is now required.
These keys are not secrets and can be added to your Git repository.
DocSearch is a program created by Algolia, which offers search to technical documentation of Open Source projects and technical blogs for free.
\nYou can read more here, and apply if you'd like to give it a try!
\nWith the upcoming stable release of DocSearch UI, we wanted to go further and provide better tooling for our users to improve their search, but also leverage the full potential of Algolia.
\nDocSearch now leverages the Algolia Crawler, which includes a web interface that will allow you to:
\n![\"The](\"https://coinsgpt.github.io/assets/images/crawler-overview-6224cc4c7b20511010652f3f4ed5904e.png\")
![\"The](\"https://coinsgpt.github.io/assets/images/editor-823e50dbed8e508bd5a69c708bab8928.png\")
But also, more Algolia features in your own Algolia app:
\n![\"The](\"https://coinsgpt.github.io/assets/images/index-overview-ca216346e6eee6881443644b6d7d8fe8.png\")
![\"The](\"https://coinsgpt.github.io/assets/images/index-analytics-f9c27da3900de6206e949736b1cd8101.png\")
And of course, a lot more, for free.
\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!
\nWe wrote a small migration guide but you'll have more detailed information in the migration email.
\nPlease contact us via either email or DocSearch's Discord or on Docusaurus's Discord #algolia channel
\nFor any feedback regarding our documentation or the DocSearch UI component, you can open an issue on our GitHub repository, but also contact us via the methods above.
\nIn favor of the new infrastructure and DocSearch v3, we will no longer maintain our beloved DocSearch scraper and DocSearch v2, but the repositories will still be available and open to pull requests.
\nThe previous documentation (now called legacy) remains available as well as our run your own guide.
After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first Docusaurus 2 beta.
\nWith the announcement of this beta, the team is even more confident that Docusaurus 2 is ready for mainstream adoption!
\n![](\"https://coinsgpt.github.io/assets/images/image_cropped-2744c01b1fc0b451dbdb65a1d568fbff.png\")
Don't fear the beta tag!
\nDocusaurus 2 is widely adopted and growing fast:
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/trend-2735e446f67fbcaa0811d103588e9b82.png\")
To get a fuller understanding of the quality of current Docusaurus 2 sites, our new 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!
\nDon't miss our favorite sites; they all stand out with something unique:
\n![\"A](\"https://coinsgpt.github.io/assets/images/favorites-7220082695a33eba77188ba7223c165c.png\")
It's hard to believe that the first alpha release v2.0.0-alpha.0 was 2 years ago 😳 , unusually long for a software alpha.
\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, and it has been successfully adopted by many Docusaurus sites (see i18n showcase).
\nWe're now quite confident that the core features of Docusaurus 2 are stable enough to be in beta.
\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.
\nIn addition, we will use the beta phase to improve our theming system.
\nWe want to make it:
\neasier to implement a custom theme, including for ourselves. We want to provide multiple official themes (including Tailwind CSS) for a long time.
\nsafer 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.
\nWe will build a better theming infrastructure and refactor the classic theme to use it.
\nIf you customize your site, you may find these planned improvements quite valuable.
\nIn case you missed it, we recently shipped two major improvements:
\nsidebars.js file anymore!Shipping the official 2.0 release!
\nTo get there, we will continue to fix bugs and implement the most wanted features, including:
\nThis is an exciting time for Docusaurus.
\nWe are inspired by the positive feedback about Docusaurus, and discover new sites online every single day.
\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.
\nThank you to everyone for reading and to the entire community who supports Docusaurus. 🤗
", "url": "https://coinsgpt.github.io/blog/2021/05/12/announcing-docusaurus-two-beta", "title": "Announcing Docusaurus 2 Beta", "summary": "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_modified": "2021-05-12T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release", "Beta" ] }, { "id": "https://coinsgpt.github.io/blog/2021/03/09/releasing-docusaurus-i18n", "content_html": "Today, we officially release Docusaurus 2 i18n (internationalization), as part of 2.0.0-alpha.71.
\nDocusaurus 2 has now reached full feature parity with Docusaurus 1. 🎉 And soon, after a few additional infrastructure updates and a bit more testing, the first Docusaurus 2 beta will be released.
\nWe went the extra mile, and the new i18n support is even better than in Docusaurus 1.
\nIn this post, we will present you the translation workflow, explain some design decisions and showcase early adopter sites that just went live: Jest, Redwood, and Datagit.
\nWe also dogfood the i18n support on the Docusaurus 2 site itself, and this post is already available in English and French!
\nYou can translate a Docusaurus site in 3 simple steps:
\ndocusaurus.config.jsThe i18n support is very flexible and based on the filesystem.
\nThe i18n tutorial is the best way to get started, and we provide help to use Git or Crowdin.
\nThe goals of the Docusaurus i18n system are:
\nhreflang for youWe worked with a few volunteers to dogfood the i18n support before releasing it.
\nWe have made it possible to upgrade a translated Docusaurus 1 site to Docusaurus 2.
\nJest, using Docusaurus 1 and Crowdin was one of those sites.
\nThe Docusaurus 2 migration was successful and the new site is now deployed in production (announcement post).
\n![\"Jest's](\"https://coinsgpt.github.io/assets/images/jest-59f159eb97ecd87655cf47ec5cc00d47.png\")
Redwood is a React full-stack Jamstack framework.
\nThey were looking for a solution to create an internationalized learning platform, and became early adopters of Docusaurus 2 i18n for learn.redwoodjs.com, using Crowdin to get it translated to French.
\n![\"Redwood's](\"https://coinsgpt.github.io/assets/images/redwood-c3155187911b62428e0cc1e8b662de76.png\")
The i18n system should work with any language, including Right-to-Left languages.
\nDatagit.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![\"Datagit's](\"https://coinsgpt.github.io/assets/images/datagit-9cff7b631eaa43b00d9e1373359abfb1.png\")
We sincerely hope you will adopt and like the new i18n support.
\nThis feature has not been an easy one, and we would like to thank everyone that got involved in this journey:
\nThanks for reading.
\n🙏 And please, add your brand new i18n sites to our showcase page. We accept any all polished Docusaurus site here, and we are working on a redesign allowing you to filter sites by features.
", "url": "https://coinsgpt.github.io/blog/2021/03/09/releasing-docusaurus-i18n", "title": "Releasing Docusaurus i18n", "summary": "Today, we officially release Docusaurus 2 i18n (internationalization), as part of 2.0.0-alpha.71.", "date_modified": "2021-03-09T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Release", "I18n" ] }, { "id": "https://coinsgpt.github.io/blog/2021/01/19/docusaurus-2020-recap", "content_html": "2020 was great for Docusaurus, despite a regrettable start and a tumultuous year for everyone.
\nWe continued to invest in Docusaurus 2, and made it reach full feature parity with Docusaurus 1.
\nWe now recommend Docusaurus 2 as the default choice to start a new Docusaurus project and encourage v1 users to migrate to Docusaurus 2.
\nWe are still in alpha, but expect some good news very soon!
\n![\"Three](\"https://coinsgpt.github.io/assets/images/docusaurus-plushie-banner-a60f7593abca1e3eef26a9afa244e4fb.jpeg\")
We have worked on many features this year, and would like to highlight the most significant ones:
\n@canary npm tag to use the upcoming release before anyone elseThe plan to rebuild Docusaurus from scratch in 2019 paid off: after a slow start, Docusaurus 2 has been widely adopted and has already outgrown Docusaurus 1 usage.
\n![\"Docusaurus](\"https://coinsgpt.github.io/assets/images/docusaurus-npm-trends-3c618d573fc9ca319e54667383ea1e01.png\")
Notable projects, startups, large companies, and individuals adopted Docusaurus 2 (showcase):
\nWe helped large scale Docusaurus 1 sites to upgrade, ensuring a proper migration path and feature parity.
\nReact Native was successfully upgraded to Docusaurus 2 (archived v1 site):
\n![\"React](\"https://coinsgpt.github.io/assets/images/react-native-screenshot-d5ace12ce89fe59dc14ac25859685b01.png\")
Localized Docusaurus 1 sites (like Jest) will be able to upgrade too:
\n![\"Jest's](\"https://coinsgpt.github.io/assets/images/jest-screenshot-fa8ba3dd1b0ebbf923ed56274f0e4f5e.png\")
We also saw the first right-to-left Docusaurus 2 site published:
\n![\"Datagit's](\"https://coinsgpt.github.io/assets/images/datagit-rtl-screenshot-0def4b4e4d5f458ea864774e78b0bf8f.png\")
We have welcomed Major League Hacking (MLH) fellows for 2 seasons already.
\nWe are very thankful for the various contributions they made, such as:
\nWe look forward to continuing this collaboration in 2021.
\nDmitry Vinnik (Developer Advocate @ Facebook) explains Docusaurus in 60 seconds or 15min videos.
\nRachel Nabors (Documentation Engineer @ Facebook) talked a bit about Docusaurus in React Native Radio 178 (podcast), and William Candillon the React Native website migration (video).
\nMany blog posts have been published:
\nThe Docusaurus community continues to grow, the Discord server is quite active, and Stack Overflow questions keep being posted.
\nThe modular architecture of Docusaurus 2 allowed the community to build and publish third-party plugins. As we would like to federate better our community, if you are building a plugin, please let us know.
\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.
\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.
\nWe still have a few major features that we would like to work on:
\nHuge thanks to the community for their contributions in 2020, especially:
\nCheers to a great 2021! 🎉
", "url": "https://coinsgpt.github.io/blog/2021/01/19/docusaurus-2020-recap", "title": "Docusaurus 2020 Recap", "summary": "2020 was great for Docusaurus, despite a regrettable start and a tumultuous year for everyone.", "date_modified": "2021-01-19T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Recap" ] } ] }