Configuration

Configure site metadata, content roots, build modes, theme, search, AI, SEO, checks, Cloudflare, and i18n.

Most site behavior is configured in svedocs.config.ts at the project root. Export defineConfig from this file so the Vite plugin, CLI, runtime utilities, checks, and OG image generator all use the same settings.

TypeScriptsvedocs.config.ts
1import { defineConfig } from 'svedocs/config';23export default defineConfig({4  site: {5    name: 'My docs',6    title: 'My docs',7    description: 'Documentation built with svedocs',8    url: 'https://example.com'9  },10  content: {11    root: 'content',12    docs: 'content/docs',13    pages: 'content/pages'14  },15  build: {16    mode: 'edge'17  }18});

Site metadata

TypeScript
1export default defineConfig({2  site: {3    name: 'Acme Docs',4    title: 'Acme Docs',5    description: 'Guides and API references for Acme.',6    url: 'https://docs.acme.com'7  }8});

The theme displays site.name, while site.title becomes the default document title. site.description is used when a page has no description of its own. Set site.url on public sites so canonical links, sitemap entries, Open Graph URLs, and language alternates can be absolute.

Content roots

TypeScript
1export default defineConfig({2  content: {3    root: 'content',4    docs: 'content/docs',5    pages: 'content/pages',6    include: ['**/*.{md,mdx,svx}'],7    exclude: ['**/_drafts/**']8  }9});

docs content participates in docs navigation. pages content becomes standalone site pages. Keep drafts outside the include pattern or exclude them explicitly.

Build modes

TypeScript
1export default defineConfig({2  build: {3    mode: 'edge'4  }5});

Mode	Output	Use it when
`edge`	Cloudflare-oriented SSR.	You need runtime routes for hosted search, Ask AI, or dynamic responses.
`static`	Fully prerendered site.	Your docs can be served as static files and runtime features can use local alternatives.
`spa`	Prerendered known pages plus a static fallback page.	A constrained host needs client-side routing.

You can override the configured mode with SVEDOCS_BUILD_MODE or svedocs build --mode <mode>.

Theme

TypeScript
1export default defineConfig({2  theme: {3    defaultMode: 'system',4    palette: {5      accent: '#3f7df6',6      neutral: '#737373'7    },8    fonts: {9      sans: 'Inter',10      mono: 'JetBrains Mono'11    },12    radius: '4px',13    codeTheme: {14      light: 'github-light',15      dark: 'github-dark'16    },17    code: {18      lineNumbers: true,19      wrap: false20    },21    brand: {22      label: 'Acme',23      href: '/',24      logo: '/logo.svg',25      mark: 'pixel'26    },27    nav: [28      { label: 'Docs', labelKey: 'nav.docs', href: '/docs' },29      { label: 'API', labelKey: 'nav.api', href: '/docs/reference/api' }30    ],31    social: [32      { label: 'GitHub', href: 'https://github.com/acme/docs', external: true }33    ],34    footer: {35      text: 'Built with svedocs',36      links: [{ label: 'Status', href: '/status' }]37    }38  }39});

Theme settings are consumed by the default components and CSS variables. Use Theme for deeper styling details.

Search

TypeScript
1export default defineConfig({2  search: {3    enabled: true,4    provider: 'local',5    scope: 'current'6  }7});

Available providers:

Provider	Notes
`local`	Default MiniSearch-backed route, no external service required.
`algolia`	Uses server-side credentials to query an Algolia index.
`typesense`	Queries a Typesense collection over REST.
`cloudflare-ai-search`	Uses Cloudflare AI Search bindings or API indexing.

Set search: false to remove search from the theme and its related runtime utilities.

Ask AI

TypeScript
1export default defineConfig({2  ai: {3    enabled: true,4    provider: 'mock',5    label: 'Ask AI',6    placeholder: 'Ask about these docs...',7    suggestions: [8      'How do I deploy to Cloudflare?',9      'How do I configure search?'10    ],11    maxResults: 612  }13});

