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,