feat(website): make canary release page display actual canary version name (#7334)

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";
+
+<VersionsProvider>
+```
+
 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
+<InsertIfCanaryVersionUnknown>
+```
+
+:::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
+</InsertIfCanaryVersionUnknown>
+<InsertIfCanaryVersionKnown>
+```
+
+:::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
+</InsertIfCanaryVersionKnown>
+```
+
 ## 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: <StableVersion />)
+- `canary`: canary releases (<CanaryVersion />)
 
 :::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). <PublishTime />
 
 :::
 
@@ -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) (<CanaryVersion />).
 
 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
+<PackageJSONDiff />
 ```
 
 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
+</VersionsProvider>
+```

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<ContextValue | null>(null);
+
+export function VersionsProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const [canaryVersion, setCanaryVersion] = useState<ContextValue | null>(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 <Context.Provider value={canaryVersion}>{children}</Context.Provider>;
+}
+
+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 ? (
+    <span>
+      <Translate
+        description="The hint text for the current canary version tag."
+        values={{canaryVersionName: <b>{canaryVersion.name}</b>}}>
+        {'Current: {canaryVersionName}'}
+      </Translate>
+    </span>
+  ) : (
+    <span>
+      <Translate description="An example canary version tag when the actual version can't be fetched.">
+        Example: 0.0.0-4922
+      </Translate>
+    </span>
+  );
+}
+
+export function StableVersion(): JSX.Element {
+  const currentVersion = useStableVersion();
+  return <span>{currentVersion}</span>;
+}
+
+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 (
+    <CodeBlock language="diff">
+      {`-  "@docusaurus/core": "^${stableVersion}",
+-  "@docusaurus/preset-classic": "^${stableVersion}",
++  "@docusaurus/core": "${canaryVersion}",
++  "@docusaurus/preset-classic": "${canaryVersion}",
+`}
+    </CodeBlock>
+  );
+}
+
+export function PublishTime(): JSX.Element | null {
+  const time = useContext(Context)?.time;
+  if (!time) {
+    return null;
+  }
+  return (
+    <Translate values={{time: <code>{time}</code>}}>
+      {
+        "The latest canary version that's available on npm is published at {time}."
+      }
+    </Translate>
+  );
+}

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,