Version Management

/**
 * Filters available versions based on plugin options
 * @param availableVersions - Array of all available version names
 * @param options - Plugin options for version filtering
 * @returns Filtered array of version names to include
 */
function filterVersions(
  availableVersions: string[],
  options: Pick<PluginOptions, 'onlyIncludeVersions' | 'includeCurrentVersion' | 'lastVersion'>
): string[];

import { filterVersions } from '@docusaurus/plugin-content-docs/server';

// Filter versions based on plugin configuration
const availableVersions = ['1.0.0', '2.0.0', '3.0.0', 'current'];
const filteredVersions = filterVersions(availableVersions, {
  onlyIncludeVersions: ['2.0.0', '3.0.0', 'current'],
  includeCurrentVersion: true,
  lastVersion: '3.0.0'
});
// Result: ['2.0.0', '3.0.0', 'current']

/**
 * Reads version names from versions.json file
 * @param versionsJsonFile - Path to versions.json file
 * @returns Promise resolving to array of version names
 */
function readVersionNames(versionsJsonFile: string): Promise<string[]>;

/**
 * Reads and processes version metadata from filesystem
 * @param params - Context and options for reading versions
 * @returns Promise resolving to array of version metadata
 */
function readVersionsMetadata(params: {
  context: LoadContext;
  options: PluginOptions;
}): Promise<VersionMetadata[]>;

/**
 * Loads complete version data including docs and sidebars
 * @param params - Parameters for loading version
 * @returns Promise resolving to loaded version data
 */
function loadVersion(params: {
  context: LoadContext;
  options: PluginOptions;
  env: DocEnv;
  versionMetadata: VersionMetadata;
}): Promise<LoadedVersion>;

/**
 * Gets version from source file path
 * @param sourceFilePath - Path to source file
 * @param versionsMetadata - Array of version metadata
 * @returns Version metadata for the file
 */
function getVersionFromSourceFilePath(
  sourceFilePath: string,
  versionsMetadata: VersionMetadata[]
): VersionMetadata;

/**
 * Converts loaded version to full version with utilities
 * @param loadedVersion - Basic loaded version data
 * @returns Full version with additional utilities
 */
function toFullVersion(loadedVersion: LoadedVersion): FullVersion;

import {
  getDefaultVersionBanner,
  getVersionBanner,
  getVersionBadge
} from "@docusaurus/plugin-content-docs/server";

/**
 * Gets default version banner for a version
 * @param versionName - Name of the version
 * @param params - Context parameters for banner determination
 * @returns Banner type or null
 */
function getDefaultVersionBanner(
  versionName: string,
  params: {
    lastVersionName: string;
    versionsMetadata: VersionMetadata[];
  }
): VersionBanner | null;

/**
 * Gets version banner configuration
 * @param versionName - Name of the version
 * @param options - Version options
 * @returns Banner configuration
 */
function getVersionBanner(
  versionName: string,
  options: VersionOptions & {
    lastVersionName: string;
    versionsMetadata: VersionMetadata[];
  }
): VersionBanner | null;

/**
 * Gets version badge configuration
 * @param versionName - Name of the version
 * @param options - Version options
 * @returns Whether to show version badge
 */
function getVersionBadge(
  versionName: string,
  options: VersionOptions & { lastVersionName: string }
): boolean;

/** Name identifier for the current/active version being worked on */
const CURRENT_VERSION_NAME = 'current';

/** Directory name where all versioned docs are stored */
const VERSIONED_DOCS_DIR = 'versioned_docs';

/** Directory name where all versioned sidebars are stored */
const VERSIONED_SIDEBARS_DIR = 'versioned_sidebars';

/** Filename for the versions.json configuration file */
const VERSIONS_JSON_FILE = 'versions.json';

import {
  CURRENT_VERSION_NAME,
  VERSIONED_DOCS_DIR,
  VERSIONED_SIDEBARS_DIR,
  VERSIONS_JSON_FILE
} from "@docusaurus/plugin-content-docs/server";

// docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'default',
        // Include only specific versions
        onlyIncludeVersions: ['current', '2.0.0', '1.0.0'],
        // Set which version is considered "latest"
        lastVersion: '2.0.0',
        // Include the current development version
        includeCurrentVersion: true,
        // Custom version configuration
        versions: {
          current: {
            label: 'Next',
            path: 'next',
            banner: 'unreleased',
          },
          '2.0.0': {
            label: '2.0.0 (Latest)',
            banner: 'none',
          },
          '1.0.0': {
            label: '1.0.0',
            banner: 'unmaintained',
          },
        },
      },
    ],
  ],
};

// docusaurus.config.js with multiple version configurations
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        versions: {
          current: {
            label: 'Development',
            path: 'next',
            banner: 'unreleased',
            badge: true,
            noIndex: true,
            className: 'version-development',
          },
          '3.0.0': {
            label: '3.0.0 (Latest)',
            banner: 'none',
            badge: false,
          },
          '2.8.0': {
            label: '2.8.0 (LTS)',
            banner: 'unmaintained',
            badge: true,
          },
        },
      },
    ],
  ],
};

interface VersionMetadata extends ContentPaths {
  /** Version name like "1.0.0" from versions.json */
  versionName: string;
  /** Display label like "Version 1.0.0" */
  label: string;
  /** Version's base URL path */
  path: string;
  /** Tags base path for this version */
  tagsPath: string;
  /** Edit URL base for this version */
  editUrl?: string | undefined;
  /** Localized edit URL base */
  editUrlLocalized?: string | undefined;
  /** Banner type for this version */
  banner: VersionBanner | null;
  /** Whether to show version badge */
  badge: boolean;
  /** Whether to prevent search indexing */
  noIndex: boolean;
  /** Custom CSS class name */
  className: string;
  /** Whether this is the latest version */
  isLast: boolean;
  /** Path to sidebar file for this version */
  sidebarFilePath: string | false | undefined;
  /** Routing priority for this version */
  routePriority: number | undefined;
}

interface LoadedVersion extends VersionMetadata {
  /** Documents in this version */
  docs: DocMetadata[];
  /** Draft documents in this version */
  drafts: DocMetadata[];
  /** Sidebars configuration for this version */
  sidebars: Sidebars;
}

interface FullVersion extends LoadedVersion {
  /** Sidebar utilities for this version */
  sidebarsUtils: SidebarsUtils;
  /** Generated category indices for this version */
  categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
}

type VersionBanner = 'unreleased' | 'unmaintained';

interface VersionOptions {
  /** Custom path for this version */
  path?: string;
  /** Display label for this version */
  label?: string;
  /** Banner type or 'none' to disable */
  banner?: 'none' | VersionBanner;
  /** Whether to show version badge */
  badge?: boolean;
  /** Prevent search engine indexing */
  noIndex?: boolean;
  /** Custom CSS class name */
  className?: string;
}

interface ContentPaths {
  /** Absolute path to content directory */
  contentPath: string;
  /** Absolute path to content directory with potential localization */
  contentPathLocalized: string;
}

type DocEnv = 'production' | 'development';