Theme Configuration

/**
 * Validates theme configuration options
 * @param params - Validation parameters
 * @returns Validated and normalized theme configuration
 */
function validateThemeConfig(params: {
  themeConfig: ThemeConfig;
  validate: ValidationContext;
}): ThemeConfig;

/**
 * Validates plugin options
 * @param params - Plugin validation parameters
 * @returns Validated plugin options
 */
function validateOptions(params: {
  options: Options;
  validate: ValidationContext;
}): PluginOptions;

interface ValidationContext {
  validate: <T>(schema: Schema<T>, value: T) => T;
}

/**
 * Returns swizzle configuration for component customization
 * @returns Complete swizzle configuration
 */
function getSwizzleConfig(): SwizzleConfig;

interface SwizzleConfig {
  components: {
    [componentName: string]: {
      actions: {
        eject: 'safe' | 'unsafe' | 'forbidden';
        wrap: 'safe' | 'unsafe' | 'forbidden';
      };
      description: string;
    };
  };
}

/**
 * Arrow icon for navigation
 * @param props - SVG props
 * @returns Arrow icon element
 */
function IconArrow(props: IconProps): ReactNode;

/**
 * Menu hamburger icon
 * @param props - SVG props
 * @returns Menu icon element
 */
function IconMenu(props: IconProps): ReactNode;

/**
 * Close/X icon
 * @param props - SVG props
 * @returns Close icon element
 */
function IconClose(props: IconProps): ReactNode;

/**
 * Home icon
 * @param props - SVG props
 * @returns Home icon element
 */
function IconHome(props: IconProps): ReactNode;

/**
 * Language/locale selection icon
 * @param props - SVG props
 * @returns Language icon element
 */
function IconLanguage(props: IconProps): ReactNode;

/**
 * External link icon
 * @param props - SVG props
 * @returns External link icon element
 */
function IconExternalLink(props: IconProps): ReactNode;

interface IconProps extends ComponentProps<'svg'> {}

/**
 * Dark mode icon
 * @param props - SVG props
 * @returns Dark mode icon element
 */
function IconDarkMode(props: IconProps): ReactNode;

/**
 * Light mode icon
 * @param props - SVG props
 * @returns Light mode icon element
 */
function IconLightMode(props: IconProps): ReactNode;

/**
 * System color mode icon
 * @param props - SVG props
 * @returns System theme icon element
 */
function IconSystemColorMode(props: IconProps): JSX.Element;

/**
 * Edit icon
 * @param props - SVG props
 * @returns Edit icon element
 */
function IconEdit(props: IconProps): ReactNode;

/**
 * Copy icon
 * @param props - SVG props
 * @returns Copy icon element
 */
function IconCopy(props: IconProps): ReactNode;

/**
 * Success/checkmark icon
 * @param props - SVG props
 * @returns Success icon element
 */
function IconSuccess(props: IconProps): ReactNode;

/**
 * Word wrap toggle icon
 * @param props - SVG props
 * @returns Word wrap icon element
 */
function IconWordWrap(props: IconProps): ReactNode;

/**
 * GitHub icon
 * @param props - SVG props
 * @returns GitHub icon element
 */
function IconGitHub(props: IconProps): ReactNode;

/**
 * Twitter icon
 * @param props - SVG props
 * @returns Twitter icon element
 */
function IconTwitter(props: IconProps): ReactNode;

/**
 * X (formerly Twitter) icon
 * @param props - SVG props
 * @returns X icon element
 */
function IconX(props: IconProps): ReactNode;

/**
 * LinkedIn icon
 * @param props - SVG props
 * @returns LinkedIn icon element
 */
function IconLinkedIn(props: IconProps): ReactNode;

/**
 * YouTube icon
 * @param props - SVG props
 * @returns YouTube icon element
 */
function IconYouTube(props: IconProps): ReactNode;

/**
 * Instagram icon
 * @param props - SVG props
 * @returns Instagram icon element
 */
function IconInstagram(props: IconProps): ReactNode;

/**
 * Threads icon
 * @param props - SVG props
 * @returns Threads icon element
 */
function IconThreads(props: IconProps): ReactNode;

