feat(v2): add a banner that links to latest version of documentation

packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts

@@ -163,6 +163,7 @@ describe('simple website', () => {
  source: path.join('@site', pluginPath, 'hello.md'),
  title: 'Hello, World !',
  description: 'Hi, Endilie here :)',
+ latestPermalink: undefined,
  });
 
  expect(docsMetadata['foo/bar']).toEqual({
@@ -176,6 +177,7 @@ describe('simple website', () => {
  source: path.join('@site', pluginPath, 'foo', 'bar.md'),
  title: 'Bar',
  description: 'This is custom description',
+ latestPermalink: undefined,
  });
 
  expect(docsSidebars).toMatchSnapshot();
@@ -335,6 +337,7 @@ describe('versioned website', () => {
  title: 'bar',
  permalink: '/docs/foo/bar',
  },
+ latestPermalink: undefined,
  });
  expect(docsMetadata['version-1.0.0/foo/baz']).toEqual({
  id: 'version-1.0.0/foo/baz',

packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts

@@ -50,13 +50,15 @@ describe('simple site', () => {
  source: path.join('@site', routeBasePath, sourceA),
  title: 'Bar',
  description: 'This is custom description',
+ latestPermalink: undefined,
  });
  expect(dataB).toEqual({
  id: 'hello',
  permalink: '/docs/hello',
  source: path.join('@site', routeBasePath, sourceB),
  title: 'Hello, World !',
  description: `Hi, Endilie here :)`,
+ latestPermalink: undefined,
  });
  });
 
@@ -85,6 +87,7 @@ describe('simple site', () => {
  editUrl:
  'https://github.com/facebook/docusaurus/edit/master/website/docs/foo/baz.md',
  description: 'Images',
+ latestPermalink: undefined,
  });
  });
 
@@ -109,6 +112,7 @@ describe('simple site', () => {
  title: 'lorem',
  editUrl: 'https://github.com/customUrl/docs/lorem.md',
  description: 'Lorem ipsum.',
+ latestPermalink: undefined,
  });
 
  // unrelated frontmatter is not part of metadata
@@ -140,6 +144,7 @@ describe('simple site', () => {
  description: 'Lorem ipsum.',
  lastUpdatedAt: 1539502055,
  lastUpdatedBy: 'Author',
+ latestPermalink: undefined,
  });
  });
 
@@ -168,6 +173,7 @@ describe('simple site', () => {
  description: 'Lorem ipsum.',
  lastUpdatedAt: 1539502055,
  lastUpdatedBy: 'Author',
+ latestPermalink: undefined,
  });
  });
 

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -65,6 +65,18 @@ const DEFAULT_OPTIONS: PluginOptions = {
  admonitions: {},
 };
 
+function getHrefFromSideBar(sidebarItems: DocsSidebarItem[]): string | null {
+ for (let sidebarItem of sidebarItems) {
+ if (sidebarItem.type === 'category') {
+ const url = getHrefFromSideBar(sidebarItem.items);
+ if (url) return url;
+ } else {
+ return sidebarItem.href;
+ }
+ }
+ return null;
+}
+
 export default function pluginContentDocs(
  context: LoadContext,
  opts: Partial<PluginOptions>,
@@ -320,7 +332,6 @@ Available document ids=
  },
  {},
  );
-
  return {
  docsMetadata,
  docsDir,
@@ -368,7 +379,6 @@ Available document ids=
  const isDocsHomePage =
  metadataItem.id.replace(versionsRegex, '').replace(/^\//, '') ===
  options.homePageId;
-
  if (isDocsHomePage) {
  const versionDocsPathPrefix =
  (metadataItem?.version === versioning.latestVersion
@@ -384,6 +394,7 @@ Available document ids=
  homePageDocsRoutePath,
  versionDocsPathPrefix,
  ]);
+
  const docsBaseMetadataPath = await createData(
  `${docuHash(metadataItem.source)}-base.json`,
  JSON.stringify(docsBaseMetadata, null, 2),
@@ -461,6 +472,18 @@ Available document ids=
  Object.values(content.docsMetadata),
  'version',
  );
+ const rootUrl = options.homePageId
+ ? normalizeUrl([baseUrl, homePageDocsRoutePath])
+ : getHrefFromSideBar(
+ content.docsSidebars[`version-${versioning.latestVersion}/docs`],
+ );
+ if (!rootUrl) {
+ throw new Error('Bad sidebars file. No document linked');
+ }
+ Object.values(content.docsMetadata).forEach((docMetadata) => {
+ if (docMetadata.version !== versioning.latestVersion)
+ docMetadata.latestPermalink = rootUrl;
+ });
  await Promise.all(
  Object.keys(docsMetadataByVersion).map(async (version) => {
  const routes: RouteConfig[] = await genRoutes(

packages/docusaurus-plugin-content-docs/src/types.ts

@@ -118,6 +118,7 @@ export interface MetadataRaw extends LastUpdateData {
  sidebar_label?: string;
  editUrl?: string;
  version?: string;
+ latestPermalink?: string;
 }
 
 export interface Paginator {

packages/docusaurus-theme-classic/src/theme/DocItem/index.js

@@ -12,6 +12,7 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import DocPaginator from '@theme/DocPaginator';
 import useTOCHighlight from '@theme/hooks/useTOCHighlight';
+import Link from '@docusaurus/Link';
 
 import clsx from 'clsx';
 import styles from './styles.module.css';
@@ -68,6 +69,7 @@ function DocItem(props) {
  lastUpdatedAt,
  lastUpdatedBy,
  version,
+ latestPermalink,
  } = metadata;
  const {
  frontMatter: {
@@ -108,6 +110,30 @@ function DocItem(props) {
  className={clsx('col', {
  [styles.docItemCol]: !hideTableOfContents,
  })}>
+ {latestPermalink && (
+ <div
+ className="alert alert--warning margin-bottom--md"
+ role="alert">
+ {version === 'next' ? (
+ <div>
+ This is unreleased documentation for {siteTitle}{' '}
+ <strong>{version}</strong> version.
+ </div>
+ ) : (
+ <div>
+ This is archived documentation for {siteTitle}{' '}
+ <strong>v{version}</strong>, which is no longer actively
+ maintained.
+ </div>
+ )}
+ <div className="margin-top--md">
+ For up-to-date documentation, see the{' '}
+ <strong>
+ <Link to={latestPermalink}>latest version</Link>.
+ </strong>
+ </div>
+ </div>
+ )}
  <div className={styles.docItemContainer}>
  <article>
  {version && (