diff --git a/website/community/4-canary.md b/website/community/4-canary.md
index b81c11ea90fd..ed20512a9275 100644
--- a/website/community/4-canary.md
+++ b/website/community/4-canary.md
@@ -1,5 +1,19 @@
# Canary releases
+```mdx-code-block
+import {
+ VersionsProvider,
+ CanaryVersion,
+ StableVersion,
+ InsertIfCanaryVersionUnknown,
+ InsertIfCanaryVersionKnown,
+ PackageJSONDiff,
+ PublishTime,
+} from "./Versions.tsx";
+
+
+```
+
Docusaurus has a canary releases system.
It permits you to **test new unreleased features** as soon as the pull requests are merged.
@@ -14,18 +28,43 @@ A canary release passes all automated tests and is used in production by the Doc
:::
+```mdx-code-block
+
+```
+
+:::caution
+
+The canary version shown below **may not be up-to-date**. Please go to the [npm page](https://www.npmjs.com/package/@docusaurus/core?activeTab=versions) to find the actual version name.
+
+:::
+
+```mdx-code-block
+
+
+```
+
+:::tip
+
+The canary version shown below is directly fetched from npm and **is up-to-date**. You can directly use these numbers in your package.json.
+
+:::
+
+```mdx-code-block
+
+```
+
## 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.
You can see on [npm](https://www.npmjs.com/package/@docusaurus/core?activeTab=versions) the current dist tags:
-- `latest`: stable releases (example: `2.0.0-beta.9`)
-- `canary`: canary releases (example: `0.0.0-4222`)
+- `latest`: stable releases (Current: )
+- `canary`: canary releases ()
:::tip
-Make sure to use the latest canary release and check the publication date (sometimes the publish process fails).
+Make sure to use the latest canary release and check the publication date (sometimes the publish process fails).
:::
@@ -37,15 +76,12 @@ Canary versions follow the naming convention `0.0.0-commitNumber`.
## Using a canary release
-Take the latest version published under the [canary npm dist tag](https://www.npmjs.com/package/@docusaurus/core?activeTab=versions) (for example: `0.0.0-4222`).
+Take the latest version published under the [canary npm dist tag](https://www.npmjs.com/package/@docusaurus/core?activeTab=versions) ().
Use it for all the `@docusaurus/*` dependencies in your `package.json`:
-```diff
-- "@docusaurus/core": "^2.0.0-beta.9",
-- "@docusaurus/preset-classic": "^2.0.0-beta.9",
-+ "@docusaurus/core": "0.0.0-4222",
-+ "@docusaurus/preset-classic": "0.0.0-4222",
+```mdx-code-block
+
```
Then, install the dependencies again and start your site:
@@ -68,3 +104,7 @@ Make sure to include all the `@docusaurus/*` packages.
For canary releases, prefer using an exact version instead of a semver range (avoid the `^` prefix).
:::
+
+```mdx-code-block
+
+```
diff --git a/website/community/Versions.tsx b/website/community/Versions.tsx
new file mode 100644
index 000000000000..15464635e8b0
--- /dev/null
+++ b/website/community/Versions.tsx
@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {useContext, useEffect, useState, type ReactNode} from 'react';
+import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import {useVersions} from '@docusaurus/plugin-content-docs/client';
+import CodeBlock from '@theme/CodeBlock';
+import Translate from '@docusaurus/Translate';
+
+type ContextValue = {
+ name: string;
+ time: string;
+};
+
+const Context = React.createContext(null);
+
+export function VersionsProvider({
+ children,
+}: {
+ children: ReactNode;
+}): JSX.Element {
+ const [canaryVersion, setCanaryVersion] = useState(null);
+ useEffect(() => {
+ fetch('https://registry.npmjs.org/@docusaurus/core')
+ .then((res) => res.json())
+ .then((data) => {
+ const name = Object.keys(data.versions).at(-1)!;
+ const time = data.time[name];
+ setCanaryVersion({name, time});
+ });
+ }, []);
+ return {children};
+}
+
+function useStableVersion(): string {
+ const preferredVersion =
+ useDocsPreferredVersion('default').preferredVersion?.name;
+ const lastVersion = useVersions('default').find(
+ (v) => v.name !== 'current',
+ )!.name;
+ return preferredVersion && preferredVersion !== 'current'
+ ? preferredVersion
+ : lastVersion;
+}
+
+export function CanaryVersion(): JSX.Element {
+ const canaryVersion = useContext(Context);
+ // Show a sensible name
+ return canaryVersion ? (
+
+ {canaryVersion.name}}}>
+ {'Current: {canaryVersionName}'}
+
+
+ ) : (
+
+
+ Example: 0.0.0-4922
+
+
+ );
+}
+
+export function StableVersion(): JSX.Element {
+ const currentVersion = useStableVersion();
+ return {currentVersion};
+}
+
+export function InsertIfCanaryVersionUnknown({
+ children,
+}: {
+ children: ReactNode;
+}): ReactNode | null {
+ const canaryVersion = useContext(Context);
+ if (!canaryVersion) {
+ return children;
+ }
+ return null;
+}
+
+export function InsertIfCanaryVersionKnown({
+ children,
+}: {
+ children: ReactNode;
+}): ReactNode | null {
+ const canaryVersion = useContext(Context);
+ if (canaryVersion) {
+ return children;
+ }
+ return null;
+}
+
+export function PackageJSONDiff(): JSX.Element {
+ const canaryVersion = useContext(Context)?.name ?? '0.0.0-4922';
+ const stableVersion = useStableVersion();
+ return (
+
+ {`- "@docusaurus/core": "^${stableVersion}",
+- "@docusaurus/preset-classic": "^${stableVersion}",
++ "@docusaurus/core": "${canaryVersion}",
++ "@docusaurus/preset-classic": "${canaryVersion}",
+`}
+
+ );
+}
+
+export function PublishTime(): JSX.Element | null {
+ const time = useContext(Context)?.time;
+ if (!time) {
+ return null;
+ }
+ return (
+ {time}}}>
+ {
+ "The latest canary version that's available on npm is published at {time}."
+ }
+
+ );
+}
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index acaf0e57a1c1..e35a43104f43 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -162,6 +162,7 @@ const config = {
}
return `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`;
},
+ remarkPlugins: [npm2yarn],
editCurrentVersion: true,
sidebarPath: require.resolve('./sidebarsCommunity.js'),
showLastUpdateAuthor: true,