Plugin Configuration

/**
 * Main plugin factory function that creates a docs plugin instance
 * @param context - Docusaurus load context with site configuration
 * @param options - Plugin configuration options
 * @returns Promise resolving to configured plugin instance
 */
function pluginContentDocs(
  context: LoadContext,
  options: PluginOptions,
): Promise<Plugin<LoadedContent>>;

import pluginContentDocs from '@docusaurus/plugin-content-docs';
import type { Config } from '@docusaurus/types';

const config: Config = {
  plugins: [
    [
      pluginContentDocs,
      {
        id: 'default',
        path: 'docs',
        routeBasePath: 'docs',
        sidebarPath: './sidebars.js',
        editUrl: 'https://github.com/facebook/docusaurus/tree/main/website/',
        showLastUpdateTime: true,
        showLastUpdateAuthor: true,
        remarkPlugins: [],
        rehypePlugins: [],
        versions: {
          current: {
            label: 'Next',
            path: 'next',
          },
        },
      },
    ],
  ],
};

/**
 * Validates plugin options and applies defaults
 * @param args - Validation context with user options
 * @returns Validated and normalized plugin options
 */
function validateOptions(
  args: OptionValidationContext<Options | undefined, PluginOptions>
): PluginOptions;

interface PathOptions {
  /** Path to docs content directory relative to site directory */
  path: string;
  /** Path to sidebar configuration file, false to disable, undefined for autogenerated */
  sidebarPath?: string | false | undefined;
}

interface MetadataOptions extends TagsPluginOptions {
  /** URL route for docs section, without trailing slash */
  routeBasePath: string;
  /** Base URL for edit links or function for dynamic edit URLs */
  editUrl?: string | EditUrlFunction;
  /** Whether edit URL targets current version instead of older versions */
  editCurrentVersion: boolean;
  /** Whether edit URL targets localized files instead of original files */
  editLocalizedFiles: boolean;
  /** Display last update time for documents */
  showLastUpdateTime: boolean;
  /** Display last update author for documents */
  showLastUpdateAuthor: boolean;
  /** Custom number prefix parser or boolean to enable/disable */
  numberPrefixParser: NumberPrefixParser;
  /** Enable breadcrumbs on doc pages */
  breadcrumbs: boolean;
}

interface VersionsOptions {
  /** Default version displayed in navbar items */
  lastVersion?: string;
  /** Subset of versions to include */
  onlyIncludeVersions?: string[];
  /** Disable versioning even with multiple versions */
  disableVersioning: boolean;
  /** Include current version in build */
  includeCurrentVersion: boolean;
  /** Per-version customization options */
  versions: {[versionName: string]: VersionOptions};
}

interface VersionOptions {
  /** Version base path appended to baseUrl + routeBasePath */
  path?: string;
  /** Version label for badges and dropdowns */
  label?: string;
  /** Banner type to show at top of docs */
  banner?: 'none' | VersionBanner;
  /** Show version badge at top of each doc */
  badge?: boolean;
  /** Prevent search engine indexing */
  noIndex?: boolean;
  /** Custom CSS class for document HTML element */
  className?: string;
}

interface SidebarOptions {
  /** Whether sidebar categories are collapsible by default */
  sidebarCollapsible: boolean;
  /** Whether sidebar categories are collapsed by default */
  sidebarCollapsed: boolean;
}

interface ContentOptions {
  /** Glob patterns for included Markdown files */
  include: string[];
  /** Glob patterns for excluded Markdown files */
  exclude: string[];
  /** URL route for tags section */
  tagsBasePath: string;
}

interface ComponentOptions {
  /** Parent component for all docs plugin pages */
  docsRootComponent: string;
  /** Parent component for docs pages of individual version */
  docVersionRootComponent: string;
  /** Parent component for docs pages with sidebars */
  docRootComponent: string;
  /** Main doc container component */
  docItemComponent: string;
  /** Component for "docs with tag X" page */
  docTagDocListComponent: string;
  /** Component for tags list page */
  docTagsListComponent: string;
  /** Component for generated category index page */
  docCategoryGeneratedIndexComponent: string;
  /** Sidebar items generator function */
  sidebarItemsGenerator: SidebarItemsGeneratorOption;
}

interface MDXOptions {
  /** Remark plugins for markdown processing */
  remarkPlugins: RemarkPlugin[];
  /** Rehype plugins for HTML processing */
  rehypePlugins: RehypePlugin[];
  /** Recma plugins for React component processing */
  recmaPlugins: RecmaPlugin[];
  /** Remark plugins to run before default plugins */
  beforeDefaultRemarkPlugins: RemarkPlugin[];
  /** Rehype plugins to run before default plugins */
  beforeDefaultRehypePlugins: RehypePlugin[];
  /** Admonitions configuration */
  admonitions: boolean | AdmonitionsOptions;
}

const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
  path: 'docs',
  routeBasePath: 'docs',
  tagsBasePath: 'tags',
  include: ['**/*.{md,mdx}'],
  exclude: GlobExcludeDefault,
  sidebarItemsGenerator: DefaultSidebarItemsGenerator,
  numberPrefixParser: DefaultNumberPrefixParser,
  docsRootComponent: '@theme/DocsRoot',
  docVersionRootComponent: '@theme/DocVersionRoot',
  docRootComponent: '@theme/DocRoot',
  docItemComponent: '@theme/DocItem',
  docTagDocListComponent: '@theme/DocTagDocListPage',
  docTagsListComponent: '@theme/DocTagsListPage',
  docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
  remarkPlugins: [],
  rehypePlugins: [],
  recmaPlugins: [],
  beforeDefaultRemarkPlugins: [],
  beforeDefaultRehypePlugins: [],
  showLastUpdateTime: false,
  showLastUpdateAuthor: false,
  admonitions: true,
  includeCurrentVersion: true,
  disableVersioning: false,
  sidebarCollapsible: true,
  sidebarCollapsed: true,
  breadcrumbs: true,
};

interface LoadedContent {
  loadedVersions: LoadedVersion[];
}

interface LoadedVersion extends VersionMetadata {
  docs: DocMetadata[];
  drafts: DocMetadata[];
  sidebars: Sidebars;
}

interface VersionMetadata extends ContentPaths {
  versionName: string;
  label: string;
  path: string;
  tagsPath: string;
  editUrl?: string | undefined;
  editUrlLocalized?: string | undefined;
  banner: VersionBanner | null;
  badge: boolean;
  noIndex: boolean;
  className: string;
  isLast: boolean;
  sidebarFilePath: string | false | undefined;
  routePriority: number | undefined;
}

type VersionBanner = 'unreleased' | 'unmaintained';

interface EditUrlFunction {
  (params: {
    version: string;
    versionDocsDirPath: string;
    docPath: string;
    permalink: string;
    locale: string;
  }): string | undefined;
}

interface NumberPrefixParser {
  (filename: string): {
    filename: string;
    numberPrefix?: number;
  };
}