Choose from mock, cloudflare-ai-search, cloudflare-workers-ai, and openai-compatible. The mock provider works without credentials and is useful while writing the site. Connect a hosted service once the content and question flow are ready to test with real responses.

SEO and OG

TypeScript
1export default defineConfig({2  seo: {3    sitemap: true,4    robots: true,5    defaultAuthor: 'Acme',6    head: {7      meta: [8        { name: 'google-site-verification', content: 'verification-token' }9      ],10      links: [11        { rel: 'alternate', type: 'application/rss+xml', href: '/feed.xml', title: 'RSS' }12      ],13      jsonLd: [14        { '@type': 'Organization', name: 'Acme' }15      ]16    },17    ogImage: {18      template: 'default',19      format: 'svg',20      outDir: 'static/og',21      renderer: 'svg'22    }23  }24});

Set seo.ogImage = false to disable automatic OG generation. Use SVG for portable edge/runtime output. Use PNG or Satori when you need richer build-time images and can provide fonts.

seo.head is for serializable head additions that should appear on every page, such as verification meta tags, feed links, preload links, and organization-level JSON-LD. Page frontmatter can also define head for page-specific additions.

Source links

TypeScript
1export default defineConfig({2  source: {3    editBaseUrl: 'https://github.com/acme/docs/edit/main'4  }5});

The default theme can use this to show edit links. svedocs also records file timestamps as lastUpdated metadata.

Checks

TypeScript
1export default defineConfig({2  checks: {3    assets: true,4    externalLinks: false,5    translations: true6  }7});

Run these checks with svedocs check. External link checks need network access and can slow down CI, so they are disabled by default.

Cloudflare

TypeScript
1export default defineConfig({2  cloudflare: {3    compatibilityDate: '2026-05-18',4    aiSearch: {5      binding: 'SVEDOCS_AI_SEARCH',6      instanceName: 'acme-docs',7      remote: false8    }9  }10});

These settings feed the deployment utilities, generated Wrangler config, platform types, AI Search routes, and Workers AI routes.

i18n

TypeScript
1export default defineConfig({2  i18n: {3    defaultLocale: 'en',4    prefixDefaultLocale: false,5    locales: [6      { code: 'en', label: 'English', hreflang: 'en', dir: 'ltr' },7      { code: 'zh', label: '中文', path: 'zh', hreflang: 'zh-CN', dir: 'ltr' }8    ],9    messages: {10      zh: {11        'search.placeholder': '搜索文档',12        'ask.label': '问 AI',13        'home.primaryAction': '阅读文档'14      }15    }16  }17});

Locale settings control routes, sidebars, search filters, Ask AI citations, SEO alternates, and translation checks. hreflang is used in <link rel="alternate">, sitemap alternates, Open Graph locale tags, and JSON-LD inLanguage. Set dir to rtl for right-to-left languages.

Use i18n.messages to translate the interface around your content, including navigation, search, Ask AI, the table of contents, article actions, code-copy labels, landing-page cards, errors, and footer text. English is the base catalog, even when i18n: false, so each locale only needs to override the messages it changes.

See Internationalization for content layout, route mapping, custom message keys, locale-aware links, SEO behavior, and translation checks.

Markdown hooks

TypeScript
1export default defineConfig({2  markdown: {3    remarkPlugins: [],4    rehypePlugins: [],5    shiki: {6      transformers: []7    }8  }9});

Markdown hooks run at compile time while svedocs builds the page list and renders SVX or MDX. They are never serialized into browser virtual modules.

A practical setup order

For a new production site, this order keeps each step easy to verify:

site, content, and build.
theme and navigation.
seo, sitemap, robots, and OG images.
search and ai local behavior.
Hosted services and Cloudflare bindings.
checks and CI commands.

At step four, the site is already usable locally. The remaining steps prepare it for external services and CI.