/**
 * Twitch icon
 * @param props - SVG props
 * @returns Twitch icon element
 */
function IconTwitch(props: IconProps): ReactNode;

/**
 * Mastodon icon
 * @param props - SVG props
 * @returns Mastodon icon element
 */
function IconMastodon(props: IconProps): ReactNode;

/**
 * Bluesky icon
 * @param props - SVG props
 * @returns Bluesky icon element
 */
function IconBluesky(props: IconProps): ReactNode;

/**
 * Stack Overflow icon
 * @param props - SVG props
 * @returns Stack Overflow icon element
 */
function IconStackOverflow(props: IconProps): ReactNode;

/**
 * Default social icon for unknown platforms
 * @param props - SVG props
 * @returns Default social icon element
 */
function IconSocialsDefault(props: IconProps): ReactNode;

/**
 * Individual tag component
 * @param props - Tag props
 * @returns Styled tag element
 */
function Tag(props: TagProps): ReactNode;

interface TagProps {
  readonly label: string;
  readonly permalink: string;
  readonly count?: number;
}

/**
 * Tags list organized alphabetically
 * @param props - Tags list props
 * @returns Alphabetically grouped tags
 */
function TagsListByLetter(props: TagsListByLetterProps): ReactNode;

interface TagsListByLetterProps {
  readonly tags: readonly TagsListItem[];
}

/**
 * Inline tags list component
 * @param props - Inline tags props
 * @returns Horizontal tags list
 */
function TagsListInline(props: TagsListInlineProps): ReactNode;

interface TagsListInlineProps {
  readonly tags: readonly Tag[];
}

/**
 * 404 Not Found page content
 * @param props - Not found props
 * @returns 404 page content
 */
function NotFoundContent(props: NotFoundContentProps): ReactNode;

interface NotFoundContentProps {
  readonly className?: string;
}

/**
 * Error page content component
 * @returns Error page content
 */
const ErrorPageContent: typeof ErrorComponent;

/**
 * Search bar component
 * @returns Search input interface
 */
function SearchBar(): ReactNode;

interface ThemeConfig {
  // Color mode configuration
  colorMode?: {
    defaultMode: 'light' | 'dark';
    disableSwitch: boolean;
    respectPrefersColorScheme: boolean;
  };
  
  // Navbar configuration
  navbar?: {
    title?: string;
    logo?: NavbarLogo;
    items: NavbarItem[];
    hideOnScroll?: boolean;
    style?: 'primary' | 'dark';
  };
  
  // Footer configuration
  footer?: {
    style: 'light' | 'dark';
    links?: FooterLinks;
    copyright?: string;
    logo?: FooterLogo;
  };
  
  // Prism syntax highlighting
  prism?: {
    theme?: PrismTheme;
    darkTheme?: PrismTheme;
    additionalLanguages?: string[];
    defaultLanguage?: string;
    magicComments?: MagicCommentConfig[];
  };
  
  // Documentation configuration
  docs?: {
    versionPersistence: 'localStorage' | 'none';
    sidebar: {
      hideable: boolean;
      autoCollapseCategories: boolean;
    };
  };
  
  // Blog configuration
  blog?: {
    sidebar: {
      groupByYear: boolean;
    };
  };
  
  // Announcement bar
  announcementBar?: {
    id: string;
    content: string;
    backgroundColor?: string;
    textColor?: string;
    isCloseable?: boolean;
  };
}

interface NavbarLogo {
  alt?: string;
  src: string;
  srcDark?: string;
  href?: string;
  target?: string;
  width?: string | number;
  height?: string | number;
  className?: string;
  style?: React.CSSProperties;
}

// Union type for different navbar item types
type NavbarItem = 
  | DefaultNavbarItem
  | DropdownNavbarItem
  | DocNavbarItem
  | DocSidebarNavbarItem
  | DocsVersionNavbarItem
  | DocsVersionDropdownNavbarItem
  | LocaleDropdownNavbarItem
  | SearchNavbarItem
  | HtmlNavbarItem;

interface FooterLogo {
  alt?: string;
  src: string;
  srcDark?: string;
  href?: string;
  width?: string | number;
  height?: string | number;
}

