Sidebar System

/**
 * Loads and processes sidebars from configuration file
 * @param sidebarFilePath - Path to sidebar config file, false for disabled, undefined for autogenerated
 * @param options - Processing parameters including version metadata
 * @returns Promise resolving to processed sidebars
 */
function loadSidebars(
  sidebarFilePath: string | false | undefined,
  options: SidebarProcessorParams,
): Promise<Sidebars>;

/**
 * Loads raw sidebar configuration from file
 * @param sidebarFilePath - Path to sidebar configuration file
 * @returns Promise resolving to sidebar configuration object
 */
function loadSidebarsFile(
  sidebarFilePath: string | false | undefined,
): Promise<SidebarsConfig>;

/**
 * Resolves sidebar path option relative to site directory
 * @param siteDir - Site directory path
 * @param sidebarPathOption - Sidebar path option from plugin config
 * @returns Resolved absolute path or original option
 */
function resolveSidebarPathOption(
  siteDir: string,
  sidebarPathOption: PluginOptions['sidebarPath'],
): PluginOptions['sidebarPath'];

import { loadSidebars, loadSidebarsFile } from '@docusaurus/plugin-content-docs';

// Load and process sidebars
const sidebars = await loadSidebars('./sidebars.js', {
  version: versionMetadata,
  sidebarItemsGenerator: options.sidebarItemsGenerator,
  numberPrefixParser: options.numberPrefixParser,
  categoryLabelSlugger: slugger,
  docs: docsMetadata,
});

// Load raw sidebar configuration
const sidebarConfig = await loadSidebarsFile('./sidebars.js');

/** Default autogenerated sidebar configuration */
const DefaultSidebars: SidebarsConfig = {
  defaultSidebar: [
    {
      type: 'autogenerated',
      dirName: '.',
    },
  ],
};

/** Disabled sidebars configuration */
const DisabledSidebars: SidebarsConfig = {};

/**
 * Default sidebar items generator function
 * Creates sidebar items automatically from directory structure
 */
const DefaultSidebarItemsGenerator: SidebarItemsGeneratorOption;

/**
 * Normalizes sidebar configuration to standard format
 * @param sidebarsConfig - Raw sidebar configuration
 * @returns Normalized sidebar configuration
 */
function normalizeSidebars(sidebarsConfig: SidebarsConfig): NormalizedSidebarsConfig;

/**
 * Validates sidebar structure and configuration
 * @param sidebars - Normalized sidebar configuration
 * @throws Error if validation fails
 */
function validateSidebars(sidebars: NormalizedSidebarsConfig): void;

/**
 * Processes sidebars with metadata and generates final structure
 * @param sidebars - Normalized sidebar configuration
 * @param categoriesMetadata - Category metadata from filesystem
 * @param options - Processing parameters
 * @returns Promise resolving to processed sidebars
 */
function processSidebars(
  sidebars: NormalizedSidebarsConfig,
  categoriesMetadata: CategoryMetadata,
  options: SidebarProcessorParams,
): Promise<ProcessedSidebars>;

/**
 * Post-processes sidebars for final output
 * @param sidebars - Processed sidebars
 * @param options - Processing parameters
 * @returns Final sidebar structure
 */
function postProcessSidebars(
  sidebars: ProcessedSidebars,
  options: SidebarProcessorParams,
): Sidebars;

// sidebars.js
module.exports = {
  // Autogenerated sidebar
  docs: [
    {
      type: 'autogenerated',
      dirName: '.', // Generate from current directory
    },
  ],
  
  // Manual sidebar configuration
  api: [
    'intro',
    {
      type: 'category',
      label: 'Tutorial',
      items: ['tutorial-basics/create-a-page'],
    },
    {
      type: 'doc', 
      id: 'intro',
      label: 'Getting Started',
    },
  ],
};

// sidebars.js with complex structure
module.exports = {
  docs: [
    'introduction',
    {
      type: 'category',
      label: 'Getting Started',
      collapsed: false,
      items: [
        'installation',
        'configuration',
        {
          type: 'autogenerated',
          dirName: 'getting-started',
        },
      ],
    },
    {
      type: 'category',
      label: 'API Reference',
      link: {
        type: 'generated-index',
        title: 'API Reference',
        description: 'Complete API documentation',
        slug: '/api',
      },
      items: [
        {
          type: 'autogenerated',
          dirName: 'api',
        },
      ],
    },
    {
      type: 'link',
      label: 'External Link',
      href: 'https://example.com',
    },
  ],
};

