feat(v2): docs versioning ❄️🔥

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

@@ -230,32 +230,6 @@ describe('createOrder', () => {
     });
   });
 
-  test('multiple sidebars with unknown sidebar item type', () => {
-    expect(() =>
-      createOrder({
-        docs: [
-          {
-            type: 'category',
-            label: 'Category1',
-            items: [
-              {type: 'endi', id: 'doc1'},
-              {type: 'doc', id: 'doc2'},
-            ],
-          },
-        ],
-        otherDocs: [
-          {
-            type: 'category',
-            label: 'Category1',
-            items: [{type: 'doc', id: 'doc5'}],
-          },
-        ],
-      }),
-    ).toThrowErrorMatchingInlineSnapshot(
-      `"Unknown item type: endi. Item: {\\"type\\":\\"endi\\",\\"id\\":\\"doc1\\"}"`,
-    );
-  });
-
   test('edge cases', () => {
     expect(createOrder({})).toEqual({});
     expect(createOrder(undefined)).toEqual({});

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

@@ -14,6 +14,18 @@ import {
   VERSIONED_SIDEBARS_DIR,
 } from './constants';
 
+export function getVersionedDocsDir(siteDir: string) {
+  return path.join(siteDir, VERSIONED_DOCS_DIR);
+}
+
+export function getVersionedSidebarsDir(siteDir: string) {
+  return path.join(siteDir, VERSIONED_SIDEBARS_DIR);
+}
+
+export function getVersionsJSONFile(siteDir: string) {
+  return path.join(siteDir, VERSIONS_JSON_FILE);
+}
+
 export default function(siteDir: string): Env {
   const versioning: VersioningEnv = {
     enabled: false,
@@ -23,7 +35,7 @@ export default function(siteDir: string): Env {
     sidebarsDir: '',
   };
 
-  const versionsJSONFile = path.join(siteDir, VERSIONS_JSON_FILE);
+  const versionsJSONFile = getVersionsJSONFile(siteDir);
   if (fs.existsSync(versionsJSONFile)) {
     const parsedVersions = JSON.parse(
       fs.readFileSync(versionsJSONFile, 'utf8'),
@@ -32,8 +44,8 @@ export default function(siteDir: string): Env {
       versioning.latestVersion = parsedVersions[0];
       versioning.enabled = true;
       versioning.versions = parsedVersions;
-      (versioning.docsDir = path.join(siteDir, VERSIONED_DOCS_DIR)),
-        (versioning.sidebarsDir = path.join(siteDir, VERSIONED_SIDEBARS_DIR));
+      versioning.docsDir = getVersionedDocsDir(siteDir);
+      versioning.sidebarsDir = getVersionedSidebarsDir(siteDir);
     }
   }
 

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

@@ -37,6 +37,7 @@ import {
   VersionToSidebars,
 } from './types';
 import {Configuration} from 'webpack';
+import {docsVersion} from './version';
 
 const DEFAULT_OPTIONS: PluginOptions = {
   path: 'docs', // Path to data on filesystem, relative to site dir.
@@ -78,6 +79,16 @@ export default function pluginContentDocs(
   return {
     name: 'docusaurus-plugin-content-docs',
 
+    extendCli(cli) {
+      cli
+        .command('docs:version')
+        .arguments('<version>')
+        .description('Tag a new version for docs')
+        .action(version => {
+          docsVersion(version, siteDir, options);
+        });
+    },
+
     getPathsToWatch() {
       const {include} = options;
       let globPattern = include.map(pattern => `${docsDir}/${pattern}`);

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

@@ -5,13 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  Sidebar,
-  SidebarItem,
-  SidebarItemDoc,
-  SidebarItemCategory,
-  Order,
-} from './types';
+import {Sidebar, SidebarItem, Order} from './types';
 
 // Build the docs meta such as next, previous, category and sidebar.
 export default function createOrder(allSidebars: Sidebar = {}): Order {
@@ -26,20 +20,16 @@ export default function createOrder(allSidebars: Sidebar = {}): Order {
         switch (item.type) {
           case 'category':
             indexItems({
-              items: (item as SidebarItemCategory).items,
+              items: item.items,
             });
             break;
           case 'ref':
           case 'link':
             // Refs and links should not be shown in navigation.
             break;
           case 'doc':
-            ids.push((item as SidebarItemDoc).id);
+            ids.push(item.id);
             break;
-          default:
-            throw new Error(
-              `Unknown item type: ${item.type}. Item: ${JSON.stringify(item)}`,
-            );
         }
       });
     };

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

@@ -23,24 +23,24 @@ export interface PluginOptions extends MetadataOptions {
 }
 
 export type SidebarItemDoc = {
-  type: string;
+  type: 'doc' | 'ref';
   id: string;
 };
 
 export interface SidebarItemLink {
-  type: string;
+  type: 'link';
   href: string;
   label: string;
 }
 
 export interface SidebarItemCategory {
-  type: string;
+  type: 'category';
   label: string;
   items: SidebarItem[];
 }
 
 export interface SidebarItemCategoryRaw {
-  type: string;
+  type: 'category';
   label: string;
   items: SidebarItemRaw[];
 }
@@ -54,7 +54,11 @@ export type SidebarItemRaw =
   | string
   | SidebarItemDoc
   | SidebarItemLink
-  | SidebarItemCategoryRaw;
+  | SidebarItemCategoryRaw
+  | {
+      type: string;
+      [key: string]: any;
+    };
 
 // Sidebar given by user that is not normalized yet. e.g: sidebars.json
 export interface SidebarRaw {
@@ -68,7 +72,7 @@ export interface Sidebar {
 }
 
 export interface DocsSidebarItemCategory {
-  type: string;
+  type: 'category';
   label: string;
   items: (SidebarItemLink | DocsSidebarItemCategory)[];
 }
@@ -137,7 +141,7 @@ export interface VersionToSidebars {
 export interface LoadedContent {
   docsMetadata: DocsMetadata;
   docsDir: string;
-  docsSidebars: Sidebar;
+  docsSidebars: DocsSidebar;
   permalinkToSidebar: PermalinkToSidebar;
   versionToSidebars: VersionToSidebars;
 }

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

@@ -0,0 +1,113 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {
+  getVersionsJSONFile,
+  getVersionedDocsDir,
+  getVersionedSidebarsDir,
+} from './env';
+import fs from 'fs-extra';
+import path from 'path';
+import {PluginOptions, Sidebar, SidebarItemCategory} from './types';
+import loadSidebars from './sidebars';
+
+export function docsVersion(
+  version: string | null | undefined,
+  siteDir: string,
+  options: PluginOptions,
+) {
+  if (!version) {
+    throw new Error(
+      'No version number specified!.\nPass the version you wish to create as an argument.\nEx: 1.0.0',
+    );
+  }
+  if (version.includes('/')) {
+    throw new Error(
+      'Invalid version number specified! Do not include slash (/). Try something like: 1.0.0',
+    );
+  }
+
+  // Load existing versions
+  let versions = [];
+  const versionsJSONFile = getVersionsJSONFile(siteDir);
+  if (fs.existsSync(versionsJSONFile)) {
+    versions = JSON.parse(fs.readFileSync(versionsJSONFile, 'utf8'));
+  }
+
+  // Check if version already exist
+  if (versions.includes(version)) {
+    throw new Error(
+      'This version already exists!.\nSpecify a new version to create that does not already exist.',
+    );
+  }
+
+  const {path: docsPath, sidebarPath} = options;
+
+  // Copy docs files
+  const docsDir = path.join(siteDir, docsPath);
+  if (fs.existsSync(docsDir)) {
+    const versionedDir = getVersionedDocsDir(siteDir);
+    const newVersionDir = path.join(versionedDir, `version-${version}`);
+
+    fs.copy(docsDir, newVersionDir);
+  }
+
+  // Load current sidebar and create a new versioned sidebars file
+  if (fs.existsSync(sidebarPath)) {
+    const loadedSidebars: Sidebar = loadSidebars([sidebarPath]);
+
+    // Transform id in original sidebar to versioned id
+    const normalizeCategory = (
+      category: SidebarItemCategory,
+    ): SidebarItemCategory => {
+      const items = category.items.map(item => {
+        switch (item.type) {
+          case 'category':
+            return normalizeCategory(item);
+          case 'ref':
+          case 'doc':
+            return {
+              type: item.type,
+              id: `version-${version}/${item.id}`,
+            };
+        }
+        return item;
+      });
+      return {...category, items};
+    };
+
+    const versionedSidebar: Sidebar = Object.entries(loadedSidebars).reduce(
+      (acc: Sidebar, [sidebarId, sidebarItemCategories]) => {
+        const newVersionedSidebarId = `version-${version}/${sidebarId}`;
+        acc[
+          newVersionedSidebarId
+        ] = sidebarItemCategories.map(sidebarItemCategory =>
+          normalizeCategory(sidebarItemCategory),
+        );
+        return acc;
+      },
+      {},
+    );
+
+    const versionedSidebarsDir = getVersionedSidebarsDir(siteDir);
+    const newSidebarFile = path.join(
+      versionedSidebarsDir,
+      `version-${version}-sidebars.json`,
+    );
+    fs.writeFileSync(
+      newSidebarFile,
+      `${JSON.stringify(versionedSidebar, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  // update versions.json file
+  versions.unshift(version);
+  fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
+
+  console.log(`Version ${version} created!\n`);
+}