or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

@docusaurus/preset-classic

@docusaurus/preset-classic is the default preset configuration for Docusaurus that automatically bundles and configures essential plugins and themes for typical documentation sites. It eliminates the need to manually configure individual plugins by providing a cohesive, pre-configured solution.

Package Information

Package Name: @docusaurus/preset-classic
Package Type: npm
Language: TypeScript
Installation: npm install @docusaurus/preset-classic

Core Imports

import preset from "@docusaurus/preset-classic";
import type { Options, ThemeConfig } from "@docusaurus/preset-classic";

For CommonJS:

const preset = require("@docusaurus/preset-classic");

Basic Usage

The preset is typically used in a Docusaurus configuration file (docusaurus.config.js):

import type { Config } from "@docusaurus/types";

const config: Config = {
  // ... other config
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          sidebarPath: "./sidebars.js",
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: "./src/css/custom.css",
        },
      } as Options,
    ],
  ],
};

export default config;

Simple configuration without options:

module.exports = {
  presets: ["@docusaurus/preset-classic"],
};

Architecture

The preset-classic package provides:

Preset Function: Main default export that analyzes configuration options and returns bundled plugin configurations
Plugin Bundling: Automatically includes and configures content plugins (docs, blog, pages), analytics plugins (Google Analytics, gtag, Google Tag Manager), utility plugins (debug, sitemap), and themes (classic theme, Algolia search)
Conditional Loading: Intelligently enables/disables plugins based on configuration options and environment conditions
Validation: Validates configuration options and provides helpful error messages for deprecated or invalid configurations

Capabilities

Preset Configuration

Main preset function that bundles and configures Docusaurus plugins and themes.

/**
 * Default preset function that configures Docusaurus plugins and themes
 * @param context - Docusaurus load context containing site configuration and environment info
 * @param opts - Configuration options for the preset
 * @returns Preset object containing configured plugins and themes
 */
export default function preset(
  context: LoadContext,
  opts: Options = {}
): Preset;

interface LoadContext {
  siteDir: string;
  generatedFilesDir: string;
  siteConfig: DocusaurusConfig;
  outDir: string;
  baseUrl: string;
  i18n: I18n;
  ssrTemplate: string;
  codeTranslations: {[locale: string]: CodeTranslations};
}

interface Preset {
  themes: PluginConfig[];
  plugins: PluginConfig[];
}

type PluginConfig = 
  | string 
  | [string, any] 
  | false 
  | null;

Configuration Options

Complete configuration interface for customizing the preset behavior.

interface Options {
  /** Enable/disable debug plugin. Use false to disable, true to enable in production */
  debug?: boolean;
  /** Configuration for @docusaurus/plugin-content-docs. Use false to disable */
  docs?: false | DocsPluginOptions;
  /** Configuration for @docusaurus/plugin-content-blog. Use false to disable */
  blog?: false | BlogPluginOptions;
  /** Configuration for @docusaurus/plugin-content-pages. Use false to disable */
  pages?: false | PagesPluginOptions;
  /** Configuration for @docusaurus/plugin-sitemap. Use false to disable */
  sitemap?: false | SitemapPluginOptions;
  /** Configuration for @docusaurus/theme-classic */
  theme?: ThemeOptions;
  /** Configuration for @docusaurus/plugin-google-analytics. Only enabled when present */
  googleAnalytics?: GAPluginOptions;
  /** Configuration for @docusaurus/plugin-google-gtag. Only enabled when present */
  gtag?: GtagPluginOptions;
  /** Configuration for @docusaurus/plugin-google-tag-manager. Only enabled when present */
  googleTagManager?: GTMPluginOptions;
}

interface DocsPluginOptions {
  path?: string;
  routeBasePath?: string;
  include?: string[];
  exclude?: string[];
  sidebarPath?: string | false;
  editUrl?: string | ((params: EditUrlParams) => string);
  editCurrentVersion?: boolean;
  editLocalizedFiles?: boolean;
  showLastUpdateTime?: boolean;
  showLastUpdateAuthor?: boolean;
  breadcrumbs?: boolean;
  // ... additional docs plugin options
}

interface BlogPluginOptions {
  path?: string;
  routeBasePath?: string;
  include?: string[];
  exclude?: string[];
  postsPerPage?: number | "ALL";
  blogTitle?: string;
  blogDescription?: string;
  blogSidebarCount?: number | "ALL";
  blogSidebarTitle?: string;
  showReadingTime?: boolean;
  feedOptions?: {
    type?: "rss" | "atom" | "all";
    title?: string;
    description?: string;
    copyright?: string;
    language?: string;
  };
  // ... additional blog plugin options
}

interface PagesPluginOptions {
  path?: string;
  routeBasePath?: string;
  include?: string[];
  exclude?: string[];
  mdxPageComponent?: string;
}

interface SitemapPluginOptions {
  changefreq?: "weekly" | "daily" | "monthly" | "yearly";
  priority?: number;
  ignorePatterns?: string[];
  filename?: string;
}

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

interface GAPluginOptions {
  trackingID: string;
  anonymizeIP?: boolean;
}

interface GtagPluginOptions {
  trackingID: string;
  anonymizeIP?: boolean;
}

interface GTMPluginOptions {
  containerId: string;
}

Theme Configuration

Combined theme configuration interface for all included themes.

interface ThemeConfig extends BaseThemeConfig, ClassicThemeConfig, AlgoliaThemeConfig {}