# _category_.yml
label: 'Tutorial'
position: 2
collapsed: true
className: 'sidebar-tutorial'
customProps:
  description: 'Learn the basics'

// _category_.json
{
  "label": "Advanced Topics",
  "position": 10,
  "collapsed": false,
  "link": {
    "type": "generated-index",
    "title": "Advanced Topics Overview"
  }
}

interface SidebarItemDoc {
  type: 'doc';
  id: string;
  label?: string;
  className?: string;
  customProps?: Record<string, unknown>;
}

interface SidebarItemCategory {
  type: 'category';
  label: string;
  items: SidebarItem[];
  collapsed?: boolean;
  collapsible?: boolean;
  className?: string;
  customProps?: Record<string, unknown>;
  link?: SidebarItemCategoryLink;
}

interface SidebarItemCategoryLink {
  type: 'doc';
  id: string;
} | {
  type: 'generated-index';
  title?: string;
  description?: string;
  slug?: string;
  keywords?: string[];
  image?: string;
};

interface SidebarItemLink {
  type: 'link';
  label: string;
  href: string;
  className?: string;
  customProps?: Record<string, unknown>;
}

interface SidebarItemHtml {
  type: 'html';
  value: string;
  className?: string;
  customProps?: Record<string, unknown>;
}

interface SidebarItemAutogenerated {
  type: 'autogenerated';
  dirName: string;
}

/**
 * Creates comprehensive sidebar utility object
 * @param sidebars - Processed sidebars configuration
 * @returns Utility object with sidebar helper methods
 */
function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils;

/**
 * Comprehensive sidebar utilities for working with processed sidebars
 */
interface SidebarsUtils {
  /** The processed sidebars object */
  sidebars: Sidebars;
  
  /**
   * Get first document ID of first sidebar
   * @returns First doc ID or undefined if no sidebars/docs
   */
  getFirstDocIdOfFirstSidebar(): string | undefined;
  
  /**
   * Get sidebar name containing a specific document
   * @param docId - Document ID  
   * @returns Sidebar name or undefined
   */
  getSidebarNameByDocId(docId: string): string | undefined;
  
  /**
   * Get navigation data for a document
   * @param unlistedBehavior - How to handle unlisted docs
   * @param docsById - Map of doc IDs to metadata
   * @returns Navigation with previous/next links
   */
  getDocNavigation(params: {
    unlistedBehavior: 'draft' | 'hide';
    docsById: {[docId: string]: DocMetadata};
  }): SidebarNavigation;
  
  /**
   * Get list of category generated indices
   * @returns Array of categories with generated indices
   */
  getCategoryGeneratedIndexList(): SidebarItemCategoryWithGeneratedIndex[];
  
  /**
   * Get navigation for category generated index page
   * @param permalink - Permalink of the category index
   * @returns Navigation with previous/next links
   */
  getCategoryGeneratedIndexNavigation(permalink: string): SidebarNavigation;
  
  /**
   * Get first link in a sidebar
   * @param sidebarId - ID of sidebar to search
   * @returns First link result or undefined
   */
  getFirstLink(sidebarId: string): FirstLinkResult | undefined;
  
  /**
   * Check for legacy versioned sidebar names and warn
   * @param params - Validation parameters
   */
  checkLegacyVersionedSidebarNames(params: {
    sidebarFilePath: string | false | undefined;
    versionMetadata: VersionMetadata;
  }): void;
  
  /**
   * Check sidebar doc IDs against available docs
   * @param params - Validation parameters
   */
  checkSidebarsDocIds(params: {
    allDocIds: string[];
    sidebarFilePath: string | false | undefined;
    versionMetadata: VersionMetadata;
  }): void;
}

interface SidebarNavigation {
  previous?: PropNavigationLink;
  next?: PropNavigationLink;
}

interface FirstLinkResult {
  type: 'doc' | 'generated-index' | 'link';
  link: PropNavigationLink;
}

interface SidebarItemCategoryWithGeneratedIndex extends SidebarItemCategory {
  link: SidebarItemCategoryLinkGeneratedIndex;
}

