fix(v2): allow relative sidebar path resolution in docs:version command (#4861)

* fix(v2): allow relative sidebar path resolution in docs:version command

* factorize sidebarPath option resolution logic + dogfood

Co-authored-by: slorber <lorber.sebastien@gmail.com>

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

@@ -17,7 +17,7 @@ import {
   UnprocessedSidebarItem,
   UnprocessedSidebars,
 } from './types';
-import {loadSidebars} from './sidebars';
+import {loadSidebars, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 
 function createVersionedSidebarFile({
@@ -145,6 +145,7 @@ export function cliDocsVersionCommand(
 
   // Copy docs files.
   const docsDir = path.join(siteDir, docsPath);
+
   if (fs.existsSync(docsDir) && fs.readdirSync(docsDir).length > 0) {
     const versionedDir = getVersionedDocsDirPath(siteDir, pluginId);
     const newVersionDir = path.join(versionedDir, `version-${version}`);
@@ -153,7 +154,12 @@ export function cliDocsVersionCommand(
     throw new Error(`${pluginIdLogPrefix}There is no docs to version !`);
   }
 
-  createVersionedSidebarFile({siteDir, pluginId, version, sidebarPath});
+  createVersionedSidebarFile({
+    siteDir,
+    pluginId,
+    version,
+    sidebarPath: resolveSidebarPathOption(siteDir, sidebarPath),
+  });
 
   // Update versions.json file.
   versions.unshift(version);

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

@@ -25,11 +25,13 @@ import {
   SidebarItemsGeneratorVersion,
   NumberPrefixParser,
   SidebarItemsGeneratorOption,
+  PluginOptions,
 } from './types';
 import {mapValues, flatten, flatMap, difference, pick, memoize} from 'lodash';
 import {getElementsAround} from '@docusaurus/utils';
 import combinePromises from 'combine-promises';
 import {DefaultSidebarItemsGenerator} from './sidebarItemsGenerator';
+import path from 'path';
 
 type SidebarItemCategoryJSON = SidebarItemBase & {
   type: 'category';
@@ -256,7 +258,19 @@ export const DefaultSidebars: UnprocessedSidebars = {
 
 export const DisabledSidebars: UnprocessedSidebars = {};
 
+// If a path is provided, make it absolute
+// use this before loadSidebars()
+export function resolveSidebarPathOption(
+  siteDir: string,
+  sidebarPathOption: PluginOptions['sidebarPath'],
+): PluginOptions['sidebarPath'] {
+  return sidebarPathOption
+    ? path.resolve(siteDir, sidebarPathOption)
+    : sidebarPathOption;
+}
+
 // TODO refactor: make async
+// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 export function loadSidebars(
   sidebarFilePath: string | false | undefined,
 ): UnprocessedSidebars {
@@ -279,6 +293,7 @@ export function loadSidebars(
 
   // We don't want sidebars to be cached because of hot reloading.
   const sidebarJson = importFresh(sidebarFilePath) as SidebarsJSON;
+
   return normalizeSidebars(sidebarJson);
 }
 

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

@@ -24,6 +24,7 @@ import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 import {LoadContext} from '@docusaurus/types';
 import {getPluginI18nPath, normalizeUrl, posixPath} from '@docusaurus/utils';
 import {difference} from 'lodash';
+import {resolveSidebarPathOption} from './sidebars';
 
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir: string, pluginId: string): string {
@@ -184,9 +185,7 @@ function getVersionMetadataPaths({
 
   function getSidebarFilePath() {
     if (isCurrentVersion) {
-      return options.sidebarPath
+      return resolveSidebarPathOption(context.siteDir, options.sidebarPath);
-        ? path.resolve(context.siteDir, options.sidebarPath)
-        : options.sidebarPath;
     } else {
       return path.join(
         getVersionedSidebarsDirPath(context.siteDir, options.id),

website/docusaurus.config.js

@@ -235,7 +235,7 @@ const isVersioningDisabled = !!process.env.DISABLE_VERSIONING || isI18nStaging;
         docs: {
           // routeBasePath: '/',
           path: 'docs',
-          sidebarPath: require.resolve('./sidebars.js'),
+          sidebarPath: 'sidebars.js',
           editUrl: ({locale, docPath}) => {
             if (locale !== 'en') {
               return `https://crowdin.com/project/docusaurus-v2/${locale}`;