From 44684421f5a82be8c46224b792ce4f27305314e7 Mon Sep 17 00:00:00 2001 From: sebastien Date: Thu, 5 Mar 2026 19:01:04 +0100 Subject: [PATCH 1/9] commit mdx parser update --- crowdin-v2.yaml | 128 +++++++----------------------------------------- 1 file changed, 19 insertions(+), 109 deletions(-) diff --git a/crowdin-v2.yaml b/crowdin-v2.yaml index 08a78b4e76a8..4e52e3cc84a7 100644 --- a/crowdin-v2.yaml +++ b/crowdin-v2.yaml @@ -20,18 +20,24 @@ languages_mapping: &languages_mapping two_letters_code: pt-BR: pt-BR -# Crowdin regularly update their MDX parser -# Unfortunately, their v2 parser is more "MDX compliant" and thus can't parse -# Docusaurus MDX files correctly due to our custom {#headingId} syntax. -# Adding this type param permits using their older v1.2 parser. -# Note: you can find the version of a file using browser DevTools -# The source file icons will have a class such as "file_type_mdx_v1_2" -# -# TODO fix our headingId syntax -# providing an explicit type is annoying and not future-proof -# there's a risk that when adding an image in /docs, it will be parsed as mdx -# and duplicating source file configs for various extensions is not great either -mdx_file_type: &mdx_file_type mdx_v1_2 +# Crowdin regularly update their MDX parser, leading to subtle breakage. +# Freezing the parser to a specific version is helpful to ensure things keep +# working when they upgrade their MDX parser. +# See https://github.com/facebook/docusaurus/pull/11432 +# +# Note: you can find the parser version of a Crowdin file using browser DevTools +# and inspecting the MDX file icon, it should have a class ".file_type_mdx_v1_2" +# Find the latest version: manually upload a new .mdx file, then inspect it +# +# How to upgrade the parser version? +# - Rename /docs to /docs_backup on Crowdin UI (same for other mdx folders) +# - Update the parser version of this config file +# - Use the CLI to re-upload the MDX source files: they should now have the new parser version +# - Use the CLI to download the translations +# - Build the full i18n site to ensure it still works (the new parser might break things) +# - Make sure the site content remains translated (normally /docs & /docs_backup share the translation strings) +# - If things work well, you can merge the config update and delete the mdx backup folders on Crowdin UI +mdx_file_type: &mdx_file_type mdx_v2_4 # # Files configuration @@ -62,6 +68,7 @@ files: - source: /website/community/**/* translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name% languages_mapping: *languages_mapping + type: *mdx_file_type - source: /website/blog/**/* translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name% @@ -71,100 +78,3 @@ files: translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name% ignore: [/**/*.js, /**/*.jsx, /**/*.ts, /**/*.tsx, /**/*.css] languages_mapping: *languages_mapping -# -# Source files filter -# e.g. "/resources/en/*.json" -# -#"source" : "/website/docs/**/*.md", -# -# Where translations will be placed -# e.g. "/resources/docs/%two_letters_code%/%original_file_name%" -# -#"translation" : "/website/i18n/%language%/docs/current/%original_file_name%", -# -# Files or directories for ignore -# e.g. ["/**/?.txt", "/**/[0-9].txt", "/**/*\?*.txt"] -# -#"ignore" : [], -# -# The dest allows you to specify a file name in Crowdin -# e.g. "/messages.json" -# -#"dest" : "", -# -# File type -# e.g. "json" -# -#"type" : "", -# -# The parameter "update_option" is optional. If it is not set, after the files update the translations for changed strings will be removed. Use to fix typos and for minor changes in the source strings -# e.g. "update_as_unapproved" or "update_without_changes" -# -#"update_option" : "", -# -# Start block (for XML only) -# -# -# Defines whether to translate tags attributes. -# e.g. 0 or 1 (Default is 1) -# -# "translate_attributes" : 1, -# -# Defines whether to translate texts placed inside the tags. -# e.g. 0 or 1 (Default is 1) -# -# "translate_content" : 1, -# -# This is an array of strings, where each item is the XPaths to DOM element that should be imported -# e.g. ["/content/text", "/content/text[@value]"] -# -# "translatable_elements" : [], -# -# Defines whether to split long texts into smaller text segments -# e.g. 0 or 1 (Default is 1) -# -# "content_segmentation" : 1, -# -# End block (for XML only) -# -# -# Start .properties block -# -# -# Defines whether single quote should be escaped by another single quote or backslash in exported translations -# e.g. 0 or 1 or 2 or 3 (Default is 3) -# 0 - do not escape single quote; -# 1 - escape single quote by another single quote; -# 2 - escape single quote by backslash; -# 3 - escape single quote by another single quote only in strings containing variables ( {0} ). -# -# "escape_quotes" : 3, -# -# Defines whether any special characters (=, :, ! and #) should be escaped by backslash in exported translations. -# e.g. 0 or 1 (Default is 0) -# 0 - do not escape special characters -# 1 - escape special characters by a backslash -# -# "escape_special_characters": 0 -# -# -# End .properties block -# -# -# Often software projects have custom names for the directories where translations are placed. crowdin-cli allows you to map your own languages to be understandable by Crowdin. -# -#"languages_mapping" : { -# "two_letters_code" : { -# "crowdin_language_code" : "local_name" -# } -#}, -# -# Does the first line contain header? -# e.g. true or false -# -#"first_line_contains_header" : true, -# -# for spreadsheets -# e.g. "identifier,source_phrase,context,uk,ru,fr" -# -# "scheme" : "", From 75cf9a149dac81d454cd4a7285332791c62a682f Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 6 Mar 2026 17:31:23 +0100 Subject: [PATCH 2/9] convert blog and community to native mdx --- crowdin-v2.yaml | 42 ++++++++-------- .../2017/12-14-introducing-docusaurus.mdx | 14 +++--- ...-How-I-Converted-Profilo-To-Docusaurus.mdx | 8 ++-- .../blog/2018/09-11-Towards-Docusaurus-2.mdx | 30 ++++++------ .../2018/12-14-Happy-First-Birthday-Slash.mdx | 2 +- .../blog/2019/12-30-docusaurus-2019-recap.mdx | 14 +++--- website/blog/2020/01-07-tribute-to-endi.mdx | 2 +- .../blog/2021/01-19-docusaurus-2020-recap.mdx | 16 +++---- .../2021/03-09-releasing-docusaurus-i18n.mdx | 16 +++---- .../index.mdx | 14 +++--- .../index.mdx | 26 +++++----- .../01-24-docusaurus-2021-recap/index.mdx | 16 +++---- .../08-01-announcing-docusaurus-2.0/index.mdx | 26 +++++----- .../blog/2022/09-01-docusaurus-2.1/index.mdx | 14 +++--- .../index.mdx | 30 ++++++------ .../index.mdx | 48 +++++++++---------- website/blog/releases/2.2/index.mdx | 14 +++--- website/blog/releases/2.3/index.mdx | 16 +++---- website/blog/releases/2.4/index.mdx | 18 +++---- website/blog/releases/3.0/index.mdx | 28 +++++------ website/blog/releases/3.1/index.mdx | 10 ++-- website/blog/releases/3.2/index.mdx | 16 +++---- website/blog/releases/3.3/index.mdx | 12 ++--- website/blog/releases/3.4/index.mdx | 12 ++--- website/blog/releases/3.5/index.mdx | 20 ++++---- website/blog/releases/3.6/index.mdx | 26 +++++----- website/blog/releases/3.7/index.mdx | 8 ++-- website/blog/releases/3.8/index.mdx | 28 +++++------ website/blog/releases/3.9/index.mdx | 12 ++--- website/community/0-support.mdx | 8 ++-- website/community/1-team.mdx | 8 ++-- website/community/2-resources.mdx | 18 +++---- website/community/4-canary.mdx | 4 +- website/community/5-release-process.mdx | 18 +++---- 34 files changed, 297 insertions(+), 297 deletions(-) diff --git a/crowdin-v2.yaml b/crowdin-v2.yaml index 4e52e3cc84a7..b9e5b1b86d7c 100644 --- a/crowdin-v2.yaml +++ b/crowdin-v2.yaml @@ -43,27 +43,27 @@ mdx_file_type: &mdx_file_type mdx_v2_4 # Files configuration # files: - - source: /website/i18n/en/**/* - translation: /website/i18n/%two_letters_code%/**/%original_file_name% - languages_mapping: *languages_mapping - - - source: /website/docs/**/*.mdx - translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name% - languages_mapping: *languages_mapping - type: *mdx_file_type - - source: /website/docs/**/* - translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name% - languages_mapping: *languages_mapping - ignore: [/**/*.mdx] - - - source: /website/versioned_docs/**/*.mdx - translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name% - languages_mapping: *languages_mapping - type: *mdx_file_type - - source: /website/versioned_docs/**/* - translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name% - languages_mapping: *languages_mapping - ignore: [/**/*.mdx] + # - source: /website/i18n/en/**/* + # translation: /website/i18n/%two_letters_code%/**/%original_file_name% + # languages_mapping: *languages_mapping + # + # - source: /website/docs/**/*.mdx + # translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name% + # languages_mapping: *languages_mapping + # type: *mdx_file_type + # - source: /website/docs/**/* + # translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name% + # languages_mapping: *languages_mapping + # ignore: [/**/*.mdx] + # + # - source: /website/versioned_docs/**/*.mdx + # translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name% + # languages_mapping: *languages_mapping + # type: *mdx_file_type + # - source: /website/versioned_docs/**/* + # translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name% + # languages_mapping: *languages_mapping + # ignore: [/**/*.mdx] - source: /website/community/**/* translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name% diff --git a/website/blog/2017/12-14-introducing-docusaurus.mdx b/website/blog/2017/12-14-introducing-docusaurus.mdx index 7698b3223e96..e79ab44fece0 100644 --- a/website/blog/2017/12-14-introducing-docusaurus.mdx +++ b/website/blog/2017/12-14-introducing-docusaurus.mdx @@ -15,13 +15,13 @@ We created [Docusaurus](https://docusaurus.io) for the following reasons: 1. To make it easy to push updates, new features, and bug fixes to everyone all at once. 1. And, finally, to provide a consistent look and feel across all of our open source projects. - +{/* truncate */} Docusaurus is a tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details. At its core, all a user has to provide are documentation files written in Markdown, customization of a provided home page written in React, and a few configuration modifications. Docusaurus handles the rest by providing default styles, site formatting, and simple document navigation. Getting started is easy, as users can [install](https://v1.docusaurus.io/docs/en/installation.html) it using `npm` or `yarn` via a simple initialization script that [creates a working example website out of the box](https://v1.docusaurus.io/docs/en/site-preparation.html). Docusaurus also provides core website and documentation features out-of-the-box including [blog support](https://v1.docusaurus.io/docs/en/blog.html), [internationalization](https://v1.docusaurus.io/docs/en/translation.html), [search](https://v1.docusaurus.io/docs/en/search.html), and [versioning](https://v1.docusaurus.io/docs/en/versioning.html). While some projects may not require any of these features, enabling them is generally a matter of updating configuration options instead of having to add the infrastructure from the ground up. As more features get added to Docusaurus, users just can easily update to the latest version. This can be done by simply running npm or yarn update and updating configuration options. Users or teams will no longer need to manually rework their entire website infrastructure each time a new feature gets added. -## The Birth of docusaurus +## The Birth of docusaurus {/* #the-birth-of-docusaurus */} ![](/img/slash-birth.png) @@ -37,7 +37,7 @@ Docusaurus was born! At Facebook, Docusaurus allows us to quickly get different projects up and running with documentation websites, especially for teams who don't have much experience with web development or primarily want a basic site to showcase their project. Docusaurus already supports sites needing more advanced features like internationalization for Jest and versioning for React Native. As different projects request new features for their sites, they are added to Docusaurus and simultaneously provided to all projects! All together, this ends up greatly reducing the work needed to maintain different sites for different projects. Our teams are able to focus on keeping their projects healthier by spending more time adding features, fixing bugs, and writing documentation. -## Getting Up and Running +## Getting Up and Running {/* #getting-up-and-running */} ![](/img/slash-up-and-running.png) @@ -69,7 +69,7 @@ root-of-repo With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your Markdown that represents your documentation; the blog folder is where you add your Markdown for your [blog posts](https://v1.docusaurus.io/docs/en/blog.html); `siteConfig.js` is where you make most of the [customizations](https://v1.docusaurus.io/docs/en/site-config.html) for your site; `sidebars.json` is where you maintain the layout and content of the [sidebar](https://v1.docusaurus.io/docs/en/navigation.html) for your documentation; the `pages` folder is where you add [custom](https://v1.docusaurus.io/docs/en/custom-pages.html) pages for your site; the `static` folder is where all of your static assets go (e.g., CSS stylesheets and images); and the `core` folder is where you can customize core components of the site, in this case the footer. -## How does Docusaurus work? +## How does Docusaurus work? {/* #how-does-docusaurus-work */} Docusaurus is written primarily in JavaScript and [React](https://facebook.github.io/react), replacing Jekyll which we used in the old template. We use [Remarkable](https://github.com/jonschlinkert/remarkable) for our Markdown rendering and [highlight.js](https://highlightjs.org/) for our code block syntax highlighting. The core of Docusaurus' functionality is in the [lib directory](https://github.com/facebookexperimental/Docusaurus/tree/master/lib) of the [Docusaurus repo](https://github.com/facebook/docusaurus/). The general structure looks like: @@ -125,13 +125,13 @@ build │ └── users.html # custom page ``` -## Community +## Community {/* #community */} ![](/img/docusaurus.svg) We welcome your [contributions](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md) to Docusaurus, whether you want to use it for your own site, you want to [contribute](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md) to the Docusaurus core or just have questions. Follow us on [GitHub](https://github.com/facebook/docusaurus) and [X)](https://x.com/docusaurus). -## Acknowledgements +## Acknowledgements {/* #acknowledgements */} Docusaurus wouldn't exist without the work of the rest of the core Docusaurus team: [Eric Nakagawa](http://x.com/ericnakagawa), [Hector Ramos](https://x.com/hectorramos), [Eric Vicenti](https://x.com/EricVicenti) and [Frank Li](https://github.com/deltice) — a former intern at Facebook who implemented the core technology and features. @@ -148,7 +148,7 @@ Special thanks also goes out to our earliest [adopters](https://v1.docusaurus.io Without their dedication to creating or migrating their websites over to the platform, we would have not have been in the position where we are today. -## Resources +## Resources {/* #resources */} - [Read our documentation](https://v1.docusaurus.io) - [Follow our X feed](https://x.com/docusaurus) diff --git a/website/blog/2018/04-30-How-I-Converted-Profilo-To-Docusaurus.mdx b/website/blog/2018/04-30-How-I-Converted-Profilo-To-Docusaurus.mdx index 2c2eb734dc89..8514dbb9bf68 100644 --- a/website/blog/2018/04-30-How-I-Converted-Profilo-To-Docusaurus.mdx +++ b/website/blog/2018/04-30-How-I-Converted-Profilo-To-Docusaurus.mdx @@ -12,7 +12,7 @@ This is the story of the rather short journey it took to create the [Profilo](ht Profilo, an Android library for collecting performance traces from production, [was announced](https://code.fb.com/android/profilo-understanding-app-performance-in-the-wild/) earlier this year. The project was [published on GitHub](https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8) with a less than [a handful or Markdown files](https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8/docs) to describe its functionality and no website to showcase any branding and highlight the logo. The task at hand was to turn these existing docs and logo into a website. - +{/* truncate */} In general, when creating a website with Docusaurus you do the following: @@ -26,7 +26,7 @@ In general, when creating a website with Docusaurus you do the following: Given I had pre-existing Markdown files, I didn't have to generate the core content but simply make sure that Docusaurus could process the files by adding the expected metadata to them. Most of the work would therefore consist of customizing the defaults provided by Docusaurus. -## Overview of Steps Taken +## Overview of Steps Taken {/* #overview-of-steps-taken */} Here's an overview of the steps taken to convert to a website. I'll discuss some of the design aspects in a later section. @@ -83,7 +83,7 @@ Here's an overview of the steps taken to convert to a website. I'll discuss some The final website was published on https://facebookincubator.github.io/profilo/. It had taken 1.5 hours to get to the initial PR stage and another half an hour or so to respond to review feedback and publish the website. -## Design +## Design {/* #design */} Here's what the initial website looked like when the first pull request was sent out: @@ -115,7 +115,7 @@ Lastly, I didn't have to worry about handling responsive design. You get this ou ![Mobile screenshots of the front page and sample doc page. The layout is automatically adjusted to make it appear more natural. The doc sidebar is hidden behind a button.](/img/profilo_blog_post_android_ios.png) -## Final Thoughts +## Final Thoughts {/* #final-thoughts */} The Profilo engineers were happy to see that they didn't have to change their workflow to update existing content. They were able to continue working with Markdown files. This will still be true in the future if new docs are added, although there may be some config changes needed if the sidebar navigation needs to be updated. diff --git a/website/blog/2018/09-11-Towards-Docusaurus-2.mdx b/website/blog/2018/09-11-Towards-Docusaurus-2.mdx index e8d11b306a13..1cc08c93e0ee 100644 --- a/website/blog/2018/09-11-Towards-Docusaurus-2.mdx +++ b/website/blog/2018/09-11-Towards-Docusaurus-2.mdx @@ -8,9 +8,9 @@ Docusaurus was [officially announced](https://v1.docusaurus.io/blog/2017/12/14/i There is a saying that the very best software is constantly evolving, and the very worst is not. In case you are not aware, we have been planning and working on the next version of Docusaurus 🎉. - +{/* truncate */} -## Introduction +## Introduction {/* #introduction */} It all started with this [RFC issue](https://github.com/facebook/docusaurus/issues/789) opened by [Yangshun](https://github.com/yangshun) towards the end of June 2018. @@ -27,9 +27,9 @@ It all started with this [RFC issue](https://github.com/facebook/docusaurus/issu Most of the suggested improvements are mentioned in the issue; I will provide details on some of issues in Docusaurus 1 and how we are going to address them in Docusaurus 2. -## Infrastructure +## Infrastructure {/* #infrastructure */} -### Content +### Content {/* #content */} A Docusaurus 1 website is, in fact, built into a bunch of static HTML pages. Despite using React, we were not fully utilizing the features React offered, such as component state, which allows for dynamic and interactive pages. React was only used as a templating engine for static content and interactivity has to be added through script tags and `dangerouslySetInnerHTML` 😱. @@ -37,7 +37,7 @@ In addition, there is not an easy way to change how Docusaurus loads content. Fo For Docusaurus 2, we will be using [webpack](https://webpack.js.org/) as a module bundler and we are changing the way we serve content. Adding CSS preprocessors will be as easy as adding a webpack loader. Instead of a pure static HTML, **during build time we will create a server-rendered version of the app** and render the corresponding HTML. A Docusaurus site will be essentially an isomorphic/universal application. This approach is heavily inspired by [Gatsby](https://github.com/gatsbyjs/gatsby). -### Versioning +### Versioning {/* #versioning */} If you have been using Docusaurus for a while, you might notice that Docusaurus creates versioned docs **if and only if** the docs content are **different**. @@ -70,7 +70,7 @@ In addition, this adds complexity within the codebase as we require a mechanism For Docusaurus 2, **every time we cut a new version, we will instead take a snapshot of all the docs**. We will not require the content of a document to have changed. This is a space complexity trade-off for a better developer and user experience. We will use more space for better separation of concerns and guaranteed correctness. -### Translation +### Translation {/* #translation */} Docusaurus allows for easy translation functionality by using [Crowdin](https://crowdin.com/). Documentation files written in English are uploaded to Crowdin for translation by users within a community. We always assumed that **English** is the default language, but this might not be the case for all users. We have seen plenty of non-English open source projects using Docusaurus. @@ -78,21 +78,21 @@ For Docusaurus 2, **we will not assume English is the default language**. When a In addition, after working on the MVP of Docusaurus 2, I realized that it is possible not to use Crowdin for translations. Thus, we might need to add an additional workflow to enable that scenario. However, we will still strongly recommend people use Crowdin for easier integration. -## Customizability +## Customizability {/* #customizability */} -### Layout +### Layout {/* #layout */} The current state of Docusaurus is that it is in charge of the entire layout and styling, unintentionally making it very hard for users to customize their site's appearance to their wishes. For Docusaurus 2, **layout and styling should be controlled by the user**. Docusaurus will handle the content generation, routing, translation, and versioning. Inspired by [create-react-app](https://github.com/facebook/create-react-app) and [VuePress](https://vuepress.vuejs.org/), Docusaurus will still provide a default theme, which the user can eject from, for further layout and styling customization. This means that it is very possible for the user to even change the HTML meta by using [React Helmet](https://github.com/nfl/react-helmet). Community-based themes are also very possible. This approach of allowing users to be in charge of layout and styling is taken by most static site generators. -### Markdown +### Markdown {/* #markdown */} Our Markdown parsing is currently powered by [Remarkable](https://github.com/jonschlinkert/remarkable). What if the user wants to use [Markdown-it](https://github.com/Markdown-it/Markdown-it) or even [MDX](https://github.com/mdx-js/mdx)? And then there is an issue of which syntax highlighter to use, (e.g: [Prism](https://prismjs.com/) vs [Highlight.js](https://highlightjs.org/)). We should leave these choices open to the user. For Docusaurus 2, **users can eject and choose their own Markdown parser**. It does not matter if they want to use another Markdown parser such as [Remark](https://github.com/remarkjs/remark), or even their own in-house Markdown parser. As a rule of thumb, the user has to provide a React component, in which we will provide a children props containing the _RAW string of Markdown_. By default, we will use Remarkable for the Markdown parser and Highlight.js for the syntax highlighting. The default parser could still change in the future as we're still experimenting with different Markdown parsers. -### Search +### Search {/* #search */} Our core search functionality is based on [Algolia](https://www.algolia.com/). There are requests by users to be able to use different search offerings, such as `lunrjs` for offline search. @@ -100,15 +100,15 @@ I personally like Algolia and we have a great experience working with them. They For Docusaurus 2, **we will allow users to customize the search box**. Users simply need to eject from the default theme and modify the Search UI (a React component). However, we will still use Algolia in the default theme. -## Stability +## Stability {/* #stability */} Software is never going to be perfect, but we want Docusaurus to not break as we add new features. When Docusaurus was first released, it did not have any strong automated test suites. As a result, there were a lot of regressions not caught early. Although we have recently added a lot of tests, the test coverage is still relatively low. For Docusaurus 2, **we are adding tests as we develop** since we are going for a fresh rewrite. Hence, I believe that it should be more stable than ever and it should be harder to break things compared to Docusaurus 1. -## Frequently Asked Questions +## Frequently Asked Questions {/* #frequently-asked-questions */} -### Will there be any breaking changes? +### Will there be any breaking changes? {/* #will-there-be-any-breaking-changes */} If you've read the post up until to this point, you should be able to notice that there will be breaking changes. While we will try to **minimize the number of breaking changes** and make it backward compatible as much as possible, we believe that some breaking changes are required. This is mostly due to Docusaurus 2 being a **major rewrite and re-architecting** of the codebase. @@ -116,7 +116,7 @@ The exact list of breaking changes is not totally known yet as development is no Our goal is that most sites should be able to upgrade to Docusaurus 2 without a lot of pain. We will also include a migration guide when we release Docusaurus 2. When the times come, feel free to ping us on [Discord](https://discord.gg/docusaurus) or [X](https://x.com/docusaurus) for questions and help. -### When is the release of Docusaurus 2? +### When is the release of Docusaurus 2? {/* #when-is-the-release-of-docusaurus-2 */} As of now, we do not have an exact date planned for the release. I personally estimate that we might be able to release an alpha version in the next one to two months, but this is, of course, just an estimate. @@ -124,7 +124,7 @@ One thing that I would like to share is that while Docusaurus is part of [Facebo For now, the actual Docusaurus 2 work is still hosted in a private repository. In the near future, we will move them into the [public repository](https://github.com/facebook/docusaurus). When that time arrives, I encourage everyone to look into it and hopefully contribute in some way. Before then, please stay tuned 😉! -## Final Thoughts +## Final Thoughts {/* #final-thoughts */} Docusaurus has had a large impact on the open source community as seen from the [many popular projects](https://v1.docusaurus.io/en/users) which use Docusaurus for documentation. In order to move faster in the future, we are taking the opportunity to fix some core problems with Docusaurus 1 and striving to make Docusaurus better for everyone. In fact, it is safe to say that Docusaurus 2 is not just a plan any longer; the work on it has started and, hopefully, we will be able to see it materialize in the near future. diff --git a/website/blog/2018/12-14-Happy-First-Birthday-Slash.mdx b/website/blog/2018/12-14-Happy-First-Birthday-Slash.mdx index c21e087341ff..f5a3fafce75f 100644 --- a/website/blog/2018/12-14-Happy-First-Birthday-Slash.mdx +++ b/website/blog/2018/12-14-Happy-First-Birthday-Slash.mdx @@ -10,7 +10,7 @@ tags: [birth] Docusaurus [went live](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus) on December 14, 2017. At the time, we had [8 early adopters](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus#acknowledgements). - +{/* truncate */} We now have nearly [60 known users of Docusaurus](https://v1.docusaurus.io/en/users), and probably more that we don't know about. We have [9K GitHub stars](https://github.com/facebook/docusaurus) and an active community, particularly [Yangshun Tay](https://x.com/yangshunz) and [Endilie Yacop Sucipto](https://x.com/endiliey), both of whom are the lead maintainers helping keep this project [moving forward](https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2). diff --git a/website/blog/2019/12-30-docusaurus-2019-recap.mdx b/website/blog/2019/12-30-docusaurus-2019-recap.mdx index 709f28702c58..25a2a78b1dad 100644 --- a/website/blog/2019/12-30-docusaurus-2019-recap.mdx +++ b/website/blog/2019/12-30-docusaurus-2019-recap.mdx @@ -6,9 +6,9 @@ tags: [recap] 2019 was a great year for Docusaurus - we've made tremendous progress on [Docusaurus 2](https://docusaurus.io/). Current Docusaurus 1 users who aren't using the translations feature can feel free to check it out and [migrate](https://docusaurus.io/docs/migration) to it! Otherwise we will work with you to make that happen in 2020 :) - +{/* truncate */} -## Docusaurus 2 (D2) +## Docusaurus 2 (D2) {/* #docusaurus-2-d2 */} In 2018, we proposed to rebuild [Docusaurus from the ground up](https://github.com/facebook/docusaurus/issues/789). It involved a major rearchitecture effort - we created a content-centric CSS framework from scratch, a plugins system, and moved from static HTML pages to be a single page-app with prerendered routes. It was a wild adventure and a tough feat, especially with no dedicated FTE working on the project. With the help of [@endilie](https://github.com/endiliey), our ex-intern-turned-contributor-turned-maintainer, we made really good progress on D2 and are currently on version 2.0.0-alpha.40. All features in Docusaurus 1 except for translations have been ported over. @@ -16,7 +16,7 @@ D2's killer features are **Dark Mode** and its **superb performance**. D2 has da Last but not least, we implemented a plugins architecture and turned the repo into a [Lerna monorepo](https://github.com/facebook/docusaurus/tree/main/packages). We believe this plugin architecture will be helpful towards building a community and also allowing users to build their own features for their unique use cases. -## GitHub Activity +## GitHub Activity {/* #github-activity */} - Stars: 10050 → 14632 (+45.6% y/y) - Total Contributors: 182 → 303 (+66.4% y/y). Most of which are non-Facebook contributors @@ -24,7 +24,7 @@ Last but not least, we implemented a plugins architecture and turned the repo in - D1 is currently used by 3872 projects on GitHub while D2 is used by 247 projects on GitHub - We now have 4 active core contributors! (+100% y/y) -## Notable Users +## Notable Users {/* #notable-users */} A good portion of the projects within the Open Source community use Docusaurus. This half we also onboarded more notable projects onto Docusaurus 2: @@ -40,11 +40,11 @@ And welcomed more projects to Docusaurus 1: - [Immer](https://immerjs.github.io/immer/) - [Sorbet](https://sorbet.org/) -## Media +## Media {/* #media */} Yangshun gave a classroom session during F8 about [Using Docusaurus to Create Open Source Websites](https://www.youtube.com/watch?v=QcGJsf6mgZE). -## Community +## Community {/* #community */} A few third-party hosting/development services also has first-class integration with a Docusaurus setup: @@ -52,7 +52,7 @@ A few third-party hosting/development services also has first-class integration - [CodeSandbox](https://codesandbox.io/s/docusaurus-template-x3vg9) - [Render](https://render.com/docs/deploy-docusaurus) -## Looking Ahead +## Looking Ahead {/* #looking-ahead */} D2 has gained some traction among the [developer community](https://docusaurus.io/showcase). In 2020, we want to achieve full feature parity with D1 by the first half and help the remaining Facebook projects on D1 move to D2. It would also be great if we could use Docusaurus for internal documentation, but that is a non-trivial undertaking. If you have a need for it or have some ideas, come speak with us! diff --git a/website/blog/2020/01-07-tribute-to-endi.mdx b/website/blog/2020/01-07-tribute-to-endi.mdx index 619ecc8b7f51..72e5563ee789 100644 --- a/website/blog/2020/01-07-tribute-to-endi.mdx +++ b/website/blog/2020/01-07-tribute-to-endi.mdx @@ -6,7 +6,7 @@ tags: [endi, tribute] It is with great sadness to announce that our primary external Docusaurus contributor, [Endilie Yacop Sucipto](https://github.com/endiliey) (Endi to those who knew him), [passed away](https://give.asia/campaign/help_endi_beat_cancer#/updates) over the weekend after an illness associated with his bout with cancer. - +{/* truncate */} It is impossible to overstate Endi's impact on this project: diff --git a/website/blog/2021/01-19-docusaurus-2020-recap.mdx b/website/blog/2021/01-19-docusaurus-2020-recap.mdx index a881fe9d6b95..ed13bfb5f6fc 100644 --- a/website/blog/2021/01-19-docusaurus-2020-recap.mdx +++ b/website/blog/2021/01-19-docusaurus-2020-recap.mdx @@ -15,9 +15,9 @@ We are **still in alpha**, but expect **some good news very soon**! ![Three Docusaurus plushies laid side-by-side on the table](/img/blog/2020-recap/docusaurus-plushie-banner.jpeg) - +{/* truncate */} -## Docusaurus 2 highlights +## Docusaurus 2 highlights {/* #docusaurus-2-highlights */} We have worked on many features this year, and would like to highlight the most significant ones: @@ -36,7 +36,7 @@ We have worked on many features this year, and would like to highlight the most - **TypeScript**: progressive adoption for internal code, and improve usage for users - **Publish Infima**: it is now [open-source](https://github.com/facebookincubator/infima) -## Docusaurus 2 growth +## Docusaurus 2 growth {/* #docusaurus-2-growth */} The plan to [rebuild Docusaurus from scratch in 2019](https://docusaurus.io/blog/2019/12/30/docusaurus-2019-recap) paid off: after a slow start, Docusaurus 2 has been widely adopted and has **already outgrown Docusaurus 1** usage. @@ -67,14 +67,14 @@ We also saw the **[first right-to-left](https://datagit.ir/)** Docusaurus 2 site ![Datagit's website in Persian, a right-to-left language. The sidebar appears on the right of the window and the TOC appears on the left.](/img/blog/2020-recap/datagit-rtl-screenshot.png) -## GitHub Activity +## GitHub Activity {/* #github-activity */} - **Stars**: 14632 → 20946 (+43.2% y/y) - **Total Contributors**: 303 → 512 (+68.9% y/y). Most of which are non-Facebook contributors - **Weekly npm Downloads**: 2356 → 25592 (+986% y/y) - **On GitHub**, Docusaurus 1 is used by 6311 projects (+62.9% y/y) while Docusaurus 2 is used by 5039 projects (+1940% y/y) -## Collaboration with Major League Hacking +## Collaboration with Major League Hacking {/* #collaboration-with-major-league-hacking */} We have welcomed [Major League Hacking](https://mlh.io/) (MLH) fellows for 2 seasons already. @@ -88,7 +88,7 @@ We are very thankful for the **various contributions** they made, such as: We look forward to continuing this collaboration in 2021. -## Media +## Media {/* #media */} Dmitry Vinnik (Developer Advocate @ Facebook) explains Docusaurus in [60 seconds](https://www.youtube.com/watch?v=_An9EsKPhp0) or [15min](https://www.youtube.com/watch?v=Yhyx7otSksg) videos. @@ -103,13 +103,13 @@ Many blog posts have been published: - [Easy documentation with Docusaurus](https://blog.logrocket.com/easy-documentation-with-docusaurus/) by Anshul Goyal (MLH fellow) - [Build Beautiful Documentation Websites with Docusaurus](https://lo-victoria.com/build-beautiful-documentation-websites-with-docusaurus) by Victoria Lo -## Community +## Community {/* #community */} The Docusaurus community continues to grow, the [Discord](https://discord.gg/docusaurus) server is quite active, and [Stack Overflow questions](https://stackoverflow.com/questions/tagged/docusaurus) keep being posted. The **modular architecture** of Docusaurus 2 allowed the community to build and publish [third-party plugins](https://docusaurus.io/community/resources#community-plugins-). As we would like to federate better our community, if you are building a plugin, please [let us know](https://github.com/facebook/docusaurus/discussions/4025). -## What's next? +## What's next? {/* #whats-next */} As 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**. diff --git a/website/blog/2021/03-09-releasing-docusaurus-i18n.mdx b/website/blog/2021/03-09-releasing-docusaurus-i18n.mdx index 87cb8117c325..3853dd924133 100644 --- a/website/blog/2021/03-09-releasing-docusaurus-i18n.mdx +++ b/website/blog/2021/03-09-releasing-docusaurus-i18n.mdx @@ -15,9 +15,9 @@ In this post, we will present you the **translation workflow**, explain some **d We also **dogfood** the i18n support on the **Docusaurus 2 site itself**, and this post is already available in [English](https://docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n) and [French](https://docusaurus.io/fr/blog/2021/03/09/releasing-docusaurus-i18n)! - +{/* truncate */} -## Translate your site +## Translate your site {/* #translate-your-site */} You can translate a Docusaurus site in **3 simple steps**: @@ -29,7 +29,7 @@ The i18n support is **very flexible** and based on the **filesystem**. The **[i18n tutorial](https://docusaurus.io/docs/i18n/tutorial)** is the best way to get started, and we provide help to use **[Git](https://docusaurus.io/docs/i18n/git)** or **[Crowdin](https://docusaurus.io/docs/i18n/crowdin)**. -## Design decisions +## Design decisions {/* #design-decisions */} The goals of the Docusaurus i18n system are: @@ -46,11 +46,11 @@ The goals of the Docusaurus i18n system are: - **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement - **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales) -## Showcase +## Showcase {/* #showcase */} We worked with a few volunteers to **dogfood the i18n support** before releasing it. -### Jest: upgrading Docusaurus +### Jest: upgrading Docusaurus {/* #jest-upgrading-docusaurus */} We have made it possible to **upgrade** a **translated Docusaurus 1 site** to Docusaurus 2. @@ -60,7 +60,7 @@ The Docusaurus 2 migration was successful and the new site is now deployed in pr [![Jest's website front page in Japanese](/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png)](https://jestjs.io) -### Redwood: adopting Docusaurus +### Redwood: adopting Docusaurus {/* #redwood-adopting-docusaurus */} [Redwood](https://redwoodjs.com/) is a React full-stack Jamstack framework. @@ -68,7 +68,7 @@ They were looking for a solution to create an **internationalized learning platf [![Redwood's doc page in French](/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png)](https://learn.redwoodjs.com/) -### Datagit: using LTR support +### Datagit: using LTR support {/* #datagit-using-ltr-support */} The i18n system should work with any language, including **Right-to-Left languages**. @@ -76,7 +76,7 @@ The i18n system should work with any language, including **Right-to-Left languag [![Datagit's website in Persian, a right-to-left language. The sidebar appears on the right of the window and the TOC appears on the left.](/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png)](https://datagit.ir/) -## Conclusion +## Conclusion {/* #conclusion */} We sincerely hope you will adopt and like the new i18n support. diff --git a/website/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx b/website/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx index a6f4b6abcc03..f69baa8195e7 100644 --- a/website/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx +++ b/website/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx @@ -17,9 +17,9 @@ With the announcement of this beta, the team is even more confident that Docusau ![](./img/image_cropped.png) - +{/* truncate */} -## Docusaurus adoption +## Docusaurus adoption {/* #docusaurus-adoption */} **Don't fear the beta tag!** @@ -33,7 +33,7 @@ Don't miss our [favorite](https://docusaurus.io/showcase?tags=favorite) sites; t [![A screenshot of the showcase's favorites section, with 12 cards each displaying the information and preview of one site](./img/favorites.png)](https://docusaurus.io/showcase?tags=favorite) -## Why was Docusaurus v2 in alpha for so long? +## Why was Docusaurus v2 in alpha for so long? {/* #why-was-docusaurus-v2-in-alpha-for-so-long */} It's hard to believe that the first alpha release [v2.0.0-alpha.0](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.0) was 2 years ago 😳 , unusually long for a software alpha. @@ -41,7 +41,7 @@ As this was a substantial re-architecture of the code base, we wanted to ensure We're now quite confident that the core features of Docusaurus 2 are stable enough to be in beta. -## What are the goals of the beta? +## What are the goals of the beta? {/* #what-are-the-goals-of-the-beta */} Now 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. @@ -57,14 +57,14 @@ We will build a better **theming infrastructure** and refactor the classic theme If you customize your site, you may find these planned improvements quite valuable. -## What's new? +## What's new? {/* #whats-new */} In case you missed it, we recently shipped two major improvements: - [Auto-generated sidebars](https://docusaurus.io/docs/sidebar#sidebar-item-autogenerated): no need to maintain a `sidebars.js` file anymore! - [Webpack 5 / PostCSS 8](https://github.com/facebook/docusaurus/issues/4027): persistent caching significantly speeds up **rebuild time**! -## What's next? +## What's next? {/* #whats-next */} Shipping the official 2.0 release! @@ -80,7 +80,7 @@ To get there, we will continue to **fix bugs** and implement the **most wanted f - [Better compatibility with CommonMark](https://github.com/facebook/docusaurus/issues/3018) - [Upgrade to MDX 2.0](https://github.com/facebook/docusaurus/issues/4029) -## Conclusion +## Conclusion {/* #conclusion */} This is an exciting time for Docusaurus. diff --git a/website/blog/2021/11-21-algolia-docsearch-migration/index.mdx b/website/blog/2021/11-21-algolia-docsearch-migration/index.mdx index 0c169bd357c4..17f289d4b09c 100644 --- a/website/blog/2021/11-21-algolia-docsearch-migration/index.mdx +++ b/website/blog/2021/11-21-algolia-docsearch-migration/index.mdx @@ -9,9 +9,9 @@ image: ./img/social-card.png Docusaurus 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. - +{/* truncate */} -## Upgrading your Docusaurus site +## Upgrading your Docusaurus site {/* #upgrading-your-docusaurus-site */} In the next few weeks, Docusaurus site owners will receive an email inviting them to join their personal Algolia application. @@ -45,21 +45,21 @@ These keys are not secrets and can be added to your Git repository. ::: -## DocSearch has a new home! +## DocSearch has a new home! {/* #docsearch-has-a-new-home */} -### What is DocSearch? +### What is DocSearch? {/* #what-is-docsearch */} [DocSearch](https://docsearch.algolia.com/) is a program created by [Algolia](http://algolia.com/), which offers search to technical documentation of Open Source projects and technical blogs **for free**. You can [read more here](https://docsearch.algolia.com/docs/what-is-docsearch/), and [apply](https://docsearch.algolia.com/apply) if you'd like to give it a try! -## What is this migration about? +## What is this migration about? {/* #what-is-this-migration-about */} -### Motivation +### Motivation {/* #motivation */} With the upcoming stable release of [DocSearch UI](https://docsearch.algolia.com/docs/DocSearch-v3), we wanted to go further and provide better tooling for our users to improve their search, but also leverage the full potential of Algolia. -### What's new? +### What's new? {/* #whats-new */} DocSearch now leverages the [Algolia Crawler](https://www.algolia.com/products/search-and-discovery/crawler/), which includes a web interface that will allow you to: @@ -83,25 +83,25 @@ But also, more Algolia features in **your own Algolia app**: And of course, **a lot more, for free**. -## FAQ +## FAQ {/* #faq */} -### I'm using Docusaurus and DocSearch, can I migrate? {#im-using-docusaurus-and-docsearch-can-i-migrate} +### I'm using Docusaurus and DocSearch, can I migrate? {/* #im-using-docusaurus-and-docsearch-can-i-migrate */} At 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! -### Where can I read more about this? +### Where can I read more about this? {/* #where-can-i-read-more-about-this */} We wrote a small [migration guide](https://docsearch.algolia.com/docs/migrating-from-legacy) but you'll have more detailed information in the migration email. -### I received the migration email but the invite expired +### I received the migration email but the invite expired {/* #i-received-the-migration-email-but-the-invite-expired */} Please contact us via either [email](mailto:docsearch@algolia.com) or [DocSearch's Discord](https://discord.gg/bRTacwYrfX) or on [Docusaurus's Discord #algolia channel](https://discordapp.com/invite/docusaurus) -### I have feedback! +### I have feedback! {/* #i-have-feedback */} For any feedback regarding our documentation or the DocSearch UI component, you can open an issue [on our GitHub repository](https://github.com/algolia/docsearch/issues), but also contact us via the methods above. -### Can I still run my own DocSearch instance? +### Can I still run my own DocSearch instance? {/* #can-i-still-run-my-own-docsearch-instance */} In favor of the new infrastructure and DocSearch v3, we will no longer maintain our beloved [DocSearch scraper](https://github.com/algolia/docsearch-scraper) and [DocSearch v2](https://github.com/algolia/docsearch/tree/master), but the repositories will still be available and open to pull requests. diff --git a/website/blog/2022/01-24-docusaurus-2021-recap/index.mdx b/website/blog/2022/01-24-docusaurus-2021-recap/index.mdx index d6fe0da86104..7c2f01f16980 100644 --- a/website/blog/2022/01-24-docusaurus-2021-recap/index.mdx +++ b/website/blog/2022/01-24-docusaurus-2021-recap/index.mdx @@ -13,9 +13,9 @@ The **official v2 release** is just around the corner! Follow the [roadmap issue ![](./img/thumbnail.png) - +{/* truncate */} -## Highlights +## Highlights {/* #highlights */} Let's begin by going over a few highlights this year. Remember the [todo-list](/blog/2021/05-12-announcing-docusaurus-two-beta/index.mdx#whats-next) from half a year ago? Time to take it out again and see how far we've come! @@ -32,9 +32,9 @@ Let's begin by going over a few highlights this year. Remember the [todo-list](/ Our 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%! -## Trends +## Trends {/* #trends */} -### npm +### npm {/* #npm */} Docusaurus 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. @@ -44,7 +44,7 @@ Docusaurus v2 continues to grow steadily. V2 installation is now 8 times more th We released 18 versions, going from `2.0.0-alpha.71` to `2.0.0-beta.14`. That's one release every 20 days! -### GitHub +### GitHub {/* #github */} - **Stars**: 20,460 → 29,679 (+45.1% y/y). And, just before this blog post is published, we have reached 30k stars! - **Total contributors**: 512 → 773 (+51.0% y/y) @@ -61,7 +61,7 @@ With an 8.4k increase in stars, we are ranked number 3 in this year's [JavaScrip ![Docusaurus placing 3rd in the "Static Sites" ranking list](./img/rising-stars.png) -## Featured adoptions +## Featured adoptions {/* #featured-adoptions */} Our showcase has welcomed a few new ["favorite" sites](/showcase?tags=favorite) that showcase the true potential of Docusaurus 2's pluggable architecture. @@ -83,7 +83,7 @@ Our showcase has welcomed a few new ["favorite" sites](/showcase?tags=favorite) 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](https://github.com/facebook/docusaurus/edit/main/website/src/data/users.tsx). -## Community +## Community {/* #community */} As an active moderator on [Discord](https://discord.gg/docusaurus), I can clearly see the community thriving. Many frequently asked questions are now integrated into our documentation, and some feature requests have been implemented as well. The project and the community reciprocally benefit each other – case in point, I was formerly a community contributor before becoming a maintainer. @@ -99,7 +99,7 @@ And we keep every one of them in [our little box](https://x.com/sebastienlorber/ As we approach the official release, we are interested in knowing more about what people are doing out there: [plugin authors](https://github.com/facebook/docusaurus/discussions/4025), [creators of customized sites](https://github.com/facebook/docusaurus/discussions/5468), and [all new users](https://github.com/facebook/docusaurus/discussions/4610) – please keep us posted about your achievements so we can steer our development to better serve your needs. -## Going forward +## Going forward {/* #going-forward */} In the past few months, we have been constantly speaking about the release-candidate phase of Docusaurus, and yes, it's almost there. We have created a dedicated [milestone](https://github.com/facebook/docusaurus/milestone/15) to keep track of all issues to solve before we can confidently progress to the next stage. In short, we want to build a **more robust theming workflow**, empowering creative site creators to customize our default theme without fearing breaking changes as they upgrade. This will include: diff --git a/website/blog/2022/08-01-announcing-docusaurus-2.0/index.mdx b/website/blog/2022/08-01-announcing-docusaurus-2.0/index.mdx index 70b669609afa..af71d6215861 100644 --- a/website/blog/2022/08-01-announcing-docusaurus-2.0/index.mdx +++ b/website/blog/2022/08-01-announcing-docusaurus-2.0/index.mdx @@ -51,7 +51,7 @@ In a hurry? Check [what's new in Docusaurus 2.0](#whats-new-in-20)! ::: -## What is Docusaurus exactly? +## What is Docusaurus exactly? {/* #what-is-docusaurus-exactly */} Docusaurus is a **static site generator** that helps you ship **beautiful documentation websites** in **no time**. @@ -89,7 +89,7 @@ Try Docusaurus now with our [online playgrounds](/docs/playground) and [5 minute ::: -## The story behind Docusaurus +## The story behind Docusaurus {/* #the-story-behind-docusaurus */} Docusaurus was created at **Facebook Open Source** in **2017** (now [Meta Open Source](https://opensource.fb.com/)). We had a lot of internal and open source projects to document. It's **complicated enough to write good documentation**, let alone to create the HTML, CSS, and JavaScript for a good-looking website. We wanted project leaders to be able to **focus on the content**, and **Markdown** is great for that. @@ -111,7 +111,7 @@ Notice that the sample sites above use different colors, but still look quite th ::: -## Toward Docusaurus 2.0 +## Toward Docusaurus 2.0 {/* #toward-docusaurus-20 */} [**Docusaurus v1**](http://v1.docusaurus.io/) has been very successful, but we started to **question some architectural choices**: @@ -131,7 +131,7 @@ Notice that the sample sites above use different colors, but still look quite th More details in the [Docusaurus 2 project announcement](/blog/2018/09-11-Towards-Docusaurus-2.mdx) and [v1 to v2 migration guide](https://docusaurus.io/docs/migration) -## Who uses Docusaurus 2.0? +## Who uses Docusaurus 2.0? {/* #who-uses-docusaurus-20 */} Despite being in pre-release, it didn't take long for **Docusaurus v2 to outgrow Docusaurus v1** in terms of NPM downloads: @@ -190,11 +190,11 @@ Please add your site to our [site showcase](/showcase)! It only takes a few seco Docusaurus is awesome. We use it -## What's New in 2.0? +## What's New in 2.0? {/* #whats-new-in-20 */} 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**. -### MDX +### MDX {/* #mdx */} [MDX](https://github.com/mdx-js/mdx) allows you to **interleave React components** in Markdown. This enables you to build top-notch **interactive documentation experiences** very easily. @@ -234,7 +234,7 @@ MDX has its own [plugin system](https://mdxjs.com/docs/extending-mdx/). You to c corresponding prose. -### File system conventions +### File system conventions {/* #file-system-conventions */} 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. @@ -257,7 +257,7 @@ Our goal is to make Docusaurus very **intuitive** to use. We added file system c not worry about any other configuration. -### Plugins +### Plugins {/* #plugins */} 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. @@ -301,7 +301,7 @@ We have a curated list of outstanding plugins in our [community resources](/comm portal so easy and fun. Super excited to show you what we've got cooking up. -### Theming +### Theming {/* #theming */} 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. @@ -336,7 +336,7 @@ This enables users willing to invest a bit more time on **customizations** to bu way that we wanted it to look. No blockers at all. -### Other features +### Other features {/* #other-features */} Docusaurus 2 comes with a very long list of useful features: @@ -367,7 +367,7 @@ Docusaurus 2 comes with a very long list of useful features: really customize the styling if you're braver than I am. -## Why 2.0 now? +## Why 2.0 now? {/* #why-20-now */} 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**. @@ -392,7 +392,7 @@ Check our [release process](/community/release-process) documentation for detail ::: -## What's Next? +## What's Next? {/* #whats-next */} ![Slash Up and Running](/img/slash-up-and-running.png) @@ -412,7 +412,7 @@ A sample of the features on our roadmap for the upcoming major versions of Docus - [Improve build time performance](https://github.com/facebook/docusaurus/issues/4765) - [Extend Docusaurus plugins, CMS integration](https://github.com/facebook/docusaurus/issues/4138) -## Thank You +## Thank You {/* #thank-you */} We'd like to express our gratitude to [all our contributors](https://github.com/facebook/docusaurus/graphs/contributors), including: diff --git a/website/blog/2022/09-01-docusaurus-2.1/index.mdx b/website/blog/2022/09-01-docusaurus-2.1/index.mdx index 6ccb1ea7d675..0c41a26b0d8d 100644 --- a/website/blog/2022/09-01-docusaurus-2.1/index.mdx +++ b/website/blog/2022/09-01-docusaurus-2.1/index.mdx @@ -12,11 +12,11 @@ The upgrade should be easy: as explained in our [release process documentation]( ![Docusaurus 2.1 social card](./img/social-card.png) - +{/* truncate */} -## Highlights +## Highlights {/* #highlights */} -### DocCardList improvements +### DocCardList improvements {/* #doccardlist-improvements */} In [#8008](https://github.com/facebook/docusaurus/pull/8008), we simplified the usage of the`` component, that is notably used on sidebar category generated index pages. @@ -34,7 +34,7 @@ Also, we made it possible to use it on any document, including regular docs not ![simplified DocCardList component](./img/doc-card-list.png) -### `noindex` improvements +### `noindex` improvements {/* #noindex-improvements */} We improved the support of the [`noindex` meta `robots` directive](https://developers.google.com/search/docs/advanced/crawling/block-indexing), a way to signal search engines you don't want a specific page to be indexed. @@ -60,7 +60,7 @@ In practice, Docusaurus will add the following meta to each page of that version In [#7964](https://github.com/facebook/docusaurus/pull/7964), we also fixed a bug where the sitemap plugin would still contain pages that have a `noindex` directive. Now the sitemap plugin will reliably filter out all the pages containing `noindex` directives. -### Overriding default meta tags +### Overriding default meta tags {/* #overriding-default-meta-tags */} In [#7952](https://github.com/facebook/docusaurus/pull/7952), it becomes possible to override default html meta tags you couldn't before: @@ -76,10 +76,10 @@ It is now possible to use `` or `themeConfig.metadata`: - to override the `viewport` meta - to override the `robots` meta: you could mark your site as `noIndex`, but except for specific pages that should be indexed -### Ukrainian translations +### Ukrainian translations {/* #ukrainian-translations */} In [#7953](https://github.com/facebook/docusaurus/pull/7953), we added default classic theme translations for the Ukrainian language. -## Other changes +## Other changes {/* #other-changes */} Check the [2.1.0 changelog entry](/changelog/2.1.0) for an exhaustive list of changes. diff --git a/website/blog/2023/09-22-upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing/index.mdx b/website/blog/2023/09-22-upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing/index.mdx index 39d56b64ed22..a3150591c880 100644 --- a/website/blog/2023/09-22-upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing/index.mdx +++ b/website/blog/2023/09-22-upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing/index.mdx @@ -17,13 +17,13 @@ This article introduces a **visual regression testing** workflow based on [**Git ![Upgrading frontend dependencies with confidence - social card](./img/social-card.png) - +{/* truncate */} 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](https://reactnative.dev/), [Jest](https://jestjs.io/), and the [Docusaurus](https://docusaurus.io/) site itself. Docusaurus v3 comes with infrastructure changes and major dependency upgrades such as [MDX v3](https://mdxjs.com/blog/v3/) and [React 18](https://react.dev/blog/2022/03/29/react-v18), which can produce unexpected side effects. It would have been difficult to notice all the visual regressions without such a workflow. That's why we encourage site owners to consider adopting visual regression testing, especially for highly customized sites. -## Workflow overview +## Workflow overview {/* #workflow-overview */} The general idea is pretty simple: @@ -47,13 +47,13 @@ Here is a more concrete example of Argos [reporting a visual regression](https:/ [![Argos GitHub PR comment](./img/argos-react-native-regression.png)](https://app.argos-ci.com/slorber/rnw-visual-tests/builds/32/56012838) -## Workflow implementation +## Workflow implementation {/* #workflow-implementation */} This section will describe the implementation details of each step of the workflow. You will need to [sign up to Argos](https://app.argos-ci.com/signup) and [connect Argos to your GitHub repository](https://argos-ci.com/docs/github) -### Dependencies +### Dependencies {/* #dependencies */} This workflow requires the following dev dependencies, in addition to the usual Docusaurus ones: @@ -61,7 +61,7 @@ This workflow requires the following dev dependencies, in addition to the usual yarn add -D @argos-ci/cli @argos-ci/playwright @playwright/test cheerio ``` -### GitHub Action +### GitHub Action {/* #github-action */} The GitHub action is responsible for executing the workflow for each Git branch. @@ -104,7 +104,7 @@ jobs: run: yarn argos upload ./screenshots ``` -### Playwright config +### Playwright config {/* #playwright-config */} Playwright is responsible for taking screenshots of the website previously built locally by the GitHub action. @@ -132,7 +132,7 @@ const config: PlaywrightTestConfig = { export default config; ``` -### Playwright test +### Playwright test {/* #playwright-test */} A Playwright config is not enough: we also need to write a Playwright test file to generate the site screenshots. @@ -208,7 +208,7 @@ export function pathnameToArgosName(pathname: string): string { -### Stylesheet +### Stylesheet {/* #stylesheet */} 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. @@ -244,7 +244,7 @@ For example, the docs "Last Updated on" might render on more than 1 line, eventu ::: -## Example repository +## Example repository {/* #example-repository */} The [slorber/docusaurus-argos-example](https://github.com/slorber/docusaurus-argos-example) repo shows a complete example of implementing this workflow on a newly initialized Docusaurus v2 site, using a Yarn monorepo. @@ -264,7 +264,7 @@ Browse the Docusaurus repository for a more advanced integration: ::: -## Make it cheap +## Make it cheap {/* #make-it-cheap */} The tools we choose are implementation details of this visual regression testing workflow. @@ -274,7 +274,7 @@ In case you don't mind storing large screenshots in Git, you can also try the fr 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. -### Limit the number of pathnames +### Limit the number of pathnames {/* #limit-the-number-of-pathnames */} The 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. @@ -298,7 +298,7 @@ test.describe('Docusaurus site screenshots', () => { }); ``` -### Limit the workflow concurrency +### Limit the workflow concurrency {/* #limit-the-workflow-concurrency */} Implementing [GitHub Actions concurrency groups](https://docs.github.com/en/actions/using-jobs/using-concurrency) will prevent successive commits to trigger multiple useless workflow runs. The workflow will only be executed for the last commit, and previous commits will be canceled automatically. @@ -308,7 +308,7 @@ concurrency: cancel-in-progress: true ``` -### Run your workflow conditionally +### Run your workflow conditionally {/* #run-your-workflow-conditionally */} It's not worth running this workflow for every single commit and pull-request. @@ -344,7 +344,7 @@ jobs: There are many options to explore, such as [triggering the workflow manually](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow) or [only when files matching a specific pattern are modified](https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#example-including-paths). -## Conclusion +## Conclusion {/* #conclusion */} I believe **visual regression testing is underused** in the frontend ecosystem. @@ -354,7 +354,7 @@ So why not give it a try? Happy hacking! -## See also +## See also {/* #see-also */} Useful documentation links: diff --git a/website/blog/2023/09-29-preparing-your-site-for-docusaurus-v3/index.mdx b/website/blog/2023/09-29-preparing-your-site-for-docusaurus-v3/index.mdx index 740a11eec476..bd76b9081241 100644 --- a/website/blog/2023/09-29-preparing-your-site-for-docusaurus-v3/index.mdx +++ b/website/blog/2023/09-29-preparing-your-site-for-docusaurus-v3/index.mdx @@ -23,7 +23,7 @@ This article will mostly focus on how to prepare your content for this new MDX v ![Preparing your site for Docusaurus v3 - social card](./img/social-card.png) - +{/* truncate */} :::warning @@ -39,7 +39,7 @@ If your site is relatively small, with only a few customizations, you can probab ::: -## Preparatory work +## Preparatory work {/* #preparatory-work */} Before preparing for the Docusaurus v3 upgrade, we recommend upgrading to the latest [Docusaurus v2 version](/versions). @@ -47,7 +47,7 @@ Depending on the complexity of your site, it may be a good idea to adopt the [vi We also recommend using the `.mdx` extension whenever you use JSX, `import`, or `export` (i.e. MDX features) inside a Markdown file. It is semantically more correct and improves compatibility with external tools (IDEs, formatters, linters, etc.). In future versions of Docusaurus, `.md` files will be parsed as standard [CommonMark](https://commonmark.org/), which does not support these features. In Docusaurus v3, `.md` files keep being compiled as MDX files, but it will be possible to [opt-in for CommonMark](https://github.com/facebook/docusaurus/issues/3018). -## Preparing content for MDX v3 +## Preparing content for MDX v3 {/* #preparing-content-for-mdx-v3 */} MDX is a major dependency of Docusaurus responsible for compiling your `.md` and `.mdx` files to React components. @@ -63,7 +63,7 @@ We have a dedicated [MDX v3 - Upgrade Support](https://github.com/facebook/docus ::: -### Using the MDX playground +### Using the MDX playground {/* #using-the-mdx-playground */} 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. @@ -93,7 +93,7 @@ The goal will be to refactor your problematic content so that it **works fine wi ::: -### Using the MDX checker CLI +### Using the MDX checker CLI {/* #using-the-mdx-checker-cli */} We provide a [docusaurus-mdx-checker](https://github.com/slorber/docusaurus-mdx-checker) CLI that permits to easily spot problematic content. Run this command today on your Docusaurus v2 site to obtain a list of files that will fail to compile under MDX v3. @@ -119,7 +119,7 @@ It will not report subtle compilation changes that do not produce errors but can ::: -### Common MDX problems +### Common MDX problems {/* #common-mdx-problems */} We upgraded a few Docusaurus sites to Docusaurus v3 and MDX v3: @@ -129,7 +129,7 @@ We upgraded a few Docusaurus sites to Docusaurus v3 and MDX v3: These upgrades permitted us to aggregate the most common content problems, and document how to best handle them. -#### Bad usage of `{` +#### Bad usage of `{` {/* #bad-usage-of- */} The `{` character is used for opening [JavaScript expressions](https://mdxjs.com/docs/what-is-mdx/#expressions). MDX will now fail if what you put inside `{expression}` is not a valid expression. @@ -153,7 +153,7 @@ Available options to fix this error: ::: -#### Bad usage of `<` +#### Bad usage of `<` {/* #bad-usage-of--1 */} The `<` character is used for opening [JSX tags](https://mdxjs.com/docs/what-is-mdx/#jsx). MDX will now fail if it thinks your JSX is invalid. @@ -185,7 +185,7 @@ Available options to fix this error: ::: -#### Bad usage of GFM Autolink +#### Bad usage of GFM Autolink {/* #bad-usage-of-gfm-autolink */} Docusaurus supports [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/), but [autolink](https://github.github.com/gfm/#autolinks) using the `` syntax is not supported anymore by MDX. @@ -218,7 +218,7 @@ http://localhost:3000 ::: -#### Lower-case MDXComponent mapping +#### Lower-case MDXComponent mapping {/* #lower-case-mdxcomponent-mapping */} For users providing a [custom `MDXComponent`mapping](/docs/markdown-features/react#mdx-component-scope), components are now "sandboxed": @@ -250,7 +250,7 @@ For any other element, **use upper-case names**. ::: -#### Unintended extra paragraphs +#### Unintended extra paragraphs {/* #unintended-extra-paragraphs */} 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 `