/**
 * Transform sidebar items recursively
 * @param sidebar - Sidebar to transform
 * @param updateFn - Function to apply to each item
 * @returns Transformed sidebar
 */
function transformSidebarItems<T extends PropSidebarItem>(
  sidebar: readonly T[],
  updateFn: (item: T) => T
): T[];

/**
 * Collect all document items from sidebar
 * @param sidebar - Sidebar to search
 * @returns Array of document sidebar items
 */
function collectSidebarDocItems(sidebar: PropSidebar): SidebarItemDoc[];

/**
 * Collect all category items from sidebar
 * @param sidebar - Sidebar to search
 * @returns Array of category sidebar items
 */
function collectSidebarCategories(sidebar: PropSidebar): SidebarItemCategory[];

/**
 * Collect all link items from sidebar
 * @param sidebar - Sidebar to search
 * @returns Array of link sidebar items
 */
function collectSidebarLinks(sidebar: PropSidebar): SidebarItemLink[];

/**
 * Collect all document references from sidebar
 * @param sidebar - Sidebar to search
 * @returns Array of referenced document items
 */
function collectSidebarRefs(sidebar: PropSidebar): SidebarItemDoc[];

/**
 * Collect all document IDs from sidebar
 * @param sidebar - Sidebar to search
 * @returns Array of document IDs
 */
function collectSidebarDocIds(sidebar: PropSidebar): string[];

/**
 * Collect navigation items from sidebar
 * @param sidebar - Sidebar to search
 * @returns Array of navigation items
 */
function collectSidebarNavigation(sidebar: PropSidebar): SidebarNavigationItem[];

/**
 * Collect document IDs from all sidebars
 * @param sidebars - Sidebars object to search
 * @returns Map of sidebar ID to array of doc IDs
 */
function collectSidebarsDocIds(sidebars: Sidebars): {[sidebarId: string]: string[]};

/**
 * Collect navigation items from all sidebars
 * @param sidebars - Sidebars object to search
 * @returns Map of sidebar ID to navigation items
 */
function collectSidebarsNavigations(sidebars: Sidebars): {[sidebarId: string]: SidebarNavigationItem[]};

interface SidebarNavigationItem {
  title: string;
  permalink: string;
  unlisted?: boolean;
}

interface SidebarsConfig {
  [sidebarId: string]: SidebarItem[];
}

interface Sidebars {
  [sidebarId: string]: SidebarItem[];
}

type SidebarItem = 
  | SidebarItemDoc
  | SidebarItemLink  
  | SidebarItemHtml
  | SidebarItemCategory
  | SidebarItemAutogenerated;

interface SidebarProcessorParams {
  version: VersionMetadata;
  sidebarItemsGenerator: SidebarItemsGeneratorOption;
  numberPrefixParser: NumberPrefixParser;
  categoryLabelSlugger: Slugger;
  docs: DocMetadata[];
}

interface SidebarItemsGeneratorOption {
  (params: {
    defaultSidebarItemsGenerator: SidebarItemsGenerator;
    item: SidebarItemAutogenerated;
    version: SidebarItemsGeneratorVersion;
    docs: SidebarItemsGeneratorDoc[];
    numberPrefixParser: NumberPrefixParser;
    isCategoryIndex: CategoryIndexMatcher;
    categoriesMetadata: {[filePath: string]: CategoryMetadataFile};
  }): NormalizedSidebar | Promise<NormalizedSidebar>;
}

interface SidebarItemsGeneratorVersion {
  versionName: string;
  label: string;
  path: string;
}

interface SidebarItemsGeneratorDoc {
  id: string;
  title: string;
  source: string;
  sourceDirName: string;
  permalink: string;
  sidebarPosition?: number;
  frontMatter: Record<string, unknown>;
}

interface CategoryIndexMatcher {
  (params: {
    fileName: string;
    directories: string[];
    extension: string;
  }): boolean;
}

interface CategoryMetadataFile {
  label?: string;
  position?: number;
  collapsed?: boolean;
  collapsible?: boolean;
  className?: string;
  customProps?: Record<string, unknown>;
  link?: SidebarItemCategoryLink;
}

interface CategoryMetadata {
  [dirPath: string]: CategoryMetadataFile;
}

/** Pattern for category metadata filenames */
const CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';