type FooterLinks = MultiColumnFooter | SimpleFooter;

interface MultiColumnFooter {
  links: FooterLinkColumn[];
}

interface SimpleFooter {
  links: FooterLinkItem[];
}

interface FooterLinkColumn {
  title?: string;
  items: FooterLinkItem[];
}

interface FooterLinkItem {
  label?: string;
  html?: string;
  to?: string;
  href?: string;
  prependBaseUrlToHref?: boolean;
}

interface PrismTheme {
  plain: PrismThemeEntry;
  styles: PrismThemeEntry[];
}

interface PrismThemeEntry {
  types: string[];
  style: React.CSSProperties;
  languages?: string[];
}

interface MagicCommentConfig {
  className: string;
  line?: string;
  block?: {
    start: string;
    end: string;
  };
}

interface Options {
  customCss?: string[] | string;
}

interface PluginOptions {
  customCss: string[];
}

const DEFAULT_COLOR_MODE_CONFIG = {
  defaultMode: 'light' as const,
  disableSwitch: false,
  respectPrefersColorScheme: false,
};

const DEFAULT_DOCS_CONFIG = {
  versionPersistence: 'localStorage' as const,
  sidebar: {
    hideable: false,
    autoCollapseCategories: false,
  },
};

const DEFAULT_BLOG_CONFIG = {
  sidebar: {
    groupByYear: true,
  },
};

// docusaurus.config.js
import { themes } from 'prism-react-renderer';

export default {
  title: 'My Documentation Site',
  themes: ['@docusaurus/theme-classic'],
  themeConfig: {
    // Color mode
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
    
    // Navbar
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
        srcDark: 'img/logo-dark.svg',
      },
      items: [
        {
          type: 'doc',
          docId: 'intro',
          position: 'left',
          label: 'Docs',
        },
        {
          to: '/blog',
          label: 'Blog',
          position: 'left',
        },
        {
          type: 'dropdown',
          label: 'Community',
          position: 'right',
          items: [
            {
              label: 'Discord',
              href: 'https://discord.gg/example',
            },
            {
              label: 'Twitter',
              href: 'https://twitter.com/example',
            },
          ],
        },
      ],
    },
    
    // Footer
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Getting Started',
              to: '/docs/intro',
            },
          ],
        },
        {
          title: 'Community',
          items: [
            {
              label: 'Discord',
              href: 'https://discord.gg/example',
            },
            {
              label: 'Twitter',
              href: 'https://twitter.com/example',
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Project.`,
    },
    
    // Prism
    prism: {
      theme: themes.github,
      darkTheme: themes.dracula,
      additionalLanguages: ['rust', 'php'],
      defaultLanguage: 'javascript',
      magicComments: [
        {
          className: 'theme-code-block-highlighted-line',
          line: 'highlight-next-line',
          block: {start: 'highlight-start', end: 'highlight-end'},
        },
      ],
    },
    
    // Docs
    docs: {
      sidebar: {
        hideable: true,
        autoCollapseCategories: true,
      },
    },
    
    // Blog
    blog: {
      sidebar: {
        groupByYear: true,
      },
    },
    
    // Announcement bar
    announcementBar: {
      id: 'support_us',
      content: 'We are looking to revamp our docs, please fill <a target="_blank" rel="noopener noreferrer" href="#">this survey</a>',
      backgroundColor: '#fafbfc',
      textColor: '#091E42',
      isCloseable: false,
    },
  },
};

// docusaurus.config.js
export default {
  themes: [
    [
      '@docusaurus/theme-classic',
      {
        customCss: [
          require.resolve('./src/css/custom.css'),
          require.resolve('./src/css/components.css'),
        ],
      },
    ],
  ],
};

# List all swizzleable components
npx docusaurus swizzle @docusaurus/theme-classic --list

# Safely eject a component for customization
npx docusaurus swizzle @docusaurus/theme-classic Footer --eject

# Wrap a component with additional functionality
npx docusaurus swizzle @docusaurus/theme-classic NavbarItem/DefaultNavbarItem --wrap