@docusaurus/plugin-content-docs 2.0.0-beta.14 → 2.0.0-beta.15

package/src/client/docsClientUtils.ts

@@ -7,21 +7,18 @@
 
 import {matchPath} from '@docusaurus/router';
 
-import {GlobalPluginData, GlobalVersion, GlobalDoc} from '../types';
+import type {
+  GlobalPluginData,
+  GlobalVersion,
+  GlobalDoc,
+  GetActivePluginOptions,
+  ActivePlugin,
+  ActiveDocContext,
+  DocVersionSuggestions,
+} from '@docusaurus/plugin-content-docs/client';
 
 // This code is not part of the api surface, not in ./theme on purpose
 
-// Short/convenient type aliases
-type Version = GlobalVersion;
-type Doc = GlobalDoc;
-
-export type ActivePlugin = {
-  pluginId: string;
-  pluginData: GlobalPluginData;
-};
-
-export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
-
 // get the data of the plugin that is currently "active"
 // ie the docs of that plugin are currently browsed
 // it is useful to support multiple docs plugin instances
@@ -30,14 +27,17 @@ export function getActivePlugin(
   pathname: string,
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined {
-  const activeEntry = Object.entries(allPluginDatas).find(
-    ([_id, pluginData]) =>
-      !!matchPath(pathname, {
-        path: pluginData.path,
-        exact: false,
-        strict: false,
-      }),
-  );
+  const activeEntry = Object.entries(allPluginDatas)
+    // A quick route sorting: '/android/foo' should match '/android' instead of '/'
+    .sort((a, b) => b[1].path.localeCompare(a[1].path))
+    .find(
+      ([, pluginData]) =>
+        !!matchPath(pathname, {
+          path: pluginData.path,
+          exact: false,
+          strict: false,
+        }),
+    );
 
   const activePlugin: ActivePlugin | undefined = activeEntry
     ? {pluginId: activeEntry[0], pluginData: activeEntry[1]}
@@ -56,13 +56,7 @@ export function getActivePlugin(
   return activePlugin;
 }
 
-export type ActiveDocContext = {
-  activeVersion?: Version;
-  activeDoc?: Doc;
-  alternateDocVersions: Record<string, Doc>;
-};
-
-export const getLatestVersion = (data: GlobalPluginData): Version =>
+export const getLatestVersion = (data: GlobalPluginData): GlobalVersion =>
   data.versions.find((version) => version.isLast)!;
 
 // Note: return undefined on doc-unrelated pages,
@@ -70,7 +64,7 @@ export const getLatestVersion = (data: GlobalPluginData): Version =>
 export const getActiveVersion = (
   data: GlobalPluginData,
   pathname: string,
-): Version | undefined => {
+): GlobalVersion | undefined => {
   const lastVersion = getLatestVersion(data);
   // Last version is a route like /docs/*,
   // we need to try to match it last or it would match /docs/version-1.0/* as well
@@ -127,13 +121,6 @@ export const getActiveDocContext = (
   };
 };
 
-export type DocVersionSuggestions = {
-  // suggest the latest version
-  latestVersionSuggestion: GlobalVersion;
-  // suggest the same doc, in latest version (if exist)
-  latestDocSuggestion?: GlobalDoc;
-};
-
 export const getDocVersionSuggestions = (
   data: GlobalPluginData,
   pathname: string,

package/src/{theme/hooks/useDocs.ts → client/globalDataHooks.ts}

@@ -11,18 +11,21 @@ import useGlobalData, {
   usePluginData,
 } from '@docusaurus/useGlobalData';
 
-import {GlobalPluginData, GlobalVersion} from '../../types';
 import {
   getActivePlugin,
   getLatestVersion,
   getActiveVersion,
   getActiveDocContext,
   getDocVersionSuggestions,
+} from './docsClientUtils';
+import type {
+  GlobalPluginData,
+  GlobalVersion,
   ActivePlugin,
   ActiveDocContext,
   DocVersionSuggestions,
   GetActivePluginOptions,
-} from '../../client/docsClientUtils';
+} from '@docusaurus/plugin-content-docs/client';
 
 // Important to use a constant object to avoid React useEffect executions etc...,
 // see https://github.com/facebook/docusaurus/issues/5089
@@ -37,6 +40,7 @@ export const useAllDocsData = (): Record<string, GlobalPluginData> =>
 export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
   usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData;
 
+// TODO this feature should be provided by docusaurus core
 export const useActivePlugin = (
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined => {

package/src/client/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export * from './globalDataHooks';

package/src/docFrontMatter.ts

@@ -6,7 +6,7 @@
  */
 
 import {
-  JoiFrontMatter as Joi, // Custom instance for frontmatter
+  JoiFrontMatter as Joi, // Custom instance for front matter
   URISchema,
   FrontMatterTagsSchema,
   FrontMatterTOCHeadingLevels,
@@ -30,6 +30,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
   sidebar_class_name: Joi.string(),
+  displayed_sidebar: Joi.string().allow(null),
   tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),
   custom_edit_url: URISchema.allow('', null),

package/src/docs.ts

@@ -8,7 +8,7 @@
 import path from 'path';
 import fs from 'fs-extra';
 import logger from '@docusaurus/logger';
-import {keyBy, last} from 'lodash';
+import {keyBy} from 'lodash';
 import {
   aliasedSitePath,
   getEditUrl,
@@ -22,14 +22,12 @@ import {
 import type {LoadContext} from '@docusaurus/types';
 
 import {getFileLastUpdate} from './lastUpdate';
-import {
+import type {
   DocFile,
   DocMetadataBase,
   DocMetadata,
   DocNavLink,
   LastUpdateData,
-  MetadataOptions,
-  PluginOptions,
   VersionMetadata,
   LoadedVersion,
 } from './types';
@@ -38,11 +36,14 @@ import {CURRENT_VERSION_NAME} from './constants';
 import {getDocsDirPaths} from './versions';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {validateDocFrontMatter} from './docFrontMatter';
-import {
-  SidebarsUtils,
-  toDocNavigationLink,
-  toNavigationLink,
-} from './sidebars/utils';
+import type {SidebarsUtils} from './sidebars/utils';
+import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
+import type {
+  MetadataOptions,
+  PluginOptions,
+  CategoryIndexMatcher,
+  CategoryIndexMatcherParam,
+} from '@docusaurus/plugin-content-docs';
 
 type LastUpdateOptions = Pick<
   PluginOptions,
@@ -139,7 +140,7 @@ function doProcessDocMetadata({
     custom_edit_url: customEditURL,
 
     // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
-    // but allow to disable this behavior with frontmatter
+    // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
 
@@ -163,7 +164,7 @@ function doProcessDocMetadata({
     throw new Error(`Document id "${baseID}" cannot include slash.`);
   }
 
-  // For autogenerated sidebars, sidebar position can come from filename number prefix or frontmatter
+  // For autogenerated sidebars, sidebar position can come from filename number prefix or front matter
   const sidebarPosition: number | undefined =
     frontMatter.sidebar_position ?? numberPrefix;
 
@@ -176,7 +177,7 @@ function doProcessDocMetadata({
       : `version-${versionMetadata.versionName}`;
 
   // TODO legacy retrocompatibility
-  // I think it's bad to affect the frontmatter id with the dirname?
+  // I think it's bad to affect the front matter id with the dirname?
   function computeDirNameIdPrefix() {
     if (sourceDirName === '.') {
       return undefined;
@@ -199,7 +200,7 @@ function doProcessDocMetadata({
     baseID,
     source,
     sourceDirName,
-    frontmatterSlug: frontMatter.slug,
+    frontMatterSlug: frontMatter.slug,
     stripDirNumberPrefixes: parseNumberPrefixes,
     numberPrefixParser: options.numberPrefixParser,
   });
@@ -296,6 +297,7 @@ export function addDocNavigation(
     const navigation = sidebarsUtils.getDocNavigation(
       doc.unversionedId,
       doc.id,
+      doc.frontMatter.displayed_sidebar,
     );
 
     const toNavigationLinkByDocId = (
@@ -367,31 +369,62 @@ export function getMainDocId({
   return getMainDoc().unversionedId;
 }
 
-function getLastPathSegment(str: string): string {
-  return last(str.split('/'))!;
-}
-
 // By convention, Docusaurus considers some docs are "indexes":
 // - index.md
 // - readme.md
 // - <folder>/<folder>.md
 //
+// This function is the default implementation of this convention
+//
 // Those index docs produce a different behavior
 // - Slugs do not end with a weird "/index" suffix
 // - Auto-generated sidebar categories link to them as intro
-export function isConventionalDocIndex(doc: {
-  source: DocMetadataBase['slug'];
-  sourceDirName: DocMetadataBase['sourceDirName'];
-}): boolean {
-  // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
-  const docName = path.parse(doc.source).name;
-
-  // "folder/subFolder/subSubFolder" => "subSubFolder"
-  const lastDirName = getLastPathSegment(doc.sourceDirName);
-
-  const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
+export const isCategoryIndex: CategoryIndexMatcher = ({
+  fileName,
+  directories,
+}): boolean => {
+  const eligibleDocIndexNames = [
+    'index',
+    'readme',
+    directories[0]?.toLowerCase(),
+  ];
+  return eligibleDocIndexNames.includes(fileName.toLowerCase());
+};
+
+export function toCategoryIndexMatcherParam({
+  source,
+  sourceDirName,
+}: Pick<
+  DocMetadataBase,
+  'source' | 'sourceDirName'
+>): CategoryIndexMatcherParam {
+  // source + sourceDirName are always posix-style
+  return {
+    fileName: path.posix.parse(source).name,
+    extension: path.posix.parse(source).ext,
+    directories: sourceDirName.split(path.posix.sep).reverse(),
+  };
+}
 
-  return eligibleDocIndexNames.includes(docName.toLowerCase());
+/**
+ * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ */
+export function splitPath(str: string): {
+  /**
+   * The list of directories, from lowest level to highest.
+   * If there's no dir name, directories is ['.']
+   */
+  directories: string[];
+  /** The file name, without extension */
+  fileName: string;
+  /** The extension, with a leading dot */
+  extension: string;
+} {
+  return {
+    fileName: path.parse(str).name,
+    extension: path.parse(str).ext,
+    directories: path.dirname(str).split(path.sep).reverse(),
+  };
 }
 
 // Return both doc ids

package/src/globalData.ts

@@ -5,12 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {mapValues} from 'lodash';
+import {normalizeUrl} from '@docusaurus/utils';
+import type {Sidebars} from './sidebars/types';
+import {createSidebarsUtils} from './sidebars/utils';
 import type {
+  CategoryGeneratedIndexMetadata,
   DocMetadata,
-  GlobalDoc,
   LoadedVersion,
-  GlobalVersion,
 } from './types';
+import type {
+  GlobalVersion,
+  GlobalSidebar,
+  GlobalDoc,
+} from '@docusaurus/plugin-content-docs/client';
 
 export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
@@ -20,6 +28,41 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
+export function toGlobalDataGeneratedIndex(
+  doc: CategoryGeneratedIndexMetadata,
+): GlobalDoc {
+  return {
+    id: doc.slug,
+    path: doc.permalink,
+    sidebar: doc.sidebar,
+  };
+}
+
+export function toGlobalSidebars(
+  sidebars: Sidebars,
+  version: LoadedVersion,
+): Record<string, GlobalSidebar> {
+  const {getFirstLink} = createSidebarsUtils(sidebars);
+  return mapValues(sidebars, (sidebar, sidebarId) => {
+    const firstLink = getFirstLink(sidebarId);
+    if (!firstLink) {
+      return {};
+    }
+    return {
+      link: {
+        path:
+          firstLink.type === 'generated-index'
+            ? normalizeUrl([version.versionPath, firstLink.slug])
+            : version.docs.find(
+                (doc) =>
+                  doc.id === firstLink.id || doc.unversionedId === firstLink.id,
+              )!.permalink,
+        label: firstLink.label,
+      },
+    };
+  });
+}
+
 export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
   return {
     name: version.versionName,
@@ -27,6 +70,9 @@ export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
     isLast: version.isLast,
     path: version.versionPath,
     mainDocId: version.mainDocId,
-    docs: version.docs.map(toGlobalDataDoc),
+    docs: version.docs
+      .map(toGlobalDataDoc)
+      .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+    sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }

package/src/index.ts

@@ -29,12 +29,10 @@ import {
 } from './docs';
 import {getDocsDirPaths, readVersionsMetadata} from './versions';
 
-import {
-  PluginOptions,
+import type {
   LoadedContent,
   SourceToPermalink,
   DocMetadataBase,
-  GlobalPluginData,
   VersionMetadata,
   LoadedVersion,
   DocFile,
@@ -54,17 +52,21 @@ import {
 import logger from '@docusaurus/logger';
 import {getVersionTags} from './tags';
 import {createVersionRoutes} from './routes';
-import type {PropTagsListPage} from '@docusaurus/plugin-content-docs';
+import type {
+  PropTagsListPage,
+  PluginOptions,
+} from '@docusaurus/plugin-content-docs';
+import type {GlobalPluginData} from '@docusaurus/plugin-content-docs/client';
 import {createSidebarsUtils} from './sidebars/utils';
 import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex';
 
-export default function pluginContentDocs(
+export default async function pluginContentDocs(
   context: LoadContext,
   options: PluginOptions,
-): Plugin<LoadedContent> {
+): Promise<Plugin<LoadedContent>> {
   const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context;
 
-  const versionsMetadata = readVersionsMetadata({context, options});
+  const versionsMetadata = await readVersionsMetadata({context, options});
 
   const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
 
@@ -79,14 +81,6 @@ export default function pluginContentDocs(
   return {
     name: 'docusaurus-plugin-content-docs',
 
-    getThemePath() {
-      return path.resolve(__dirname, './theme');
-    },
-
-    getTypeScriptThemePath() {
-      return path.resolve(__dirname, '..', 'src', 'theme');
-    },
-
     extendCli(cli) {
       const isDefaultPluginId = pluginId === DEFAULT_PLUGIN_ID;
 

package/src/lastUpdate.ts

@@ -43,12 +43,12 @@ export async function getFileLastUpdate(
       return null;
     }
 
-    const result = shell.exec(`git log -1 --format=%ct,%an ${filePath}`, {
+    const result = shell.exec(`git log -1 --format=%ct,%an "${filePath}"`, {
       silent: true,
     });
     if (result.code !== 0) {
       throw new Error(
-        `Retrieval of git history failed at ${filePath} with exit code ${result.code}: ${result.stderr}`,
+        `Retrieval of git history failed at "${filePath}" with exit code ${result.code}: ${result.stderr}`,
       );
     }
     return getTimestampAndAuthor(result.stdout.trim());

package/src/markdown/index.ts

@@ -6,7 +6,7 @@
  */
 
 import {linkify} from './linkify';
-import {DocsMarkdownOption} from '../types';
+import type {DocsMarkdownOption} from '../types';
 import type {LoaderContext} from 'webpack';
 
 export default function markdownLoader(

package/src/markdown/linkify.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocsMarkdownOption} from '../types';
+import type {DocsMarkdownOption} from '../types';
 import {getDocsDirPaths} from '../versions';
 import {replaceMarkdownLinks} from '@docusaurus/utils';
 

package/src/numberPrefix.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {NumberPrefixParser} from './types';
+import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
 
 // Best-effort to avoid parsing some patterns as number prefix
 const IgnoredPrefixPatterns = (function () {

package/src/options.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {PluginOptions} from './types';
+import type {PluginOptions} from '@docusaurus/plugin-content-docs';
 import {
   Joi,
   RemarkPluginsSchema,

package/src/plugin-content-docs.d.ts

@@ -6,14 +6,85 @@
  */
 
 declare module '@docusaurus/plugin-content-docs' {
-  export type Options = Partial<import('./types').PluginOptions>;
-  export type SidebarsConfig = import('./sidebars/types').SidebarsConfig;
-  export type VersionBanner = import('./types').VersionBanner;
-  type GlobalDataVersion = import('./types').GlobalVersion;
-  type GlobalDataDoc = import('./types').GlobalDoc;
-  type VersionTag = import('./types').VersionTag;
+  import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
+
+  export type NumberPrefixParser = (filename: string) => {
+    filename: string;
+    numberPrefix?: number;
+  };
+
+  export type CategoryIndexMatcherParam = {
+    fileName: string;
+    directories: string[];
+    extension: string;
+  };
+  export type CategoryIndexMatcher = (
+    param: CategoryIndexMatcherParam,
+  ) => boolean;
+
+  export type EditUrlFunction = (editUrlParams: {
+    version: string;
+    versionDocsDirPath: string;
+    docPath: string;
+    permalink: string;
+    locale: string;
+  }) => string | undefined;
+
+  export type MetadataOptions = {
+    routeBasePath: string;
+    editUrl?: string | EditUrlFunction;
+    editCurrentVersion: boolean;
+    editLocalizedFiles: boolean;
+    showLastUpdateTime?: boolean;
+    showLastUpdateAuthor?: boolean;
+    numberPrefixParser: NumberPrefixParser;
+  };
 
-  export type {GlobalDataVersion, GlobalDataDoc};
+  export type PathOptions = {
+    path: string;
+    sidebarPath?: string | false | undefined;
+  };
+
+  // TODO support custom version banner? {type: "error", content: "html content"}
+  export type VersionBanner = 'unreleased' | 'unmaintained';
+  export type VersionOptions = {
+    path?: string;
+    label?: string;
+    banner?: 'none' | VersionBanner;
+    badge?: boolean;
+    className?: string;
+  };
+  export type VersionsOptions = {
+    lastVersion?: string;
+    versions: Record<string, VersionOptions>;
+    onlyIncludeVersions?: string[];
+  };
+  export type SidebarOptions = {
+    sidebarCollapsible: boolean;
+    sidebarCollapsed: boolean;
+  };
+
+  export type PluginOptions = MetadataOptions &
+    PathOptions &
+    VersionsOptions &
+    RemarkAndRehypePluginOptions &
+    SidebarOptions & {
+      id: string;
+      include: string[];
+      exclude: string[];
+      docLayoutComponent: string;
+      docItemComponent: string;
+      docTagDocListComponent: string;
+      docTagsListComponent: string;
+      docCategoryGeneratedIndexComponent: string;
+      admonitions: Record<string, unknown>;
+      disableVersioning: boolean;
+      includeCurrentVersion: boolean;
+      sidebarItemsGenerator: import('./sidebars/types').SidebarItemsGeneratorOption;
+      tagsBasePath: string;
+    };
+  export type Options = Partial<PluginOptions>;
+  export type SidebarsConfig = import('./sidebars/types').SidebarsConfig;
 
   export type PropNavigationLink = {
     readonly title: string;
@@ -42,6 +113,8 @@ declare module '@docusaurus/plugin-content-docs' {
   export type PropCategoryGeneratedIndex = {
     title: string;
     description?: string;
+    image?: string;
+    keywords?: string | readonly string[];
     slug: string;
     permalink: string;
     navigation: PropNavigation;
@@ -238,17 +311,54 @@ declare module '@theme/Seo' {
   export default Seo;
 }
 
-declare module '@theme/hooks/useDocs' {
-  type GlobalPluginData = import('./types').GlobalPluginData;
-  type GlobalVersion = import('./types').GlobalVersion;
-  type ActivePlugin = import('./client/docsClientUtils').ActivePlugin;
-  type ActiveDocContext = import('./client/docsClientUtils').ActiveDocContext;
-  type DocVersionSuggestions =
-    import('./client/docsClientUtils').DocVersionSuggestions;
-  type GetActivePluginOptions =
-    import('./client/docsClientUtils').GetActivePluginOptions;
-
-  export type {GlobalPluginData, GlobalVersion};
+// TODO until TS supports exports field... hope it's in 4.6
+declare module '@docusaurus/plugin-content-docs/client' {
+  export type ActivePlugin = {
+    pluginId: string;
+    pluginData: GlobalPluginData;
+  };
+  export type ActiveDocContext = {
+    activeVersion?: GlobalVersion;
+    activeDoc?: GlobalDoc;
+    alternateDocVersions: Record<string, GlobalDoc>;
+  };
+  export type GlobalDoc = {
+    id: string;
+    path: string;
+    sidebar: string | undefined;
+  };
+
+  export type GlobalVersion = {
+    name: string;
+    label: string;
+    isLast: boolean;
+    path: string;
+    mainDocId: string; // home doc (if docs homepage configured), or first doc
+    docs: GlobalDoc[];
+    sidebars?: Record<string, GlobalSidebar>;
+  };
+
+  export type GlobalSidebarLink = {
+    label: string;
+    path: string;
+  };
+
+  export type GlobalSidebar = {
+    link?: GlobalSidebarLink;
+    // ... we may add other things here later
+  };
+  export type GlobalPluginData = {
+    path: string;
+    versions: GlobalVersion[];
+  };
+  export type DocVersionSuggestions = {
+    // suggest the latest version
+    latestVersionSuggestion: GlobalVersion;
+    // suggest the same doc, in latest version (if exist)
+    latestDocSuggestion?: GlobalDoc;
+  };
+  export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
+
   export const useAllDocsData: () => Record<string, GlobalPluginData>;
   export const useDocsData: (pluginId?: string) => GlobalPluginData;
   export const useActivePlugin: (