@docusaurus/plugin-content-docs 0.0.0-4788 → 0.0.0-4792

package/src/sidebars/processor.ts

@@ -5,7 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {DocMetadataBase, VersionMetadata} from '../types';
+import type {
+  DocMetadataBase,
+  VersionMetadata,
+} from '@docusaurus/plugin-content-docs';
 import type {
   NormalizedSidebarItem,
   NormalizedSidebar,

package/src/sidebars/types.ts

@@ -6,11 +6,12 @@
  */
 
 import type {Optional, Required} from 'utility-types';
-import type {DocMetadataBase, VersionMetadata} from '../types';
 import type {
   NumberPrefixParser,
   SidebarOptions,
   CategoryIndexMatcher,
+  DocMetadataBase,
+  VersionMetadata,
 } from '@docusaurus/plugin-content-docs';
 import type {Slugger} from '@docusaurus/utils';
 
@@ -199,16 +200,6 @@ export type PropSidebarBreadcrumbsItem =
   | PropSidebarItemLink
   | PropSidebarItemCategory;
 
-export type PropVersionDoc = {
-  id: string;
-  title: string;
-  description?: string;
-  sidebar?: string;
-};
-export type PropVersionDocs = {
-  [docId: string]: PropVersionDoc;
-};
-
 export type CategoryMetadataFile = {
   label?: string;
   position?: number;
@@ -243,11 +234,20 @@ export type SidebarItemsGeneratorVersion = Pick<
 >;
 
 export type SidebarItemsGeneratorArgs = {
+  /** The sidebar item with type "autogenerated" to be transformed. */
   item: SidebarItemAutogenerated;
+  /** Useful metadata for the version this sidebar belongs to. */
   version: SidebarItemsGeneratorVersion;
+  /** All the docs of that version (unfiltered). */
   docs: SidebarItemsGeneratorDoc[];
+  /** Number prefix parser configured for this plugin. */
   numberPrefixParser: NumberPrefixParser;
+  /** The default category index matcher which you can override. */
   isCategoryIndex: CategoryIndexMatcher;
+  /**
+   * key is the path relative to the doc content directory, value is the
+   * category metadata file's content.
+   */
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile};
 };
 export type SidebarItemsGenerator = (
@@ -258,6 +258,10 @@ export type SidebarItemsGenerator = (
 // default sidebar gen logic
 // see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
 export type SidebarItemsGeneratorOptionArgs = {
+  /**
+   * Useful to re-use/enhance the default sidebar generation logic from
+   * Docusaurus.
+   */
   defaultSidebarItemsGenerator: SidebarItemsGenerator;
 } & SidebarItemsGeneratorArgs;
 export type SidebarItemsGeneratorOption = (

package/src/sidebars/utils.ts

@@ -21,7 +21,10 @@ import type {
 
 import _ from 'lodash';
 import {toMessageRelativeFilePath} from '@docusaurus/utils';
-import type {DocMetadataBase, DocNavLink} from '../types';
+import type {
+  DocMetadataBase,
+  PropNavigationLink,
+} from '@docusaurus/plugin-content-docs';
 
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
@@ -346,7 +349,7 @@ Available document ids are:
   };
 }
 
-export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
+export function toDocNavigationLink(doc: DocMetadataBase): PropNavigationLink {
   const {
     title,
     permalink,
@@ -361,7 +364,7 @@ export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
 export function toNavigationLink(
   navigationItem: SidebarNavigationItem | undefined,
   docsById: {[docId: string]: DocMetadataBase},
-): DocNavLink | undefined {
+): PropNavigationLink | undefined {
   function getDocById(docId: string) {
     const doc = docsById[docId];
     if (!doc) {

package/src/slug.ts

@@ -15,9 +15,11 @@ import {
   DefaultNumberPrefixParser,
   stripPathNumberPrefixes,
 } from './numberPrefix';
-import type {DocMetadataBase} from './types';
 import {isCategoryIndex, toCategoryIndexMatcherParam} from './docs';
-import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
+import type {
+  NumberPrefixParser,
+  DocMetadataBase,
+} from '@docusaurus/plugin-content-docs';
 
 export default function getSlug({
   baseID,

package/src/tags.ts

@@ -6,13 +6,14 @@
  */
 
 import {groupTaggedItems} from '@docusaurus/utils';
-import type {VersionTags, DocMetadata} from './types';
+import type {VersionTags} from './types';
+import type {DocMetadata} from '@docusaurus/plugin-content-docs';
 import _ from 'lodash';
 
 export function getVersionTags(docs: DocMetadata[]): VersionTags {
   const groups = groupTaggedItems(docs, (doc) => doc.tags);
   return _.mapValues(groups, (group) => ({
-    name: group.tag.label,
+    label: group.tag.label,
     docIds: group.items.map((item) => item.id),
     permalink: group.tag.permalink,
   }));

package/src/translations.ts

@@ -245,7 +245,7 @@ function translateSidebars(
 function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
   const versionTranslations: TranslationFileContent = {
     'version.label': {
-      message: version.versionLabel,
+      message: version.label,
       description: `The label for version ${version.versionName}`,
     },
   };
@@ -275,8 +275,7 @@ function translateVersion(
     translationFiles[getVersionFileName(version.versionName)]!.content;
   return {
     ...version,
-    versionLabel:
-      versionTranslations['version.label']?.message ?? version.versionLabel,
+    label: versionTranslations['version.label']?.message ?? version.label,
     sidebars: translateSidebars(version, versionTranslations),
     // docs: translateDocs(version.docs, versionTranslations),
   };

package/src/types.ts

@@ -8,13 +8,13 @@
 /// <reference types="@docusaurus/module-type-aliases" />
 
 import type {Sidebars} from './sidebars/types';
+import type {BrokenMarkdownLink, Tag} from '@docusaurus/utils';
 import type {
-  Tag,
-  FrontMatterTag,
-  BrokenMarkdownLink,
-  ContentPaths,
-} from '@docusaurus/utils';
-import type {VersionBanner} from '@docusaurus/plugin-content-docs';
+  VersionMetadata,
+  LastUpdateData,
+  DocMetadata,
+  CategoryGeneratedIndexMetadata,
+} from '@docusaurus/plugin-content-docs';
 
 export type DocFile = {
   contentPath: string; // /!\ may be localized
@@ -24,106 +24,19 @@ export type DocFile = {
   lastUpdate: LastUpdateData;
 };
 
-export type VersionMetadata = ContentPaths & {
-  versionName: string; // 1.0.0
-  versionLabel: string; // Version 1.0.0
-  versionPath: string; // /baseUrl/docs/1.0.0
-  tagsPath: string;
-  versionEditUrl?: string | undefined;
-  versionEditUrlLocalized?: string | undefined;
-  versionBanner: VersionBanner | null;
-  versionBadge: boolean;
-  versionClassName: string;
-  isLast: boolean;
-  sidebarFilePath: string | false | undefined; // versioned_sidebars/1.0.0.json
-  routePriority: number | undefined; // -1 for the latest docs
-};
-
-export type LastUpdateData = {
-  lastUpdatedAt?: number;
-  formattedLastUpdatedAt?: string;
-  lastUpdatedBy?: string;
-};
-
-export type DocFrontMatter = {
-  // Front matter uses snake case
-  id?: string;
-  title?: string;
-  tags?: FrontMatterTag[];
-  hide_title?: boolean;
-  hide_table_of_contents?: boolean;
-  keywords?: string[];
-  image?: string;
-  description?: string;
-  slug?: string;
-  sidebar_label?: string;
-  sidebar_position?: number;
-  sidebar_class_name?: string;
-  sidebar_custom_props?: {[key: string]: unknown};
-  displayed_sidebar?: string | null;
-  pagination_label?: string;
-  custom_edit_url?: string | null;
-  parse_number_prefixes?: boolean;
-  toc_min_heading_level?: number;
-  toc_max_heading_level?: number;
-  pagination_next?: string | null;
-  pagination_prev?: string | null;
-};
-
-export type DocMetadataBase = LastUpdateData & {
-  id: string; // TODO legacy versioned id => try to remove
-  unversionedId: string; // TODO new unversioned id => try to rename to "id"
-  version: string;
-  title: string;
-  description: string;
-  source: string; // @site aliased posix source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
-  sourceDirName: string; // posix path relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
-  slug: string;
-  permalink: string;
-  sidebarPosition?: number;
-  editUrl?: string | null;
-  tags: Tag[];
-  frontMatter: DocFrontMatter & {[key: string]: unknown};
-};
-
-export type DocNavLink = {
-  title: string;
-  permalink: string;
-};
-
-export type DocMetadata = DocMetadataBase & {
-  sidebar?: string;
-  previous?: DocNavLink;
-  next?: DocNavLink;
-};
-
-export type CategoryGeneratedIndexMetadata = {
-  title: string;
-  description?: string;
-  slug: string;
-  permalink: string;
-  sidebar: string;
-  previous?: DocNavLink;
-  next?: DocNavLink;
-  image?: string;
-  keywords?: string | readonly string[];
-};
-
 export type SourceToPermalink = {
   [source: string]: string;
 };
 
-export type VersionTag = {
-  name: string; // normalized name/label of the tag
-  docIds: string[]; // all doc ids having this tag
-  permalink: string; // pathname of the tag
+export type VersionTag = Tag & {
+  /** all doc ids having this tag. */
+  docIds: string[];
 };
 export type VersionTags = {
   [key: string]: VersionTag;
 };
 
 export type LoadedVersion = VersionMetadata & {
-  versionPath: string;
   mainDocId: string;
   docs: DocMetadata[];
   sidebars: Sidebars;

package/src/versions.ts

@@ -7,7 +7,6 @@
 
 import path from 'path';
 import fs from 'fs-extra';
-import type {VersionMetadata} from './types';
 import {
   VERSIONS_JSON_FILE,
   VERSIONED_DOCS_DIR,
@@ -17,8 +16,8 @@ import {
 import type {
   PluginOptions,
   VersionBanner,
-  VersionOptions,
   VersionsOptions,
+  VersionMetadata,
 } from '@docusaurus/plugin-content-docs';
 
 import type {LoadContext} from '@docusaurus/types';
@@ -207,7 +206,12 @@ function getVersionEditUrls({
   contentPath,
   contentPathLocalized,
   context: {siteDir, i18n},
-  options: {id, path: currentVersionPath, editUrl, editCurrentVersion},
+  options: {
+    id,
+    path: currentVersionPath,
+    editUrl: editUrlOption,
+    editCurrentVersion,
+  },
 }: {
   contentPath: string;
   contentPathLocalized: string;
@@ -216,15 +220,11 @@ function getVersionEditUrls({
     PluginOptions,
     'id' | 'path' | 'editUrl' | 'editCurrentVersion'
   >;
-}): {versionEditUrl: string; versionEditUrlLocalized: string} | undefined {
-  if (!editUrl) {
-    return undefined;
-  }
-
-  // if the user is using the functional form of editUrl,
-  // he has total freedom and we can't compute a "version edit url"
-  if (typeof editUrl === 'function') {
-    return undefined;
+}): Pick<VersionMetadata, 'editUrl' | 'editUrlLocalized'> {
+  // If the user is using the functional form of editUrl,
+  // she has total freedom and we can't compute a "version edit url"
+  if (!editUrlOption || typeof editUrlOption === 'function') {
+    return {editUrl: undefined, editUrlLocalized: undefined};
   }
 
   const editDirPath = editCurrentVersion ? currentVersionPath : contentPath;
@@ -244,16 +244,16 @@ function getVersionEditUrls({
     path.relative(siteDir, path.resolve(siteDir, editDirPathLocalized)),
   );
 
-  const versionEditUrl = normalizeUrl([editUrl, versionPathSegment]);
+  const editUrl = normalizeUrl([editUrlOption, versionPathSegment]);
 
-  const versionEditUrlLocalized = normalizeUrl([
-    editUrl,
+  const editUrlLocalized = normalizeUrl([
+    editUrlOption,
     versionPathSegmentLocalized,
   ]);
 
   return {
-    versionEditUrl,
-    versionEditUrlLocalized,
+    editUrl,
+    editUrlLocalized,
   };
 }
 
@@ -370,12 +370,12 @@ function createVersionMetadata({
   }
   const defaultVersionPathPart = getDefaultVersionPathPart();
 
-  const versionOptions: VersionOptions = options.versions[versionName] ?? {};
+  const versionOptions = options.versions[versionName] ?? {};
 
-  const versionLabel = versionOptions.label ?? defaultVersionLabel;
+  const label = versionOptions.label ?? defaultVersionLabel;
   const versionPathPart = versionOptions.path ?? defaultVersionPathPart;
 
-  const versionPath = normalizeUrl([
+  const routePath = normalizeUrl([
     context.baseUrl,
     options.routeBasePath,
     versionPathPart,
@@ -388,28 +388,27 @@ function createVersionMetadata({
     options,
   });
 
-  // Because /docs/:route` should always be after `/docs/versionName/:route`.
   const routePriority = versionPathPart === '' ? -1 : undefined;
 
   // the path that will be used to refer the docs tags
   // example below will be using /docs/tags
-  const tagsPath = normalizeUrl([versionPath, options.tagsBasePath]);
+  const tagsPath = normalizeUrl([routePath, options.tagsBasePath]);
 
   return {
     versionName,
-    versionLabel,
-    versionPath,
+    label,
+    path: routePath,
     tagsPath,
-    versionEditUrl: versionEditUrls?.versionEditUrl,
-    versionEditUrlLocalized: versionEditUrls?.versionEditUrlLocalized,
-    versionBanner: getVersionBanner({
+    editUrl: versionEditUrls.editUrl,
+    editUrlLocalized: versionEditUrls.editUrlLocalized,
+    banner: getVersionBanner({
       versionName,
       versionNames,
       lastVersionName,
       options,
     }),
-    versionBadge: getVersionBadge({versionName, versionNames, options}),
-    versionClassName: getVersionClassName({versionName, options}),
+    badge: getVersionBadge({versionName, versionNames, options}),
+    className: getVersionClassName({versionName, options}),
     isLast,
     routePriority,
     sidebarFilePath,
@@ -592,15 +591,3 @@ export async function readVersionsMetadata({
   );
   return versionsMetadata;
 }
-
-// order matter!
-// Read in priority the localized path, then the unlocalized one
-// We want the localized doc to "override" the unlocalized one
-export function getDocsDirPaths(
-  versionMetadata: Pick<
-    VersionMetadata,
-    'contentPath' | 'contentPathLocalized'
-  >,
-): [string, string] {
-  return [versionMetadata.contentPathLocalized, versionMetadata.contentPath];
-}