` tags. @@ -297,7 +297,7 @@ If your content contains "Markdown inlines" (`**`, `*`, `_`, `[link](/path)`), y ::: -#### Unintended usage of directives +#### Unintended usage of directives {/* #unintended-usage-of-directives */} Docusaurus v3 now uses [Markdown Directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) (implemented with [remark-directive](https://github.com/remarkjs/remark-directive)) as a generic way to provide support for admonitions, and other upcoming Docusaurus features. @@ -338,7 +338,7 @@ conf is great ::: -#### Unsupported indented code blocks +#### Unsupported indented code blocks {/* #unsupported-indented-code-blocks */} MDX does not transform indented text as code blocks anymore. @@ -364,7 +364,7 @@ console.log('hello'); ::: -### MDX plugins +### MDX plugins {/* #mdx-plugins */} All the official packages (Unified, Remark, Rehype...) in the MDX ecosystem are now [**ES Modules only**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and do not support [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) anymore. @@ -402,11 +402,11 @@ If you created custom Remark or Rehype plugins, you may need to refactor those, ::: -## Other breaking changes +## Other breaking changes {/* #other-breaking-changes */} Apart from MDX, there are other breaking changes that you can already prepare your site for, notably major version upgrades of important dependencies. -### Node.js 18.0 +### Node.js 18.0 {/* #nodejs-180 */} Node.js 16 [reached End-of-Life](https://nodejs.org/en/blog/announcements/nodejs16-eol), and Docusaurus v3 now requires **Node.js >= 18.0**. @@ -416,7 +416,7 @@ Upgrade your Docusaurus v2 site to Node.js 18 before upgrading to Docusaurus v3. ::: -### React 18.0 +### React 18.0 {/* #react-180 */} Docusaurus v3 now requires **React >= 18.0**. @@ -435,7 +435,7 @@ We recommend to particularly look for: ::: -### TypeScript 5.0 +### TypeScript 5.0 {/* #typescript-50 */} Docusaurus v3 now requires **TypeScript >= 5.0**. @@ -445,7 +445,7 @@ Upgrade your Docusaurus v2 site to TypeScript 5 before upgrading to Docusaurus v ::: -### TypeScript base config +### TypeScript base config {/* #typescript-base-config */} The official Docusaurus TypeScript config has been re-internalized from the external package [`@tsconfig/docusaurus`](https://www.npmjs.com/package/@tsconfig/docusaurus) to our new monorepo package [`@docusaurus/tsconfig`](https://www.npmjs.com/package/@docusaurus/tsconfig). @@ -476,7 +476,7 @@ The new Docusaurus v3 TypeScript config is sensibly the same as the former Docus ::: -### Admonition warning +### Admonition warning {/* #admonition-warning */} For historical reasons, we support an undocumented admonition `:::warning` that renders with a red color. @@ -502,7 +502,7 @@ Docusaurus v3 also [deprecated the `:::caution`](https://github.com/facebook/doc ::: -### Versioned sidebars +### Versioned sidebars {/* #versioned-sidebars */} This breaking change will only affect **Docusaurus v2 early adopters** who versioned their docs before `v2.0.0-beta.10` (December 2021). @@ -531,7 +531,7 @@ You can remove the useless versioned prefix from your versioned sidebars. ::: -## Try Docusaurus v3 today {#try-docusaurus-v3-today} +## Try Docusaurus v3 today {/* #try-docusaurus-v3-today */} Docusaurus v3 is now [in beta](https://github.com/facebook/docusaurus/discussions/9312), and already used in production by [React-Native](https://reactnative.dev), [Jest](https://jestjs.io), and [our own website](https://docusaurus.io/). @@ -564,7 +564,7 @@ For most sites, the upgrade should be easy. If you prepared your site ahead of t } ``` -## Ask for help +## Ask for help {/* #ask-for-help */} We will be there to help you upgrade through the following support channels: @@ -576,7 +576,7 @@ We will be there to help you upgrade through the following support channels: Alternatively, you can look for a paid [Docusaurus Service Provider](https://github.com/facebook/docusaurus/discussions/9281) to execute this upgrade for you. If your site is open source, you can also ask our community for [free, benevolent help](https://github.com/facebook/docusaurus/discussions/9283). -## Conclusion +## Conclusion {/* #conclusion */} Docusaurus v3 is ready to try, and will be released soon. This article already gives you a good idea of all the major changes required to upgrade. diff --git a/website/blog/releases/2.2/index.mdx b/website/blog/releases/2.2/index.mdx index f1ec204d6442..3661aa8d9fe0 100644 --- a/website/blog/releases/2.2/index.mdx +++ b/website/blog/releases/2.2/index.mdx @@ -14,9 +14,9 @@ The upgrade should be easy: as explained in our [release process documentation]( {/* truncate */} -## Highlights +## Highlights {/* #highlights */} -### Mermaid diagrams +### Mermaid diagrams {/* #mermaid-diagrams */} In [#7490](https://github.com/facebook/docusaurus/pull/7490), we added support for Mermaid diagrams. This fills the gap between GitHub Flavored Markdown which also [added support recently](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/). You can create Mermaid diagrams using Markdown code blocks: @@ -61,7 +61,7 @@ sequenceDiagram Make sure to check the [documentation](/docs/markdown-features/diagrams), and the [more advanced examples](/tests/pages/diagrams) -### Config `headTags` +### Config `headTags` {/* #config-headtags */} In [#8151](https://github.com/facebook/docusaurus/pull/8151), we added the ability to apply arbitrary HTML `` tags to all pages of your site. @@ -79,7 +79,7 @@ module.exports = { }; ``` -### Accessibility +### Accessibility {/* #accessibility */} We did several accessibility improvements: @@ -88,7 +88,7 @@ We did several accessibility improvements: - [#8204](https://github.com/facebook/docusaurus/pull/8204): makes the skip to content button support progressive enhancement - [#8174](https://github.com/facebook/docusaurus/pull/8174): improves screen reader announcement when toggling between light/dark mode -### Developer Experience +### Developer Experience {/* #developer-experience */} We made validation stricter and improved error messages: @@ -96,7 +96,7 @@ We made validation stricter and improved error messages: - [#8192](https://github.com/facebook/docusaurus/pull/8192) and [#8159](https://github.com/facebook/docusaurus/pull/8159): validates `siteConfig.url` more strictly and with better error message - [#8066](https://github.com/facebook/docusaurus/pull/8066): makes config `url` and `baseUrl` fail-safe and less sensitive to the presence or absence of a leading or trailing slash -### Translations +### Translations {/* #translations */} We completed the default theme translation support for multiple languages: @@ -111,7 +111,7 @@ Completing theme translations is an [ongoing effort](https://github.com/facebook ::: -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/2.3/index.mdx b/website/blog/releases/2.3/index.mdx index 2ce5005ae463..d5e3b53320cf 100644 --- a/website/blog/releases/2.3/index.mdx +++ b/website/blog/releases/2.3/index.mdx @@ -12,11 +12,11 @@ The upgrade should be easy: as explained in our [release process documentation]( ![Docusaurus 2.2 social card](./img/social-card.png) - +{/* truncate */} -## Highlights +## Highlights {/* #highlights */} -### Google Tag Manager plugin +### Google Tag Manager plugin {/* #google-tag-manager-plugin */} 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. @@ -30,7 +30,7 @@ Therefore, we are also **deprecating our existing [`@docusaurus/plugin-google-an ::: -### Tabs Query String Support +### Tabs Query String Support {/* #tabs-query-string-support */} 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. @@ -66,7 +66,7 @@ import TabItem from '@theme/TabItem'; -### Nested admonitions +### Nested admonitions {/* #nested-admonitions */} It is now possible to nest one admonition within another by adding extra colons for the outer/enclosing admonition: @@ -96,7 +96,7 @@ Use this sparingly when it makes sense. :::: -### Blog `createFeedItems` +### Blog `createFeedItems` {/* #blog-createfeeditems */} A new blog plugin option [`feedOptions.createFeedItems`](/docs/api/plugins/@docusaurus/plugin-content-blog/#CreateFeedItemsFn) gives you more control over the RSS/Atom feed generation. It is now possible to transform/filter/limit feed items through a new callback. @@ -122,7 +122,7 @@ A new blog plugin option [`feedOptions.createFeedItems`](/docs/api/plugins/@docu ]; ``` -### Translations +### Translations {/* #translations */} We added or completed the default theme translation support for multiple languages: @@ -140,7 +140,7 @@ Completing theme translations is an [ongoing effort](https://github.com/facebook ::: -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/2.4/index.mdx b/website/blog/releases/2.4/index.mdx index 7eeea9aabbf8..278fd6a3ec3c 100644 --- a/website/blog/releases/2.4/index.mdx +++ b/website/blog/releases/2.4/index.mdx @@ -12,15 +12,15 @@ The upgrade should be easy: as explained in our [release process documentation]( ![Docusaurus blog post social card](./img/social-card.png) - +{/* truncate */} import BrowserWindow from '@site/src/components/BrowserWindow'; import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow'; import ErrorBoundaryTestButton from '@site/src/components/ErrorBoundaryTestButton'; -## Highlights +## Highlights {/* #highlights */} -### Sidebar item description +### Sidebar item description {/* #sidebar-item-description */} In [#8236](https://github.com/facebook/docusaurus/pull/8236), we made it possible to provide a new `description` attribute for docs sidebar items of type `link` and `category`. @@ -47,7 +47,7 @@ These descriptions will be used in category generated index pages. ![Show sidebar category generated index with custom descriptions](./img/sidebar-item-description.jpg) -### Theme Query String +### Theme Query String {/* #theme-query-string */} In [#8708](https://github.com/facebook/docusaurus/pull/8708), we added the possibility to force Docusaurus to initialize itself in `light` or `dark` mode through a new `docusaurus-theme` query-string parameter. @@ -56,7 +56,7 @@ This is useful to ensure a consistent theme when embedding an existing Docusauru -### Remark plugin npm2yarn upgrade +### Remark plugin npm2yarn upgrade {/* #remark-plugin-npm2yarn-upgrade */} In [#8690](https://github.com/facebook/docusaurus/pull/8690), we upgraded our Remark plugin [@docusaurus/remark-plugin-npm2yarn](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-remark-plugin-npm2yarn) with many conversion bug fixes, first-class support for pnpm, and the ability to register custom converters producing new tabs. @@ -80,7 +80,7 @@ npm run myCustomScript -- --some-arg -### gtag support for multiple tracking IDs +### gtag support for multiple tracking IDs {/* #gtag-support-for-multiple-tracking-ids */} In [#8620](https://github.com/facebook/docusaurus/pull/8620) we added support for the [@docusaurus/plugin-google-gtag](/docs/api/plugins/@docusaurus/plugin-google-gtag) plugin to declare multiple tracking IDs. @@ -114,7 +114,7 @@ To preserve the continuity of your analytics, we temporarily recommend that you ::: -### Developer Experience +### Developer Experience {/* #developer-experience */} In [#8736](https://github.com/facebook/docusaurus/pull/8736), we improved how we render error messages and added initial support to render the full causal chain of an error (see [ES2022 Error Cause](https://h3manth.com/ES2022/#error-cause)). @@ -128,7 +128,7 @@ In [#8735](https://github.com/facebook/docusaurus/pull/8735) we also made navbar ![Docusaurus navbar error message screenshot](./img/navbar-error.jpg) -### Translations +### Translations {/* #translations */} We made it possible to translate some new elements: @@ -146,7 +146,7 @@ Completing theme translations is an [ongoing effort](https://github.com/facebook ::: -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/3.0/index.mdx b/website/blog/releases/3.0/index.mdx index 87496cd352bc..13aa29784324 100644 --- a/website/blog/releases/3.0/index.mdx +++ b/website/blog/releases/3.0/index.mdx @@ -34,7 +34,7 @@ According to our [release process](/community/release-process), Docusaurus v2 ha import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow'; -## Breaking changes +## Breaking changes {/* #breaking-changes */} This section only gives you a quick glance. All the breaking changes are thoroughly documented in the [**v3 upgrade guide**](/docs/migration/v3). @@ -94,11 +94,11 @@ Apart from MDX v3, most breaking changes coming with those upgraded dependencies - [#9310](https://github.com/facebook/docusaurus/pull/9310): remove the legacy versioned sidebar id prefix, used for sites versioned before `v2.0.0-beta.10` (December 2021) - [#7966](https://github.com/facebook/docusaurus/pull/7966): refactor docs theme components, eventually requiring to you re-swizzle them -## Highlights +## Highlights {/* #highlights */} 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**](https://github.com/facebook/docusaurus/releases/tag/v3.0.0). -### Markdown +### Markdown {/* #markdown */} Docusaurus v3 upgraded from MDX v1 to MDX v3: @@ -144,7 +144,7 @@ export default { Docusaurus now uses the [remark-directive](https://github.com/remarkjs/remark-directive) plugin to support admonitions. This also offers you the ability to create your own Remark plugins to extend Markdown with your own [custom directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) such as `:textDirective`, `::leafDirective` or `:::containerDirective`. -### ESM and TypeScript configs {#esm-ts-configs} +### ESM and TypeScript configs {/* #esm-ts-configs */} In [#9317](https://github.com/facebook/docusaurus/pull/9317), we added support for ES Modules and TypeScript config files, including site config, docs sidebars, plugins and presets. @@ -184,7 +184,7 @@ const sidebars: SidebarsConfig = { export default sidebars; ``` -### Unlisted content +### Unlisted content {/* #unlisted-content */} 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. @@ -202,7 +202,7 @@ Unlisted content will also display a banner so that you don't forget to turn it -### React 18 +### React 18 {/* #react-18 */} In [#8961](https://github.com/facebook/docusaurus/pull/8961), we upgraded to React 18. This is important, notably for the [gradual adoption of Concurrent React features](https://react.dev/blog/2022/03/29/react-v18#gradually-adopting-concurrent-features), as well as upcoming exciting features such as [build-time React Server Components](https://github.com/facebook/docusaurus/issues/9089). @@ -220,7 +220,7 @@ Their Docusaurus support is considered as **experimental**. We might have to adj ::: -### Automatic JSX runtime +### Automatic JSX runtime {/* #automatic-jsx-runtime */} Docusaurus now uses the ["automatic" JSX runtime](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html). @@ -234,7 +234,7 @@ It is not needed anymore to import React in JSX files that do not use any React } ``` -### Debug builds +### Debug builds {/* #debug-builds */} It is now possible to build your static site in dev mode. @@ -250,7 +250,7 @@ This new build mode is particularly helpful for **troubleshooting React problems ::: -### TypeScript +### TypeScript {/* #typescript */} Docusaurus v3 now requires a minimum version of TypeScript 5.0. @@ -274,7 +274,7 @@ import type {Options, ThemeConfig} from '@docusaurus/preset-classic'; import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; ``` -### Code blocks +### Code blocks {/* #code-blocks */} In [#9316](https://github.com/facebook/docusaurus/pull/9316), we improved on syntax highlighting thanks to the [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer) v2 upgrade. For example, a bash param `--save` is now colored: @@ -311,7 +311,7 @@ x = 10; y = times2(x); ``` -### Mermaid diagrams +### Mermaid diagrams {/* #mermaid-diagrams */} In [#9305](https://github.com/facebook/docusaurus/pull/9305), we upgraded to Mermaid v10.4 and added support for async diagram rendering. Docusaurus is now able to render new types of diagrams. @@ -354,7 +354,7 @@ quadrantChart -### Query-string data attributes +### Query-string data attributes {/* #query-string-data-attributes */} In [#9028](https://github.com/facebook/docusaurus/pull/9028), we made it possible to set custom HTML [data attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*) though `docusaurus-data-x` query-string parameters. This makes it easier to embed a Docusaurus iframe on another site, and lets you customize the appearance of the embedded version with CSS. @@ -370,7 +370,7 @@ html[data-red-border] div#__docusaurus { -### Other features +### Other features {/* #other-features */} Other new features worth mentioning: @@ -382,7 +382,7 @@ Other new features worth mentioning: Read [**Docusaurus v3.0.0 release notes**](https://github.com/facebook/docusaurus/releases/tag/v3.0.0) for an exhaustive list of changes. -## Conclusion +## Conclusion {/* #conclusion */} This release comes with a few features, but more importantly **upgrades many pieces of the Docusaurus infrastructure**. diff --git a/website/blog/releases/3.1/index.mdx b/website/blog/releases/3.1/index.mdx index a4db5eaf0147..3b4c65564bf2 100644 --- a/website/blog/releases/3.1/index.mdx +++ b/website/blog/releases/3.1/index.mdx @@ -12,15 +12,15 @@ The upgrade should be easy: as explained in our [release process documentation]( ![Docusaurus blog post social card](./img/social-card.png) - +{/* truncate */} import BrowserWindow from '@site/src/components/BrowserWindow'; import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow'; import ErrorBoundaryTestButton from '@site/src/components/ErrorBoundaryTestButton'; -## Highlights +## Highlights {/* #highlights */} -### Broken anchors checker +### Broken anchors checker {/* #broken-anchors-checker */} In [#9528](https://github.com/facebook/docusaurus/pull/9528), we improved the built-in broken links checker to also detect broken anchors. @@ -42,7 +42,7 @@ For users and plugin authors implementing custom `` and `` compon ::: -### `parseFrontMatter` hook +### `parseFrontMatter` hook {/* #parsefrontmatter-hook */} In [#9624](https://github.com/facebook/docusaurus/pull/9624), we added a new [`siteConfig.markdown.parseFrontMatter` function hook](/docs/api/docusaurus-config#markdown). @@ -81,7 +81,7 @@ export default { Read the [front matter guide](/docs/markdown-features#front-matter) and the [`parseFrontMatter` API ref](/docs/api/docusaurus-config#markdown) for details. -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/3.2/index.mdx b/website/blog/releases/3.2/index.mdx index 2c5136996110..dffd2ade3782 100644 --- a/website/blog/releases/3.2/index.mdx +++ b/website/blog/releases/3.2/index.mdx @@ -12,15 +12,15 @@ The upgrade should be easy: as explained in our [release process documentation]( ![Docusaurus blog post social card](./img/social-card.png) - +{/* truncate */} import BrowserWindow from '@site/src/components/BrowserWindow'; import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow'; import ErrorBoundaryTestButton from '@site/src/components/ErrorBoundaryTestButton'; -## Highlights +## Highlights {/* #highlights */} -### Faster builds +### Faster builds {/* #faster-builds */} We worked hard to reduce the time it takes to build a Docusaurus site in production mode. @@ -44,7 +44,7 @@ An incremental build happens when you run another time the `docusaurus build` co -### Faster Dev Server +### Faster Dev Server {/* #faster-dev-server */} We also worked on improving the performance of the dev server, so that you can get a faster feedback when editing Markdown/MDX files. @@ -52,7 +52,7 @@ The way we initially implemented content reloading wasn't great. For example, ed We 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. -### MDX partials table-of-contents +### MDX partials table-of-contents {/* #mdx-partials-table-of-contents */} With [#9684](https://github.com/facebook/docusaurus/pull/9684), Docusaurus is now able to render headings coming from an imported partial into the table-of-contents. @@ -78,7 +78,7 @@ Some paragraph Previously, the heading `Partial heading` did not appear in the table-of-contents, but now it will! -### Blog improvements +### Blog improvements {/* #blog-improvements */} We improved the blog plugin with several new options to make it even more powerful and flexible: @@ -86,7 +86,7 @@ We improved the blog plugin with several new options to make it even more powerf - [#9886](https://github.com/facebook/docusaurus/pull/9886): a new `processBlogPosts` option allow you to filter/transform/sort blog posts. - [#9838](https://github.com/facebook/docusaurus/pull/9838): a new `pageBasePath` option allows you to customize the blog pagination URL segment (`/blog/page/2`) -### Sitemap lastmod +### Sitemap lastmod {/* #sitemap-lastmod */} With [#9954](https://github.com/facebook/docusaurus/pull/9954), the sitemap plugin has a new `lastmod` option that can now emit a `` 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. @@ -102,7 +102,7 @@ We recommend using the following sitemap plugin config, that will become the def } ``` -## Other changes +## Other changes {/* #other-changes */} - [#9687](https://github.com/facebook/docusaurus/pull/9687): new Vercel Analytics plugin - [#9681](https://github.com/facebook/docusaurus/pull/9681) and [#9442](https://github.com/facebook/docusaurus/pull/9442): `docusaurus swizzle` and `create-docusaurus` CLIs now ask users if they prefer to use TypeScript diff --git a/website/blog/releases/3.3/index.mdx b/website/blog/releases/3.3/index.mdx index 88907a9d90fd..31ae75b69786 100644 --- a/website/blog/releases/3.3/index.mdx +++ b/website/blog/releases/3.3/index.mdx @@ -12,14 +12,14 @@ Upgrading should be easy. Our [release process](/community/release-process) resp ![Docusaurus blog post social card](./img/social-card.png) - +{/* truncate */} import BrowserWindow from '@site/src/components/BrowserWindow'; import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow'; -## Highlights +## Highlights {/* #highlights */} -### Prepare for React 19 +### Prepare for React 19 {/* #prepare-for-react-19 */} The React core team recently [released the first **React 19 beta**](https://react.dev/blog/2024/04/25/react-19). They also [published an upgrade guide and a **React v18.3 release**](https://react.dev/blog/2024/04/25/react-19-upgrade-guide) with new warnings to help us identify issues **before upgrading to React 19**. @@ -31,7 +31,7 @@ It turns out in its current state, **Docusaurus had a few of those extra warning In [#10079](https://github.com/facebook/docusaurus/pull/10079), we got Docusaurus ready for React 19. We fixed all the React 18.3 warnings we encountered. In case we missed any, don't hesitate to [**report new warnings**](https://github.com/facebook/docusaurus/issues/10099) if you see them, to us but also to other Docusaurus third-party plugin authors. -### `createSitemapItems` +### `createSitemapItems` {/* #createsitemapitems */} In [#10083](https://github.com/facebook/docusaurus/pull/10083), we introduced a new flexible `createSitemapItems()` hook to the sitemap plugin. This enables users to create/filter/transform/enhance the sitemap items with their own custom logic. @@ -58,7 +58,7 @@ export default { }; ``` -### Pages plugin improvements +### Pages plugin improvements {/* #pages-plugin-improvements */} The Docusaurus [pages plugin](/docs/api/plugins/@docusaurus/plugin-content-pages) has historically been lagging behind the docs and blog plugins in terms of available feature. @@ -93,7 +93,7 @@ These new plugin options only apply to Markdown pages, and have no effect on Rea ::: -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/3.4/index.mdx b/website/blog/releases/3.4/index.mdx index de0a1cfec04d..97308d417ebc 100644 --- a/website/blog/releases/3.4/index.mdx +++ b/website/blog/releases/3.4/index.mdx @@ -12,11 +12,11 @@ Upgrading should be easy. Our [release process](/community/release-process) resp ![Docusaurus blog post social card](./img/social-card.png) - +{/* truncate */} -## Highlights +## Highlights {/* #highlights */} -### Tags files +### Tags files {/* #tags-files */} 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. @@ -52,7 +52,7 @@ Use the new `onInlineTags: 'throw'` plugin option to enforce the usage of predef ::: -### Hash Router - Experimental +### Hash Router - Experimental {/* #hash-router---experimental */} With [9859](https://github.com/facebook/docusaurus/pull/9859), we added a new **experimental** hash router config option, useful for **offline browsing** by opening your site locally through the `file://` protocol. @@ -85,7 +85,7 @@ This feature is **experimental**. If you try it out, please let us know how it w ::: -### Site Storage - Experimental +### Site Storage - Experimental {/* #site-storage---experimental */} Docusaurus uses the browser `localStorage` API to persist UI state. @@ -115,7 +115,7 @@ This feature is **experimental**. If you try it out, please let us know how it w ::: -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/3.5/index.mdx b/website/blog/releases/3.5/index.mdx index 13b07cc79d24..a61e6d1d5abf 100644 --- a/website/blog/releases/3.5/index.mdx +++ b/website/blog/releases/3.5/index.mdx @@ -16,9 +16,9 @@ Upgrading should be easy. Our [release process](/community/release-process) resp {/* truncate */} -## Highlights +## Highlights {/* #highlights */} -### Blog Social Icons +### Blog Social Icons {/* #blog-social-icons */} In [#10222](https://github.com/facebook/docusaurus/pull/10222), we added the possibility to associate social links to blog authors, for inline authors declared in front matter or global through the `authors.yml` file. @@ -39,7 +39,7 @@ slorber: 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. -### Blog Authors Pages +### Blog Authors Pages {/* #blog-authors-pages */} In [#10216](https://github.com/facebook/docusaurus/pull/10216), we added the possibility for [global blog authors](/docs/blog#global-authors) (declared in `authors.yml`) to have their own dedicated page listing all the blog posts they contributed to. @@ -64,7 +64,7 @@ An [authors index page](/blog/authors) is also created, listing all the blog aut Check the [blog authors pages guide](/docs/blog#authors-pages) for details. -### Blog Feeds Styling +### Blog Feeds Styling {/* #blog-feeds-styling */} In [#9252](https://github.com/facebook/docusaurus/pull/9252), we added support for [styling your blog feeds](https://darekkay.com/blog/rss-styling/) by providing custom XSLT `.xls` files for the RSS and Atom feeds. This allows browsers to render the feeds in a more visually appealing way, like a regular HTML page, instead of the default XML view. @@ -95,7 +95,7 @@ const blogOptions = { ![Screenshot of the Docusaurus blog RSS feed, beautifully styled](./img/blog-feed-xslt.png) -### Blog Sidebar Grouping +### Blog Sidebar Grouping {/* #blog-sidebar-grouping */} In [#10252](https://github.com/facebook/docusaurus/pull/10252), we added support for grouping blog posts by years in the blog sidebar. @@ -103,23 +103,23 @@ In [#10252](https://github.com/facebook/docusaurus/pull/10252), we added support This feature is now turned on by default, but can be disabled with `themeConfig.blog.sidebar.groupByYear: false`. -### Blog Consistency Options +### Blog Consistency Options {/* #blog-consistency-options */} We added new blog options to enforce recommended practices for your blog posts: -#### `onInlineAuthors` +#### `onInlineAuthors` {/* #oninlineauthors */} We believe large multi-blogs are easier to manage by using [global authors](/docs/blog#global-authors), declared in `authors.yml`. This notably permits to avoids duplicating author information across multiple blog posts, and now permits to generate [author pages](/docs/blog#authors-pages). In [#10224](https://github.com/facebook/docusaurus/pull/10224), we added the `onInlineAuthors` option. Use `onInlineAuthors: 'throw'` to forbid [inline authors](/docs/blog#inline-authors), and enforce a consistent usage of [global authors](/docs/blog#global-authors). -#### `onUntruncatedBlogPosts` +#### `onUntruncatedBlogPosts` {/* #onuntruncatedblogposts */} We believe blog posts are better using [truncation markers](/docs/blog#blog-list) (`` 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](https://github.com/facebook/docusaurus/pull/10375), we added the `onUntruncatedBlogPosts` option. Use `onUntruncatedBlogPosts: 'throw'` to enforce a consistent usage of [truncation markers](/docs/blog#blog-list). -## Translations +## Translations {/* #translations */} - 🇪🇪 [#10339](https://github.com/facebook/docusaurus/pull/10339): Add Estonian theme translations. - 🇮🇩 [#10325](https://github.com/facebook/docusaurus/pull/10325): Add Indonesian theme translations. @@ -127,7 +127,7 @@ In [#10375](https://github.com/facebook/docusaurus/pull/10375), we added the `on - 🇩🇪 [#10235](https://github.com/facebook/docusaurus/pull/10235): Improve German theme translations. - 🇨🇳 [#10257](https://github.com/facebook/docusaurus/pull/10257): Improve Traditional Chinese (zh-Hant) theme translations. -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/3.6/index.mdx b/website/blog/releases/3.6/index.mdx index 297bbd0f99b7..fb015df04670 100644 --- a/website/blog/releases/3.6/index.mdx +++ b/website/blog/releases/3.6/index.mdx @@ -16,11 +16,11 @@ Upgrading should be easy. Our [release process](/community/release-process) resp {/* truncate */} -## Highlights +## Highlights {/* #highlights */} This release has been mostly focused on build performance through the [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) project. -## Docusaurus Faster +## Docusaurus Faster {/* #docusaurus-faster */} The [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) project's goal is to reduce the build times and memory consumption. @@ -30,13 +30,13 @@ We have worked on multiple optimizations and modernized our infrastructure to us - 🦀 [SWC](https://swc.rs/): Speedy Web Compiler, Rust-based platform for the Web (HTML, CSS, JS) - 🦀 [Lightning CSS](https://lightningcss.dev/): An extremely fast CSS parser, transformer, bundler, and minifier -### Impacts +### Impacts {/* #impacts */} Adopting a new infrastructure can have various impacts. It's impossible to list them all exhaustively, so let's focus on the major ones. To help you adopt it easily, we have been fairly conservative in terms of expected static site output and [browser support](/docs/browser-support). -#### Build Time +#### Build Time {/* #build-time */} Benchmarks on community site show that you can expect your production site to build ⚡️**2 to 4 times faster**! 🔥: @@ -52,7 +52,7 @@ Benchmarks on community site show that you can expect your production site to bu ::: -#### Memory Consumption +#### Memory Consumption {/* #memory-consumption */} You should also notice an improvement in memory consumption: @@ -62,13 +62,13 @@ You should also notice an improvement in memory consumption: - We added [internal tooling](https://github.com/facebook/docusaurus/pull/10590) to better understand which step of a build consumes memory - We [removed a `process.exit(0)`](https://github.com/facebook/docusaurus/pull/10410) that can hide memory leaks in your own code and third-party plugins -#### Other Impacts +#### Other Impacts {/* #other-impacts */} - The HTML minifier now [emits warnings in case of invalid HTML markup](https://github.com/facebook/docusaurus/discussions/10580) - The static HTML output is [~5% smaller](https://github.com/facebook/docusaurus/pull/10554) - Some bugs are automatically fixed by the new infrastructure -### Adoption Strategy +### Adoption Strategy {/* #adoption-strategy */} This new infrastructure is a breaking change, but it is opt-in and does not require a new major version of Docusaurus. @@ -122,7 +122,7 @@ The new infrastructure is robust and well-tested by our CI pipeline. The [Docusa ::: -#### Plugins +#### Plugins {/* #plugins */} The new infrastructure uses [Rspack](https://rspack.dev/). By chance, Rspack is almost 100% compatible with [webpack](https://webpack.js.org/), and Rspack shouldn't break our plugin ecosystem. @@ -155,7 +155,7 @@ Check the [dedicated issue](https://github.com/facebook/docusaurus/issues/10572) ::: -### Next Steps +### Next Steps {/* #next-steps */} It's only the beginning: we will continue working on the [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) project and already have a few more performance improvements planned. @@ -163,7 +163,7 @@ Depending on [your feedback](https://github.com/facebook/docusaurus/issues/10556 🙏 We'd like to thank the authors of all these great tools that already helped us make Docusaurus much faster than before. In particular the [Rspack team](https://rspack.dev/misc/team/core-team) that supported us along the way, handled our feedback very quickly and implemented all the missing features we needed to make it happen. 👏 -## Rsdoctor plugin +## Rsdoctor plugin {/* #rsdoctor-plugin */} In [#10588](https://github.com/facebook/docusaurus/pull/10588), we created a Docusaurus plugin for [Rsdoctor](https://rsdoctor.dev/). It analyzes the bundling phase of Docusaurus and helps you figure out what slows down the bundler in terms of loaders, plugins and minimizers. It works for both webpack and Rspack. @@ -211,7 +211,7 @@ RSDOCTOR=true npm run build ::: -## Mermaid +## Mermaid {/* #mermaid */} In [#10510](https://github.com/facebook/docusaurus/pull/10510), we relaxed our [Mermaid diagrams](https://mermaid.js.org/) dependency range to allow newer major versions of Mermaid. We now support both Mermaid 10/11, and expect upcoming versions to be compatible, letting you upgrade on your own terms. @@ -231,13 +231,13 @@ architecture-beta disk2:T -- B:db ``` -## Translations +## Translations {/* #translations */} - 🇸🇮 [#10551](https://github.com/facebook/docusaurus/pull/10551): Improve Slovenian theme translations. - 🇻🇳 [#10507](https://github.com/facebook/docusaurus/pull/10507): Improve Vietnamese theme translations. - 🇪🇸 [#10413](https://github.com/facebook/docusaurus/pull/10413): Improve Spanish theme translations. -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/3.7/index.mdx b/website/blog/releases/3.7/index.mdx index 557a32385845..b7586bd80b06 100644 --- a/website/blog/releases/3.7/index.mdx +++ b/website/blog/releases/3.7/index.mdx @@ -16,9 +16,9 @@ Upgrading should be easy. Our [release process](/community/release-process) resp {/* truncate */} -## Highlight +## Highlight {/* #highlight */} -### React 19 +### React 19 {/* #react-19 */} In [#10763](https://github.com/facebook/docusaurus/pull/10763), we added support for [React 19](https://react.dev/blog/2024/12/05/react-19), and the Docusaurus website is running on React 19 already. @@ -57,7 +57,7 @@ Here are good reasons to upgrade your site before Docusaurus v4: Along the way, we [fixed](https://github.com/facebook/docusaurus/pull/10786) all the remaining hydration errors reported by React 19, some of them produced by our aggressive HTML minifier settings. -### SVGR plugin +### SVGR plugin {/* #svgr-plugin */} Docusaurus has built-in support for [SVGR](https://github.com/gregberge/svgr), allowing you to seamlessly import and use SVG files as React components: @@ -92,7 +92,7 @@ export default { }; ``` -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/3.8/index.mdx b/website/blog/releases/3.8/index.mdx index 818f0d521ab6..673a085983bf 100644 --- a/website/blog/releases/3.8/index.mdx +++ b/website/blog/releases/3.8/index.mdx @@ -22,11 +22,11 @@ import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow'; import NavbarColorModeToggle from '@theme/Navbar/ColorModeToggle'; ``` -## Performance +## Performance {/* #performance */} This release keeps improving our build infrastructure performance with various optimizations, and 2 new Docusaurus Faster options. -### Docusaurus Faster +### Docusaurus Faster {/* #docusaurus-faster */} [Docusaurus Faster](https://github.com/facebook/docusaurus/issues/10556) has been introduced in [Docusaurus v3.6](/blog/releases/3.6#docusaurus-faster), and permits you to opt-in for our upgraded build infrastructure and helps you build your site much faster. The experimental flags can be turned on individually, but we recommend to turn them all at once with this convenient shortcut: @@ -45,7 +45,7 @@ Don't forget to install the `@docusaurus/faster` dependency first! ::: -#### Persistent Cache +#### Persistent Cache {/* #persistent-cache */} In [#10931](https://github.com/facebook/docusaurus/pull/10931), we have enabled the **[Rspack persistent cache](https://rspack.dev/blog/announcing-1-2#persistent-cache)**. Similarly to the [Webpack persistent cache](https://webpack.js.org/blog/2020-10-10-webpack-5-release/#persistent-caching) (already supported), it permits to greatly speed up the bundling of the Docusaurus app on subsequent builds. @@ -76,7 +76,7 @@ Popular CDNs such as Netlify and Vercel do that for you automatically. Depending **Result**: On average, you can expect your site's bundling time to be ~2-5× faster on rebuilds 🔥. The impact can be even more significant if you [disable the optional `concatenateModule` optimization](https://github.com/facebook/docusaurus/discussions/11199). -#### Worker Threads +#### Worker Threads {/* #worker-threads */} In [#10826](https://github.com/facebook/docusaurus/pull/10826), we introduced a [Node.js Worker Thread pool](https://github.com/tinylibs/tinypool) to run the static side generation code. With this new strategy, we can better leverage all the available CPUs, reduce static site generation time, and contain potential memory leaks. @@ -99,7 +99,7 @@ const config = { **Result**: On average, you can expect your site's static site generation time to be ~2× times faster 🔥. This was measured on a MacBook Pro M3 and result may vary depending on your CI. -### Other Optimizations +### Other Optimizations {/* #other-optimizations */} We identified and resolved several major bottlenecks, including: @@ -114,7 +114,7 @@ If bundling time is a concern, consider disabling the optional `concatenateModul ::: -### Impact +### Impact {/* #impact */} We have upgraded the [React Native website to Docusaurus v3.8](https://github.com/facebook/react-native-website/pull/4607) already. Here's an updated benchmark showing the global Docusaurus Faster impact on total build time for a site with ~2000 pages: @@ -132,7 +132,7 @@ We measured similar results on our website: You can also expect memory usage improvements, and a faster `docusaurus start` experience. -## Future Flags +## Future Flags {/* #future-flags */} The Docusaurus v4 Future Flags let you **opt-in for upcoming Docusaurus v4 breaking changes**, and help you manage them incrementally, one at a time. Enabling all the future flags will make your site easier to upgrade to Docusaurus v4 when it's released. @@ -162,7 +162,7 @@ This way, you are sure to always keep your site prepared for Docusaurus v4. Be a ::: -### CSS Cascade Layers +### CSS Cascade Layers {/* #css-cascade-layers */} In Docusaurus v4, we plan to leverage [CSS Cascade Layers](https://css-tricks.com/css-cascade-layers/). This modern CSS feature is widely supported and permits to group CSS rules in layers of specificity. It is particularly useful to give you more control over the CSS cascade. It makes the CSS rules less dependent on their insertion order. Your un-layered rules will now always override the layered CSS we provide. @@ -223,7 +223,7 @@ Then you can apply this class to any HTML element, so that Infima doesn't apply -### `postBuild()` Change +### `postBuild()` Change {/* #postbuild-change */} In [#10850](https://github.com/facebook/docusaurus/pull/10850), we added a new `removeLegacyPostBuildHeadAttribute` Future Flag that slightly changes the signature of the `postBuild()` plugin lifecycle method, removing the `head` attribute. @@ -242,7 +242,7 @@ This legacy data structure is coming from our [react-helmet-async](https://githu While technically a **breaking change**, we believe this change will not affect anyone. We couldn't find any open source plugin that uses the `head` parameter that this method receives. If turning this flag on breaks your site, please let us know [here](https://github.com/facebook/docusaurus/pull/10850). -## System Color Mode +## System Color Mode {/* #system-color-mode */} In [#10987](https://github.com/facebook/docusaurus/pull/10987), the classic theme now lets you revert the color mode to the system/OS value. @@ -256,20 +256,20 @@ In [#10987](https://github.com/facebook/docusaurus/pull/10987), the classic them ``` -## Code Block Refactor +## Code Block Refactor {/* #code-block-refactor */} In [#11058](https://github.com/facebook/docusaurus/pull/11058), [#11059](https://github.com/facebook/docusaurus/pull/11059), [#11062](https://github.com/facebook/docusaurus/pull/11062) and [#11077](https://github.com/facebook/docusaurus/pull/11077), the theme code block components have been significantly refactored in a way that should be much easier to swizzle and extend. According to our [release process](/community/release-process), this is not a breaking change, but sites that have swizzled these components may need to upgrade them. -## Translations +## Translations {/* #translations */} - 🇹🇷 [#10893](https://github.com/facebook/docusaurus/pull/10893): Add missing Turkish theme translations. - 🇵🇱 [#10884](https://github.com/facebook/docusaurus/pull/10884): Add missing Polish theme translations. - 🇨🇳 [#10816](https://github.com/facebook/docusaurus/pull/10816): Add missing Chinese theme translations. - 🇯🇵 [#11030](https://github.com/facebook/docusaurus/pull/11030): Add missing Japanese theme translations. -## Maintenance +## Maintenance {/* #maintenance */} Docusaurus 3.8 is ready for [Node.js 24](https://github.com/facebook/docusaurus/pull/11168) and [TypeScript 5.8](https://github.com/facebook/docusaurus/pull/10966). @@ -281,7 +281,7 @@ We also removed useless npm packages and internalizing unmaintained ones: - In [#11138](https://github.com/facebook/docusaurus/pull/11138), we removed the `reading-time` package in favor of the built-in `Intl.Segmenter` standard API to compute blog post reading times. - In [#11037](https://github.com/facebook/docusaurus/pull/11037), we removed the useless `clean-webpack-plugin`. -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/blog/releases/3.9/index.mdx b/website/blog/releases/3.9/index.mdx index d1631588f878..4cda7f17437f 100644 --- a/website/blog/releases/3.9/index.mdx +++ b/website/blog/releases/3.9/index.mdx @@ -20,7 +20,7 @@ Upgrading is easy. We follow [Semantic Versioning](https://semver.org/), and min import BrowserWindow from '@site/src/components/BrowserWindow'; ``` -## Dropping Node.js 18 +## Dropping Node.js 18 {/* #dropping-nodejs-18 */} In [#11408](https://github.com/facebook/docusaurus/pull/11408), we have dropped support for Node.js 18, and the new minimum required Node.js version is now v20.0. @@ -31,7 +31,7 @@ This upgrade is further motivated by our dependencies: - Some of our dependencies now only receive security patches on newer versions that do not support Node.js 18 anymore. See, for example, this [`webpack-dev-server@4` security warning](https://github.com/facebook/docusaurus/pull/11410). To keep the Docusaurus v3 release line secure for our users, for both the runtime and third-party dependencies, the upgrade is necessary. - Some of our dependencies are also dropping support for Node.js 18 in minor releases, transitively impacting Docusaurus runtime requirements. For example, [Rspack 1.5 now requires Node.js 18.12](https://rspack.rs/blog/announcing-1-5), while Docusaurus v3 initially supported Node.js 18.0. -## DocSearch v4 +## DocSearch v4 {/* #docsearch-v4 */} In [#11327](https://github.com/facebook/docusaurus/pull/11327) and [#11421](https://github.com/facebook/docusaurus/pull/11421), we added support for Algolia DocSearch v4. This new version comes with [AskAI](https://docsearch.algolia.com/docs/v4/askai) support, letting you add an AI-powered search assistant to your Docusaurus site that can answer questions based on what's in your documentation with a conversational experience. @@ -53,7 +53,7 @@ When using DocSearch v4, the new AskAI feature is not enabled by default: you al ::: -## i18n improvements +## i18n improvements {/* #i18n-improvements */} In [#11316](https://github.com/facebook/docusaurus/pull/11316), we added new `i18n.localeConfigs[locale].{url,baseUrl}` config options to better support complex and multi-domain i18n deployments. Previously, Docusaurus relied on hard-coded heuristics that made sense for most i18n projects, but weren't flexible enough to accommodate all use cases, leading UX and SEO issues. It is now possible to configure each locale's deployment URL and base URL independently, overriding the default values inferred by Docusaurus: @@ -105,7 +105,7 @@ export default { }; ``` -## Mermaid ELK layouts +## Mermaid ELK layouts {/* #mermaid-elk-layouts */} In [#11357](https://github.com/facebook/docusaurus/pull/11357), we added support for [Mermaid ELK layout algorithm](https://mermaid.js.org/intro/syntax-reference.html#supported-layout-algorithms), based on the [Eclipse Layout Kernel (ELK)](https://www.eclipse.org/elk/). Compared to the default Dagre layout, it provides more sophisticated layout capabilities and configuration options, especially useful when working with large or intricate diagrams. @@ -136,12 +136,12 @@ erDiagram CUSTOMER }|..|{ DELIVERY-ADDRESS : uses ``` -## Translations +## Translations {/* #translations */} - 🇧🇷 [#11315](https://github.com/facebook/docusaurus/pull/11315): Add missing Brazilian Portuguese theme translations. - 🇺🇦 [#11305](https://github.com/facebook/docusaurus/pull/11305): Add missing Ukrainian theme translations. -## Other changes +## Other changes {/* #other-changes */} Other notable changes include: diff --git a/website/community/0-support.mdx b/website/community/0-support.mdx index 6e2cad8d81a6..3788d054dcc6 100644 --- a/website/community/0-support.mdx +++ b/website/community/0-support.mdx @@ -6,11 +6,11 @@ On this page we've listed some Docusaurus-related communities that you can be a Before participating in Docusaurus' communities, [please read our Code of Conduct](https://engineering.fb.com/codeofconduct/). We have adopted the [Contributor Covenant](https://www.contributor-covenant.org/) and we expect that all community members adhere to the guidelines within. -## Stack Overflow {#stack-overflow} +## Stack Overflow {/* #stack-overflow */} Stack Overflow is a popular forum to ask code-level questions or if you're stuck with a specific error. Read through the [existing questions](https://stackoverflow.com/questions/tagged/docusaurus) tagged with **docusaurus** or [ask your own](https://stackoverflow.com/questions/ask?tags=docusaurus)! -## Discussion forums {#discussion-forums} +## Discussion forums {/* #discussion-forums */} There are many online forums for discussion about best practices and application architecture as well as the future of Docusaurus. If you have an answerable code-level question, Stack Overflow is usually a better fit. @@ -19,10 +19,10 @@ There are many online forums for discussion about best practices and application - [#contributors](https://discord.gg/6g6ASPA) for contributing help - [Reddit's Docusaurus community](https://www.reddit.com/r/docusaurus/) -## Feature requests {#feature-requests} +## Feature requests {/* #feature-requests */} For new feature requests, you can create a post on our [feature requests board (Canny)](/feature-requests), which is a handy tool for road-mapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first! -## News {#news} +## News {/* #news */} For the latest news about Docusaurus, [follow **@docusaurus** on X](https://x.com/docusaurus) and the [official Docusaurus blog](/blog) on this website. diff --git a/website/community/1-team.mdx b/website/community/1-team.mdx index 98bf339e27c2..4e205d8195a6 100644 --- a/website/community/1-team.mdx +++ b/website/community/1-team.mdx @@ -6,7 +6,7 @@ import { StudentFellowsTeamRow, } from '@site/src/components/TeamProfileCards'; -## Active Team {#active-team} +## Active Team {/* #active-team */} The Docusaurus team works on the core functionality, plugins for the classic theme, as well as the Docusaurus documentation website. @@ -14,19 +14,19 @@ Current members of the Docusaurus team are listed in alphabetical order below. -## Honorary Alumni {#honorary-alumni} +## Honorary Alumni {/* #honorary-alumni */} Docusaurus would never be what it is today without the huge contributions from these folks who have moved on to bigger and greater things. -## Student Fellows {#student-fellows} +## Student Fellows {/* #student-fellows */} A handful of students have also worked on Docusaurus as part of their school term/internship and the [Major League Hacking Fellowship program](https://fellowship.mlh.io/), contributing amazing features such as plugin options validation, migration tooling, and a Bootstrap theme. -## Acknowledgements {#acknowledgements} +## Acknowledgements {/* #acknowledgements */} Docusaurus was originally created by Joel Marcey. Today, Docusaurus has a few hundred open source contributors. We’d like to recognize a few people who have made significant contributions to Docusaurus and its documentation in the past and have helped maintain them over the years: diff --git a/website/community/2-resources.mdx b/website/community/2-resources.mdx index 22244d224b4a..e4c6bbcec9b0 100644 --- a/website/community/2-resources.mdx +++ b/website/community/2-resources.mdx @@ -2,7 +2,7 @@ A curated list of interesting Docusaurus community projects. -## Community documentation {#community-documentation} +## Community documentation {/* #community-documentation */} The **[Docusaurus.community](https://docusaurus.community)** site extends the [official docs](/docs) with more complex examples and full articles that recommend best practices and provide solutions to common problems. @@ -16,23 +16,23 @@ We are also contemplating further integration into the official documentation at ::: -## Videos {#videos} +## Videos {/* #videos */} - [F8 2019: Using Docusaurus to Create Open Source Websites](https://www.youtube.com/watch?v=QcGJsf6mgZE) -## Articles {#articles} +## Articles {/* #articles */} - [Awesome Docusaurus](https://github.com/webbertakken/awesome-docusaurus#readme) - Community curated list of Docusaurus resources. - [Live code editing in Docusaurus](https://dev.to/mrmuhammadali/live-code-editing-in-docusaurus-ux-at-its-best-2hj1) - [The definitive guide to migrating from Blogger to Docusaurus](https://blog.johnnyreilly.com/definitive-guide-to-migrating-from-blogger-to-docusaurus) -## Showcase {#showcase} +## Showcase {/* #showcase */} See the showcase. -## Community plugins {#community-plugins} +## Community plugins {/* #community-plugins */} -### Search {#search} +### Search {/* #search */} - [docusaurus-plugin-lunr](https://github.com/daldridge/docusaurus-plugin-lunr) - Docusaurus plugin to create a local search index for use with Lunr.js - [docusaurus-lunr-search](https://github.com/lelouch77/docusaurus-lunr-search) - Offline Search for Docusaurus @@ -45,14 +45,14 @@ See the showcase - [@orama/plugin-docusaurus-v3](https://github.com/askorama/orama/tree/main/packages/plugin-docusaurus-v3) - [Orama](https://askorama.ai/) plugin for Docusaurus v3 - [@getcanary/docusaurus-theme-search-pagefind](https://getcanary.dev/docs/integrations/docusaurus.html) - Create [Pagefind](https://pagefind.app/) index and use [Canary](https://github.com/fastrepl/canary) as UI primitives. -### Integrations {#integrations} +### Integrations {/* #integrations */} - [docusaurus2-dotenv](https://github.com/jonnynabors/docusaurus2-dotenv) - A Docusaurus plugin that supports dotenv and other environment variables - [posthog-docusaurus](https://github.com/PostHog/posthog-docusaurus) - Integrate [PostHog](https://posthog.com/) product analytics with Docusaurus - [docusaurus-plugin-moesif](https://github.com/Moesif/docusaurus-plugin-moesif) - Adds [Moesif API Analytics](https://www.moesif.com/) to track user behavior and pinpoint where developers drop off in your activation funnel. - [docusaurus-plugin-yandex-metrica](https://github.com/sgromkov/docusaurus-plugin-yandex-metrica) - Adds [Yandex Metrika](https://metrika.yandex.ru/) counter for evaluating site traffic and analyzing user behavior. -### Features {#features} +### Features {/* #features */} - [docusaurus-theme-github-codeblock](https://github.com/saucelabs/docusaurus-theme-github-codeblock). A Docusaurus plugin that supports referencing code examples from public GitHub repositories - [docs-to-pdf](https://github.com/jean-humann/docs-to-pdf) - Generate documentation into PDF format @@ -75,7 +75,7 @@ See the showcase - [docusaurus-plugin-cookie-consent](https://github.com/mcclowes/docusaurus-plugin-cookie-consent) - A Docusaurus plugin for allowing users to opt in/out of cookies, and accessing those settings in code. - [expose-markdown-docusaurus-plugin](https://github.com/FlyNumber/markdown_docusaurus_plugin) - A Docusaurus plugin that exposes your /docs Markdown files as raw .md URLs. (For LLM's and such). -## Enterprise usage {#enterprise-usage} +## Enterprise usage {/* #enterprise-usage */} - Facebook - Google diff --git a/website/community/4-canary.mdx b/website/community/4-canary.mdx index cf337558cbce..38cdb791a186 100644 --- a/website/community/4-canary.mdx +++ b/website/community/4-canary.mdx @@ -53,7 +53,7 @@ The canary version shown below is directly fetched from npm and **is up-to-date* ``` -## Canary npm dist tag +## Canary npm dist tag {/* #canary-npm-dist-tag */} For any code-related commit on `main`, the continuous integration will publish a canary release under the `@canary` npm dist tag. It generally takes up to 10 minutes. @@ -74,7 +74,7 @@ Canary versions follow the naming convention `0.0.0-commitNumber`. ::: -## Using a canary release +## Using a canary release {/* #using-a-canary-release */} Take the latest version published under the [canary npm dist tag](https://www.npmjs.com/package/@docusaurus/core?activeTab=versions) (). diff --git a/website/community/5-release-process.mdx b/website/community/5-release-process.mdx index a30cdaaddccd..fadd13e1c62a 100644 --- a/website/community/5-release-process.mdx +++ b/website/community/5-release-process.mdx @@ -8,7 +8,7 @@ This topic is particularly important for highly customized sites that may have d ::: -## Semantic versioning {#semantic-versioning} +## Semantic versioning {/* #semantic-versioning */} Docusaurus versioning is based on the `major.minor.patch` scheme and respects [Semantic Versioning](https://semver.org/). @@ -19,7 +19,7 @@ Respecting Semantic Versioning is important for multiple reasons: - A new major version is an opportunity to thoroughly document breaking changes - A new major/minor version is an opportunity to communicate new features through a blog post -### Major versions {#major-versions} +### Major versions {/* #major-versions */} The `major` version number is incremented on **every breaking change**. @@ -34,7 +34,7 @@ Read our [public API surface](#public-api-surface) section to clearly understand ::: -### Minor versions {#minor-versions} +### Minor versions {/* #minor-versions */} The `minor` version number is incremented on every significant retro-compatible change. @@ -55,7 +55,7 @@ We may drop support for End-of-Life Node.js versions in minor Docusaurus version ::: -### Patch versions {#patch-versions} +### Patch versions {/* #patch-versions */} The `patch` version number is incremented on bugfixes releases. @@ -63,7 +63,7 @@ Whenever a new patch version is released, we publish: - an exhaustive changelog entry -## Node.js support policy {#nodejs-support} +## Node.js support policy {/* #nodejs-support */} Each major version of Docusaurus supports a minimum Node.js version. This retro-compatibility will be preserved all along that release line. This runtime backward compatibility will be preserved throughout all the minor versions of the release line, except for End-of-Life Node.js versions. @@ -73,7 +73,7 @@ On minor releases, we reserve the right to drop support for Node.js versions tha ::: -## Versions {#versions} +## Versions {/* #versions */} ```mdx-code-block import { @@ -107,7 +107,7 @@ It is recommended to upgrade within that time frame to the new stable version. ::: -## Public API surface {#public-api-surface} +## Public API surface {/* #public-api-surface */} Docusaurus commits to respecting Semantic Versioning. This means that whenever changes occur in Docusaurus public APIs and break backward compatibility, we will increment the `major` version number. @@ -119,7 +119,7 @@ Docusaurus guarantees public API retro-compatibility across `minor` versions. Un We will outline what accounts as the public API surface. -### Core public API {#core-public-api} +### Core public API {/* #core-public-api */} ✅ Our public API includes: @@ -148,7 +148,7 @@ For non-theme APIs, any documented API is considered public (and will be stable) An API being "stable" means if you increment the patch or minor version of your Docusaurus installation without any other change, running `docusaurus start` or `docusaurus build` should not throw an error. -### Theming public API {#theming-public-api} +### Theming public API {/* #theming-public-api */} Docusaurus has a very flexible theming system: From a0770823094b77cb4a436f9d2b6d85cef964ff52 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 6 Mar 2026 18:37:33 +0100 Subject: [PATCH 3/9] convert docs to native mdx --- crowdin-v2.yaml | 8 +- website/docs/advanced/client.mdx | 6 +- website/docs/advanced/plugins.mdx | 10 +-- website/docs/advanced/routing.mdx | 16 ++-- website/docs/advanced/ssg.mdx | 12 +-- website/docs/api/docusaurus.config.js.mdx | 76 ++++++++-------- website/docs/api/misc/create-docusaurus.mdx | 12 +-- .../docs/api/misc/eslint-plugin/README.mdx | 14 +-- .../api/misc/eslint-plugin/no-html-links.mdx | 4 +- .../eslint-plugin/no-untranslated-text.mdx | 8 +- .../prefer-docusaurus-heading.mdx | 2 +- .../string-literal-i18n-messages.mdx | 6 +- website/docs/api/misc/logger/logger.mdx | 4 +- website/docs/api/plugin-methods/README.mdx | 10 +-- .../plugin-methods/extend-infrastructure.mdx | 10 +-- .../api/plugin-methods/i18n-lifecycles.mdx | 8 +- .../api/plugin-methods/lifecycle-apis.mdx | 36 ++++---- .../api/plugin-methods/static-methods.mdx | 12 +-- .../_partial-tags-file-api-ref-section.mdx | 6 +- website/docs/api/plugins/overview.mdx | 4 +- .../api/plugins/plugin-client-redirects.mdx | 12 +-- .../docs/api/plugins/plugin-content-blog.mdx | 34 +++---- .../docs/api/plugins/plugin-content-docs.mdx | 24 ++--- .../docs/api/plugins/plugin-content-pages.mdx | 18 ++-- .../api/plugins/plugin-css-cascade-layers.mdx | 10 +-- website/docs/api/plugins/plugin-debug.mdx | 6 +- .../api/plugins/plugin-google-analytics.mdx | 6 +- .../docs/api/plugins/plugin-google-gtag.mdx | 6 +- .../api/plugins/plugin-google-tag-manager.mdx | 6 +- .../docs/api/plugins/plugin-ideal-image.mdx | 8 +- website/docs/api/plugins/plugin-pwa.mdx | 28 +++--- website/docs/api/plugins/plugin-rsdoctor.mdx | 6 +- website/docs/api/plugins/plugin-sitemap.mdx | 10 +-- website/docs/api/plugins/plugin-svgr.mdx | 6 +- .../api/plugins/plugin-vercel-analytics.mdx | 6 +- website/docs/api/themes/overview.mdx | 4 +- website/docs/api/themes/theme-classic.mdx | 4 +- .../docs/api/themes/theme-configuration.mdx | 66 +++++++------- .../docs/api/themes/theme-live-codeblock.mdx | 2 +- website/docs/api/themes/theme-mermaid.mdx | 2 +- website/docs/blog.mdx | 30 +++---- website/docs/browser-support.mdx | 6 +- website/docs/cli.mdx | 28 +++--- website/docs/configuration.mdx | 16 ++-- website/docs/deployment.mdx | 62 ++++++------- website/docs/docusaurus-core.mdx | 74 ++++++++-------- website/docs/guides/creating-pages.mdx | 8 +- website/docs/guides/docs/docs-create-doc.mdx | 14 +-- .../docs/guides/docs/docs-introduction.mdx | 2 +- .../docs/guides/docs/docs-multi-instance.mdx | 14 +-- .../guides/docs/sidebar/autogenerated.mdx | 12 +-- website/docs/guides/docs/sidebar/index.mdx | 20 ++--- website/docs/guides/docs/sidebar/items.mdx | 26 +++--- .../guides/docs/sidebar/multiple-sidebars.mdx | 6 +- website/docs/guides/docs/versioning.mdx | 32 +++---- .../markdown-features-admonitions.mdx | 20 ++--- .../markdown-features-assets.mdx | 12 +-- .../markdown-features-code-blocks.mdx | 34 +++---- .../markdown-features-diagrams.mdx | 12 +-- .../markdown-features-head-metadata.mdx | 4 +- .../markdown-features-intro.mdx | 10 +-- .../markdown-features-math-equations.mdx | 10 +-- .../markdown-features-plugins.mdx | 8 +- .../markdown-features-react.mdx | 14 +-- .../markdown-features-tabs.mdx | 10 +-- .../markdown-features-toc.mdx | 88 +++++++++---------- website/docs/i18n/i18n-crowdin.mdx | 48 +++++----- website/docs/i18n/i18n-git.mdx | 20 ++--- website/docs/i18n/i18n-introduction.mdx | 20 ++--- website/docs/i18n/i18n-tutorial.mdx | 34 +++---- website/docs/installation.mdx | 18 ++-- website/docs/introduction.mdx | 32 +++---- website/docs/migration/index.mdx | 6 +- .../docs/migration/v2/migration-automated.mdx | 2 +- .../docs/migration/v2/migration-manual.mdx | 66 +++++++------- .../docs/migration/v2/migration-overview.mdx | 16 ++-- .../v2/migration-translated-sites.mdx | 16 ++-- .../v2/migration-versioned-sites.mdx | 8 +- website/docs/migration/v3.mdx | 80 ++++++++--------- website/docs/search.mdx | 28 +++--- website/docs/seo.mdx | 18 ++-- website/docs/static-assets.mdx | 10 +-- website/docs/styling-layout.mdx | 24 ++--- website/docs/swizzling.mdx | 16 ++-- website/docs/typescript-support.mdx | 8 +- website/docs/using-plugins.mdx | 18 ++-- 86 files changed, 794 insertions(+), 794 deletions(-) diff --git a/crowdin-v2.yaml b/crowdin-v2.yaml index b9e5b1b86d7c..34e385637579 100644 --- a/crowdin-v2.yaml +++ b/crowdin-v2.yaml @@ -47,10 +47,10 @@ files: # translation: /website/i18n/%two_letters_code%/**/%original_file_name% # languages_mapping: *languages_mapping # - # - source: /website/docs/**/*.mdx - # translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name% - # languages_mapping: *languages_mapping - # type: *mdx_file_type + - source: /website/docs/**/*.mdx + translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name% + languages_mapping: *languages_mapping + type: *mdx_file_type # - source: /website/docs/**/* # translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name% # languages_mapping: *languages_mapping diff --git a/website/docs/advanced/client.mdx b/website/docs/advanced/client.mdx index f4d37d296ded..7608265aba93 100644 --- a/website/docs/advanced/client.mdx +++ b/website/docs/advanced/client.mdx @@ -4,7 +4,7 @@ description: How the Docusaurus client is structured # Client architecture -## Theme aliases {#theme-aliases} +## Theme aliases {/* #theme-aliases */} A theme works by exporting a set of components, e.g. `Navbar`, `Layout`, `Footer`, to render the data passed down from plugins. Docusaurus and users use these components by importing them using the `@theme` webpack alias: @@ -80,7 +80,7 @@ The components in this "stack" are pushed in the order of `preset plugins > pres `@theme-init/*` always points to the bottommost component—usually, this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases! -## Client modules {#client-modules} +## Client modules {/* #client-modules */} Client modules are part of your site's bundle, just like theme components. However, they are usually side-effect-ful. Client modules are anything that can be `import`ed by Webpack—CSS, JS, etc. JS scripts usually work on the global context, like registering event listeners, creating global variables... @@ -117,7 +117,7 @@ CSS stylesheets imported as client modules are [global](../styling-layout.mdx#gl } ``` -### Client module lifecycles {#client-module-lifecycles} +### Client module lifecycles {/* #client-module-lifecycles */} Besides introducing side-effects, client modules can optionally export two lifecycle functions: `onRouteUpdate` and `onRouteDidUpdate`. diff --git a/website/docs/advanced/plugins.mdx b/website/docs/advanced/plugins.mdx index 1f09ea723a2a..bdb49aaadccf 100644 --- a/website/docs/advanced/plugins.mdx +++ b/website/docs/advanced/plugins.mdx @@ -2,11 +2,11 @@ Plugins are the building blocks of features in a Docusaurus site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via presets. -## Creating plugins {#creating-plugins} +## Creating plugins {/* #creating-plugins */} A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](../api/plugin-methods/README.mdx). -### Function definition {#function-definition} +### Function definition {/* #function-definition */} You can use a plugin as a function directly included in the Docusaurus config file: @@ -33,7 +33,7 @@ export default { }; ``` -### Module definition {#module-definition} +### Module definition {/* #module-definition */} You can use a plugin as a module path referencing a separate file or npm package: @@ -80,11 +80,11 @@ Plugins come as several types: You can access them on the client side with `useDocusaurusContext().siteMetadata.pluginVersions`. -## Plugin design {#plugin-design} +## Plugin design {/* #plugin-design */} Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page. -### Theme design {#theme-design} +### Theme design {/* #theme-design */} When plugins have loaded their content, the data is made available to the client side through actions like [`createData` + `addRoute`](../api/plugin-methods/lifecycle-apis.mdx#addRoute) or [`setGlobalData`](../api/plugin-methods/lifecycle-apis.mdx#setGlobalData). This data has to be _serialized_ to plain strings, because [plugins and themes run in different environments](./architecture.mdx). Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through `ReactDOM.render`... diff --git a/website/docs/advanced/routing.mdx b/website/docs/advanced/routing.mdx index ea62c06f357e..ed29569dd6eb 100644 --- a/website/docs/advanced/routing.mdx +++ b/website/docs/advanced/routing.mdx @@ -13,7 +13,7 @@ import BrowserWindow from '@site/src/components/BrowserWindow'; Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system. -## Routing in content plugins {#routing-in-content-plugins} +## Routing in content plugins {/* #routing-in-content-plugins */} Every content plugin provides a `routeBasePath` option. It defines where the plugins append their routes to. By default, the docs plugin puts its routes under `/docs`; the blog plugin, `/blog`; and the pages plugin, `/`. You can think about the route structure like this: @@ -42,13 +42,13 @@ Changing `routeBasePath` can effectively alter your site's route structure. For Next, let's look at how the three plugins structure their own "boxes of subroutes". -### Pages routing {#pages-routing} +### Pages routing {/* #pages-routing */} Pages routing are straightforward: the file paths directly map to URLs, without any other way to customize. See the [pages docs](../guides/creating-pages.mdx#routing) for more information. The component used for Markdown pages is `@theme/MDXPage`. React pages are directly used as the route's component. -### Blog routing {#blog-routing} +### Blog routing {/* #blog-routing */} The blog creates the following routes: @@ -70,7 +70,7 @@ The blog creates the following routes: - The route is customizable through the `archiveBasePath` option. - The component is `@theme/BlogArchivePage`. -### Docs routing {#docs-routing} +### Docs routing {/* #docs-routing */} The docs is the only plugin that creates **nested routes**. At the top, it registers [**version paths**](../guides/docs/versioning.mdx): `/`, `/next`, `/2.0.0-beta.13`... which provide the version context, including the layout and sidebar. This ensures that when switching between individual docs, the sidebar's state is preserved, and that you can switch between versions through the navbar dropdown while staying on the same doc. The component used is `@theme/DocPage`. @@ -87,7 +87,7 @@ The individual docs are rendered in the remaining space after the navbar, footer The doc's `slug` front matter customizes the last part of the route, but the base route is always defined by the plugin's `routeBasePath` and the version's `path`. -### File paths and URL paths {#file-paths-and-url-paths} +### File paths and URL paths {/* #file-paths-and-url-paths */} Throughout the documentation, we always try to be unambiguous about whether we are talking about file paths or URL paths. Content plugins usually map file paths directly to URL paths, for example, `./docs/advanced/routing.md` will become `/docs/advanced/routing`. However, with `slug`, you can make URLs totally decoupled from the file structure. @@ -146,7 +146,7 @@ The following directory structure may help you visualize this file → URL mappi So much about content plugins. Let's take one step back and talk about how routing works in a Docusaurus app in general. -## Routes become HTML files {#routes-become-html-files} +## Routes become HTML files {/* #routes-become-html-files */} Because Docusaurus is a server-side rendering framework, all routes generated will be server-side rendered into static HTML files. If you are familiar with the behavior of HTTP servers like [Apache2](https://httpd.apache.org/docs/trunk/getting-started.html), you will understand how this is done: when the browser sends a request to the route `/docs/advanced/routing`, the server interprets that as request for the HTML file `/docs/advanced/routing/index.html`, and returns that. @@ -220,7 +220,7 @@ For example, the emitted HTML would contain links like ` ``` -## Escaping from SPA redirects {#escaping-from-spa-redirects} +## Escaping from SPA redirects {/* #escaping-from-spa-redirects */} Docusaurus builds a [single-page application](https://developer.mozilla.org/en-US/docs/Glossary/SPA), where route transitions are done through the `history.push()` method of React router. This operation is done on the client side. However, the prerequisite for a route transition to happen this way is that the target URL is known to our router. Otherwise, the router catches this path and displays a 404 page instead. diff --git a/website/docs/advanced/ssg.mdx b/website/docs/advanced/ssg.mdx index 07931249bbc8..fdf27298ea66 100644 --- a/website/docs/advanced/ssg.mdx +++ b/website/docs/advanced/ssg.mdx @@ -102,7 +102,7 @@ export default function expensiveComp() { ``` -## Understanding SSR {#understanding-ssr} +## Understanding SSR {/* #understanding-ssr */} React is not just a dynamic UI runtime—it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs. @@ -112,7 +112,7 @@ In CSR-only apps, all DOM elements are generated on client side with React, and Note that Docusaurus is ultimately a single-page application, so static site generation is only an optimization (_progressive enhancement_, as it's called), but our functionality does not fully depend on those HTML files. This is contrary to site generators like [Jekyll](https://jekyllrb.com/) and [Docusaurus v1](https://v1.docusaurus.io/), where all files are statically transformed to markup, and interactiveness is added through external JavaScript linked with `