Configuration

Complete reference for all Ardo configuration options.

Configuration

Ardo is configured through the ardo() plugin in your vite.config.ts. This page documents every available option.

Basic Setup

import { defineConfig } from "vite"
import { ardo } from "ardo/vite"

export default defineConfig({
  plugins: [
    ardo({
      title: "My Documentation",
      description: "My awesome docs",
    }),
  ],
})

The ardo() function accepts an options object that combines site configuration (from ArdoConfig) with plugin-specific settings.

Site Configuration

These options control the identity and basic behavior of your documentation site.

title

Type: string
Required

The site title, used in the default <title> meta tag and displayed in the header.

ardo({
  title: "My Documentation",
})

description

Type: string
Default: ""

Site description for the default meta tags.

ardo({
  title: "My Docs",
  description: "A comprehensive guide to my library",
})

titleSeparator

Type: string
Default: " | "

Separator between the page title and the site title in <title> tags. For example, a page titled "Getting Started" produces Getting Started | My Docs.

ardo({
  title: "My Docs",
  titleSeparator: " - ",
})

base

Type: string
Default: "/"

Base URL path for the site. Set this if your docs live under a subpath.

ardo({
  title: "My Docs",
  base: "/docs/",
})

When deploying to GitHub Pages, Ardo auto-detects the repository name and sets the base path for you. See the githubPages plugin option below.

srcDir

Type: string
Default: "content"

Content source directory, relative to the project root. This is where Ardo looks for your markdown files when using the config-driven approach.

ardo({
  title: "My Docs",
  srcDir: "docs",
})

outDir

Type: string
Default: "dist"

Build output directory.

ardo({
  title: "My Docs",
  outDir: "build",
})

lang

Type: string
Default: "en"

Site language. Sets the lang attribute on the <html> element.

ardo({
  title: "My Docs",
  lang: "de",
})

Plugin Options

These options are specific to the ardo() Vite plugin and are not part of ArdoConfig.

routes

Type: ArdoRoutesPluginOptions | false
Default: automatic

Configuration for the automatic route generation plugin. Set to false to disable auto-routing entirely.

githubPages

Type: boolean
Default: true

When true, Ardo auto-detects your GitHub repository name from the git remote and sets base: '/repo-name/' for GitHub Pages deployment.

ardo({
  title: "My Docs",
  githubPages: false, // Disable auto-detection
})

routesDir

Type: string
Default: "./app/routes"

Directory where route files are located.

ardo({
  title: "My Docs",
  routesDir: "./src/routes",
})

Markdown

Markdown processing options are configured under the markdown key.

ardo({
  title: "My Docs",
  markdown: {
    theme: { light: "github-light-default", dark: "github-dark-default" },
    lineNumbers: true,
  },
})

markdown.theme

Type: BundledTheme | { light: BundledTheme; dark: BundledTheme }
Default: { light: "github-light-default", dark: "github-dark-default" }

Syntax highlighting theme. Can be a single Shiki theme name or a light/dark pair.

markdown: {
  theme: "one-dark-pro",
}

markdown.lineNumbers

Type: boolean
Default: false

Show line numbers in code blocks.

markdown.anchor

Type: boolean
Default: true

Enable anchor links on headings.

markdown.toc

Type: { level?: [number, number] }
Default: { level: [2, 3] }

Table of contents configuration. The level tuple specifies which heading levels to include (min, max).

markdown: {
  toc: {
    level: [2, 4], // Include h2, h3, and h4
  },
}

markdown.remarkPlugins

Type: unknown[]
Default: []

Additional remark plugins for markdown processing. Ardo already includes remark-frontmatter, remark-mdx-frontmatter, and remark-gfm.

markdown.rehypePlugins

Type: unknown[]
Default: []

Additional rehype plugins for HTML processing. Ardo already includes @shikijs/rehype for syntax highlighting.

TypeDoc

Enable TypeDoc API documentation generation. Pass true for defaults or an object for fine-grained control.

ardo({
  title: "My Docs",
  typedoc: true, // Enable with defaults (./src/index.ts)
})

typedoc (boolean shorthand)

Type: true

Enables TypeDoc with default settings — reads from ./src/index.ts and outputs to content/api-reference/.

typedoc.enabled

Type: boolean
Default: true

Explicitly enable or disable TypeDoc generation.

typedoc.entryPoints

Type: string[]
Required (when using object config)

Entry point files for TypeDoc.

typedoc: {
  entryPoints: ["./src/index.ts", "./src/utils.ts"],
}

typedoc.tsconfig

Type: string
Default: auto-detected

Path to the TypeScript configuration file for TypeDoc.

typedoc: {
  entryPoints: ["./src/index.ts"],
  tsconfig: "./tsconfig.api.json",
}

typedoc.out

Type: string
Default: "content/api-reference"

Output directory for generated API documentation.

typedoc.exclude

Type: string[]

Glob patterns for files to exclude from documentation.

typedoc.excludeExternals

Type: boolean

Exclude external modules from documentation.

typedoc.excludePrivate

Type: boolean

Exclude private members from documentation.

typedoc.excludeProtected

Type: boolean

Exclude protected members from documentation.

typedoc.excludeInternal

Type: boolean

Exclude @internal tagged items from documentation.

typedoc.sort

Type: Array<"source-order" | "alphabetical" | "enum-value-ascending" | "enum-value-descending" | "required-first" | "visibility">

Sorting strategy for documented items.

typedoc: {
  entryPoints: ["./src/index.ts"],
  sort: ["alphabetical", "required-first"],
}

typedoc.watch

Type: boolean

Enable watch mode for TypeDoc during development.

typedoc.sidebar

Type: { title?: string; position?: number; collapsed?: boolean }

Sidebar configuration for the generated API reference section.

typedoc.markdown

Type: { breadcrumbs?: boolean; hierarchy?: boolean; sourceLinks?: boolean; sourceBaseUrl?: string; codeBlocks?: boolean }

Options controlling the generated markdown output.

UI Configuration

Navigation, sidebar, footer, editLink, lastUpdated, and search are configured via JSX props in your root.tsx using <ArdoRoot>. See Custom Theme for details.

Frontmatter

Per-page configuration is done through frontmatter in your MDX files. See the dedicated Frontmatter page for all available options.

Full Example

import { defineConfig } from "vite"
import { ardo } from "ardo/vite"

export default defineConfig({
  plugins: [
    ardo({
      title: "My Library",
      description: "Comprehensive documentation for My Library",
      lang: "en",

      markdown: {
        theme: { light: "github-light-default", dark: "github-dark-default" },
        lineNumbers: false,
        toc: { level: [2, 3] },
      },

      typedoc: {
        entryPoints: ["./src/index.ts"],
        tsconfig: "./tsconfig.api.json",
      },
    }),
  ],
})

Edit this page on GitHub