Configuration

Ardo keeps configuration split where React teams expect it:

• Build behavior lives in the ardo() Vite plugin: site metadata, routes, Markdown, TypeDoc, and deployment helpers.
• UI behavior lives in React: ArdoRoot, header/sidebar/footer props, component overrides, and runtime hooks.

This page documents the build-time options first, then points to the React-side UI hooks and components. For a broader capability matrix, including planned features that are not yet configurable, see Feature Status.

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/",
})

siteUrl

• Type: string
• Default: ""

Absolute public URL for the site. Ardo uses it to generate canonical URLs, og:url, and absolute social image URLs for Markdown routes.

ardo({
  title: "My Docs",
  siteUrl: "https://example.com",
})

If your docs are served from a subpath, configure base separately. Ardo combines siteUrl, base, and the route path for generated canonical URLs.

metadata

• Type: { image?: string; ogType?: string; twitterCard?: "summary_large_image" | "summary"; twitterSite?: string }
• Default: {}

Site-level defaults for generated Markdown metadata. Page frontmatter can override these values per route.

ardo({
  title: "My Docs",
  siteUrl: "https://example.com",
  metadata: {
    image: "/social.png",
    ogType: "website",
    twitterCard: "summary_large_image",
    twitterSite: "@example",
  },
})

brand

• Type: { color?: number | Preset; accent?: number | Preset; neutral?: number | Preset; logo?: string | { light: string; dark: string } }
• Default: {}

Simple brand configuration for the default theme and header logo. color, accent, and neutral accept OKLCH hue numbers or preset names: berry, red, orange, amber, green, teal, blue, indigo, purple, pink, slate, and gray.

ardo({
  title: "My Docs",
  brand: {
    color: "blue",
    accent: "teal",
    neutral: "slate",
    logo: "./app/assets/logo.svg",
  },
})

When color is set without accent, Ardo derives an accent hue. When neutral is omitted, the neutral chrome follows color. Local SVG logo paths are bundled for the default header and also become the default source for generated favicons. Use an explicit logo on ArdoHeader or icons.source when the header and favicon should use different assets.

seo.llms

• Type: boolean | { indexFileName?: string; fullFileName?: string; includeFull?: boolean; title?: string; description?: string }
• Default: true

Generates LLM-friendly text artifacts alongside the other build outputs:

• /llms.txt is a concise Markdown index with links to Markdown and MDX routes.
• /llms-full.txt is the same documentation content as one Markdown file.

Ardo uses page frontmatter titles and descriptions when available, skips TSX routes, and strips MDX imports, exports, and JSX component tags from the full export. Set llms: false in page frontmatter to exclude a Markdown page from both files.

ardo({
  title: "My Docs",
  siteUrl: "https://example.com",
  seo: {
    llms: {
      title: "My Docs",
      description: "Developer documentation for my package.",
      includeFull: true,
    },
  },
})

Set seo.llms: false if you want to manage these files yourself from public/.

seo.sitemap

