---
title: Configuration Overview & Schema
description: Comprehensive reference for VertiWiki's runtime configuration file (config.json) and design options.
tags: [vertiwiki, configuration, schema, settings, config-json]
---

# Configuration Overview & Schema

> For the complete documentation index and agent navigation, see [llms.txt](/llms.txt).

VertiWiki's behavior is driven entirely by a declarative `config.json` file placed in your wiki root directory. Changes take effect on the next browser refresh without requiring any build step.

---

## 📄 Minimal Working Configuration

```json
{
  "title": "My Knowledge Hub",
  "navigationFile": "navigation.md",
  "homePage": "index.md"
}
```

---

## 🛠️ Full Configuration Schema Reference

| Property | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `title` | `string` | `"VertiWiki"` | Name of the documentation portal displayed in navbar and document `<title>`. |
| `logo` | `string` | `undefined` | Path to header logo image (SVG, PNG, WebP). |
| `favicon` | `string` | `undefined` | Path to custom favicon asset. |
| `brandDisplay` | `'both' \| 'logo' \| 'title'` | `'both'` | Controls whether the header renders logo only, title only, or both. |
| `useSideMenu` | `boolean` | `true` | Toggles the hierarchical sidebar navigation tree. |
| `useTableOfContents` | `boolean` | `true` | Toggles the right-hand "On this page" TOC column. |
| `enableSearch` | `boolean` | `true` | Enables in-memory full-text search with MiniSearch and modal shortcut (<kbd>⌘K</kbd>). |
| `enableMath` | `boolean` | `true` | Enables KaTeX LaTeX mathematical formula rendering. |
| `enableMermaid` | `boolean` | `true` | Enables Mermaid diagram and flowchart compilation. |
| `enableCodeCopy` | `boolean` | `true` | Injects a copy button on all code fence headers. |
| `enableAiCopy` | `boolean` | `true` | Enables "Copy for AI" prompt export button in document headers. |
| `enableThemeChooser` | `boolean` | `true` | Shows the theme preset dropdown switcher in navbar. |
| `enableLanguageChooser` | `boolean` | `false` | Shows the multi-language switcher dropdown in navbar. |
| `locales` | `LocaleConfig[]` | `[]` | Array of supported language locales (see [Multi-Language Settings](#multi-language-settings)). |
| `collapsibleNavigation`| `boolean` | `true` | Enables folding/expanding category accordion groups in sidebar. |
| `defaultTheme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Initial theme mode before user preference is saved to `localStorage`. |
| `themePreset` | `string` | `'default'` | Active color theme preset ID (e.g. `'obsidian'`, `'dracula'`, `'nord'`). |
| `customThemes` | `string[] \| object[]` | `[]` | Array of standalone theme JSON paths (e.g. `["themes/obsidian.json"]`) or theme objects. |
| `layoutMode` | `string` | `'default'` | Global layout style: `'default'`, `'book'`, `'handbook'`, `'api'`, or `'hub'`. |
| `contentWidth` | `'normal' \| 'readable' \| 'full'` | `'normal'` | Max width constraint: normal (850px), readable (68ch), or full (100%). |
| `headerLinks` | `HeaderLinkItem[]` | `[]` | Custom external links and action buttons rendered in header. |
| `customCss` | `string \| string[]` | `undefined` | Path to custom external CSS stylesheet(s) for brand overrides. |
| `navigationFile` | `string` | `"navigation.md"`| Markdown file defining the sidebar navigation tree. |
| `homePage` | `string` | `"index.md"` | Default Markdown file loaded on root URL visit. |
| `llmsTxtUrl` | `string` | `"llms.txt"` | Relative or absolute path to structured AI agent index file. |
| `footerText` | `string` | `undefined` | Custom footer text or HTML rendered at the bottom of pages. |
| `githubUrl` | `string` | `undefined` | Repository URL linking to GitHub in header. |

---

## 🌐 Multi-Language Settings (`locales`)

When defining multi-language mirrors, configure the `locales` array:

```json
{
  "enableLanguageChooser": true,
  "locales": [
    { "code": "en", "label": "English", "isDefault": true },
    { "code": "ro", "label": "Română", "prefix": "ro" },
    { "code": "fr", "label": "Français", "prefix": "fr" }
  ]
}
```

- `code`: ISO 639-1 language code.
- `label`: Human-readable label displayed in the switcher dropdown.
- `prefix`: URL subfolder path prefix for this language.
- `isDefault`: Marks the primary canonical language (loaded without prefix).

---

## 📊 Privacy-Focused Analytics Integration

VertiWiki includes zero-dependency telemetry integrations. Simply declare the matching provider ID:

```json
{
  "googleAnalyticsId": "G-XXXXXXXXXX",
  "gtmId": "GTM-XXXXXXX",
  "plausibleDomain": "docs.example.com",
  "cloudflareToken": "abcdef123456",
  "umamiWebsiteId": "12345678-1234-1234-1234-1234567890ab",
  "umamiScriptUrl": "https://analytics.umami.is/script.js",
  "matomoUrl": "https://analytics.example.com/",
  "matomoSiteId": "1"
}
```

---

## 🔗 Next Steps

- Learn how to configure security and sandbox boundaries in [Security & CSP Boundaries](security.md).
- Explore hosting and deployment recipes in the [Operational Runbook](../operations/runbook.md).