interface BaseThemeConfig {
  image?: string;
  metadata?: Metadata[];
  announcementBar?: {
    id?: string;
    content: string;
    backgroundColor?: string;
    textColor?: string;
    isCloseable?: boolean;
  };
}

interface ClassicThemeConfig {
  navbar?: {
    title?: string;
    logo?: {
      alt?: string;
      src: string;
      srcDark?: string;
      width?: string | number;
      height?: string | number;
      style?: Record<string, string>;
    };
    items?: NavbarItem[];
    hideOnScroll?: boolean;
    style?: "primary" | "dark";
  };
  footer?: {
    style?: "light" | "dark";
    links?: FooterLinkItem[][];
    copyright?: string;
    logo?: {
      alt?: string;
      src: string;
      width?: string | number;
      height?: string | number;
    };
  };
  prism?: {
    theme?: any;
    darkTheme?: any;
    defaultLanguage?: string;
    additionalLanguages?: string[];
  };
  colorMode?: {
    defaultMode?: "light" | "dark";
    disableSwitch?: boolean;
    respectPrefersColorScheme?: boolean;
  };
}

interface AlgoliaThemeConfig {
  algolia?: {
    appId: string;
    apiKey: string;
    indexName: string;
    contextualSearch?: boolean;
    searchParameters?: Record<string, any>;
    searchPagePath?: string | false;
  };
}

interface NavbarItem {
  type?: "default" | "dropdown" | "docsVersionDropdown" | "localeDropdown";
  label?: string;
  to?: string;
  href?: string;
  position?: "left" | "right";
  className?: string;
  "aria-label"?: string;
}

interface FooterLinkItem {
  title?: string;
  items?: {
    label: string;
    to?: string;
    href?: string;
  }[];
}

interface Metadata {
  name?: string;
  property?: string;
  content: string;
}

Error Handling

The preset function validates configuration and throws descriptive errors for common issues:

Deprecated Configuration: Throws errors if deprecated themeConfig.gtag or themeConfig.googleAnalytics fields are used instead of preset options
Invalid Options: Throws errors for unrecognized configuration keys with helpful guidance on valid options
Plugin Conflicts: Automatically handles plugin conflicts and conditional loading based on environment and configuration

Common error messages:

// Deprecated gtag configuration
throw new Error(
  'The "gtag" field in themeConfig should now be specified as option for plugin-google-gtag. ' +
  'For preset-classic, simply move themeConfig.gtag to preset options.'
);

// Invalid configuration keys
throw new Error(
  `Unrecognized keys ${Object.keys(invalidKeys).join(', ')} found in preset-classic configuration. ` +
  'The allowed keys are debug, docs, blog, pages, sitemap, theme, googleAnalytics, gtag, and googleTagManager.'
);

Usage Examples

Complete Configuration Example

import type { Config } from "@docusaurus/types";
import type { Options } from "@docusaurus/preset-classic";

const config: Config = {
  title: "My Documentation Site",
  tagline: "Comprehensive docs with Docusaurus",
  url: "https://mydocs.com",
  baseUrl: "/",
  
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          sidebarPath: "./sidebars.js",
          editUrl: "https://github.com/myorg/mydocs/tree/main/",
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
        },
        blog: {
          showReadingTime: true,
          postsPerPage: 10,
          blogSidebarCount: 5,
          feedOptions: {
            type: "all",
            copyright: `Copyright © ${new Date().getFullYear()} My Organization.`,
          },
        },
        pages: {
          remarkPlugins: [require("remark-math")],
          rehypePlugins: [require("rehype-katex")],
        },
        theme: {
          customCss: "./src/css/custom.css",
        },
        gtag: {
          trackingID: "G-XXXXXXXXXX",
          anonymizeIP: true,
        },
        sitemap: {
          changefreq: "weekly",
          priority: 0.5,
        },
      } as Options,
    ],
  ],

  themeConfig: {
    navbar: {
      title: "My Site",
      logo: {
        alt: "My Site Logo",
        src: "img/logo.svg",
      },
      items: [
        {
          type: "doc",
          docId: "intro",
          position: "left",
          label: "Tutorial",
        },
        { to: "/blog", label: "Blog", position: "left" },
        {
          href: "https://github.com/myorg/mydocs",
          label: "GitHub",
          position: "right",
        },
      ],
    },
    footer: {
      style: "dark",
      links: [
        {
          title: "Docs",
          items: [
            {
              label: "Tutorial",
              to: "/docs/intro",
            },
          ],
        },
        {
          title: "Community",
          items: [
            {
              label: "Stack Overflow",
              href: "https://stackoverflow.com/questions/tagged/docusaurus",
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Project.`,
    },
    algolia: {
      appId: "YOUR_APP_ID",
      apiKey: "YOUR_SEARCH_API_KEY",
      indexName: "YOUR_INDEX_NAME",
      contextualSearch: true,
    },
  },
};

export default config;

Minimal Configuration

// docusaurus.config.js
module.exports = {
  title: "My Site",
  tagline: "A simple documentation site",
  url: "https://mysite.com",
  baseUrl: "/",
  
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          sidebarPath: require.resolve("./sidebars.js"),
        },
        blog: {
          showReadingTime: true,
        },
      },
    ],
  ],
};

Disabling Specific Plugins

const config: Config = {
  presets: [
    [
      "@docusaurus/preset-classic",
      {
        // Disable blog entirely
        blog: false,
        // Keep docs but disable sitemap
        sitemap: false,
        // Enable debug in production
        debug: true,
        docs: {
          sidebarPath: "./sidebars.js",
        },
      } as Options,
    ],
  ],
};