• Type: boolean | { changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never"; priority?: number }
• Default: true

Generates /sitemap.xml from Markdown and MDX routes. Ardo combines siteUrl, base, and each route path so subpath deployments still produce absolute URLs.

ardo({
  title: "My Docs",
  siteUrl: "https://example.com",
  base: "/docs/",
  seo: {
    sitemap: {
      changefreq: "weekly",
      priority: 0.7,
    },
  },
})

Set seo.sitemap: false to skip sitemap generation. Set sitemap: false in page frontmatter to exclude a single Markdown route.

seo.robots

• Type: boolean | { allow?: string[]; disallow?: string[] }
• Default: true

Generates /robots.txt. By default Ardo allows all crawlers and points them at the generated sitemap when siteUrl is configured.

ardo({
  title: "My Docs",
  siteUrl: "https://example.com",
  seo: {
    robots: {
      allow: ["/"],
      disallow: ["/drafts/"],
    },
  },
})

Set seo.robots: false if you want to provide your own robots.txt from public/.

linkCheck

• Type: { enabled?: boolean; checkAnchors?: boolean; exclude?: string[]; level?: "warn" | "error" }
• Default: { enabled: true, checkAnchors: true, level: "warn" }

Checks internal links in Markdown and MDX content at build time. Ardo reports missing routes and, unless disabled, missing heading anchors.

ardo({
  title: "My Docs",
  linkCheck: {
    level: "error",
    exclude: ["/storybook/*", "/generated/*"],
  },
})

Use checkAnchors: false when another tool rewrites heading ids after Ardo has read the route manifest. Use enabled: false only when another link checker owns the build gate.

redirects

• Type: Array<{ from: string; to: string }>
• Default: []

Generates static redirect assets for configured legacy paths:

• _redirects for Netlify-style hosts
• vercel.json redirect entries
• HTML redirect files for static hosts that only serve files

ardo({
  title: "My Docs",
  redirects: [
    { from: "/old-guide", to: "/guide/getting-started" },
    { from: "/v1/config", to: "/guide/configuration" },
  ],
})

Use frontmatter redirectFrom when a redirect belongs to one page instead of the whole site.

versioning

• Type: false | { current: string; versions: Array<{ id: string; label?: string; path: string }>; rootRedirect?: boolean }
• Default: false

Enables a small major-version documentation model. Ardo builds the current docs under the active version path, exposes the configured versions to the header version switcher, emits /versions.json, and generates a static /index.html redirect to the current version by default.

ardo({
  title: "My Docs",
  siteUrl: "https://docs.example.com",
  versioning: {
    current: "v3",
    versions: [
      { id: "v3", label: "3.x", path: "/v3/" },
      { id: "v2", label: "2.x", path: "/v2/" },
    ],
  },
})

When base is set, Ardo treats it as the deployment root and appends the version path. For example, base: "/my-project/" with path: "/v3/" produces canonical URLs under /my-project/v3/. The generated sitemap contains the current build only; older major versions can remain deployed as static folders without being advertised as duplicate current content.

Set rootRedirect: false if you want to provide your own root page or provider-level redirect. On static hosts such as GitHub Pages, Ardo's redirect is an HTML file with meta refresh and JavaScript. If you put a CDN or hosting layer with real HTTP redirects in front of the site, configure those redirects outside Ardo.

srcDir

• Type: string
• Default: "content"

Content source directory, relative to the project root. Most React Router projects use app/routes/ through the route generator. srcDir remains available for config-driven content workflows and generated markdown output.

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

outDir

• Type: string
• Status: Deprecated compatibility field

outDir remains in the public config type for compatibility, but it does not change the React Router build output. Ardo's static output is written to build/client/.

ardo({
  title: "My Docs",
  // Do not use outDir for new projects.
  // Deploy build/client/ instead.
})

lang

• Type: string
• Default: "en"

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

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

sidebar.sectionOrder

• Type: string[]
• Default: []

Controls the order of top-level sections used by ArdoGeneratedSidebar. Use route directory names, without leading slashes. Sections listed here appear first in the configured order. Any section not listed still appears automatically after the configured sections using the normal generated order.

ardo({
  title: "Product Docs",
  sidebar: {
    sectionOrder: ["guide", "reference", "api", "quality", "architecture", "archive"],
  },
})

Child pages inside each section keep their own generated order from frontmatter order values and alphabetical fallback sorting.

head

• Type: HeadConfig[]
• Status: Deprecated

Legacy static head tags. Prefer React Router's meta export and route-level metadata instead.

vite

• Type: Record<string, unknown>

Reserved for Vite-adjacent integration data. Most projects should configure Vite directly in vite.config.ts instead of nesting options here.

project

• Type: { name?: string; homepage?: string; repository?: string; version?: string; author?: string; license?: string }

Project metadata exposed through virtual:ardo/config. The Vite plugin auto-detects these values from package.json when possible.

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
})

icons

• Type: false | { source?: string }
• Default: automatic Ardo icon set

Ardo generates a lean favicon set at build time and serves it during development: /favicon.ico, /icon.svg, and /apple-touch-icon.png. This matches the modern minimal browser set without adding a web app manifest or legacy apple-touch-icon-precomposed.png files.

ardo({
  title: "My Docs",
  icons: {
    source: "./app/assets/logo.svg",
  },
})

Set icons: false if you want to manage all root icon files yourself from public/.

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 the package src/index.ts and generates route files under app/routes/api-reference/ in the default React Router scaffold.

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: "api-reference"

Output route directory for generated API documentation, relative to the configured routes directory.

typedoc.readme

• Type: string

Path to a README file TypeDoc should use as the generated project overview.

typedoc: {
  entryPoints: ["./src/index.ts"],
  readme: "./README.md",
}

typedoc.plugin

• Type: string[]

Additional TypeDoc plugin package names to load during API generation.

typedoc: {
  entryPoints: ["./src/index.ts"],
  plugin: ["typedoc-plugin-mdn-links"],
}

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.categoryOrder

• Type: string[]

Preferred order for TypeDoc categories.

typedoc: {
  entryPoints: ["./src/index.ts"],
  categoryOrder: ["Components", "Hooks", "Utilities"],
}

typedoc.groupOrder

• Type: string[]

Preferred order for TypeDoc groups.

typedoc: {
  entryPoints: ["./src/index.ts"],
  groupOrder: ["Functions", "Classes", "Interfaces", "Type Aliases"],
}

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 sections, footer, editLink, lastUpdated, and search are configured with JSX in your root.tsx using <ArdoRoot>. See Site UI Configuration for the ArdoRoot, header, footer, and sidebar-section reference.

Package Exports

Ardo keeps browser-safe runtime imports separate from build-time Node.js imports:

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",
      },
    }),
  ],
})