Configuration

All configuration for your Viabl project lives in a single docs.json file at the root of your project. Add the $schema field to get full intellisense and validation in VS Code.

json

{
  "$schema": "https://viabl.dev/schema/docs.json",
  "name": "My Docs",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction"]
    }
  ]
}

Only name and navigation are required. Everything else is optional.

Identity

namestringrequired

The name of your documentation site. Shown in the browser tab and header.

faviconstring

Path to your favicon relative to the project root.

json

  { "favicon": "/favicon.png" }

Logo

Controls the logo shown in the top left of your docs.

logo.lightstring

Path to the logo image used in light mode.

logo.darkstring

Path to the logo image used in dark mode.

logo.hrefstring

URL to navigate to when the logo is clicked. Defaults to the docs root.

json

"logo": {
  "light": "/logo/light.svg",
  "dark": "/logo/dark.svg",
  "href": "https://example.com"
}

Colors

Brand color configuration. Controls the accent colors used throughout your docs.

colors.primarystring

Base brand color used as the default accent. Example: #ff5800

colors.lightstring

Color variant for light backgrounds — usually darker or more saturated for contrast on white.

colors.darkstring

Color variant for dark backgrounds — usually lighter or more vibrant to pop on dark.

colors.background.lightstring

Background color for light mode. Supports CSS gradients.

colors.background.darkstring

Background color for dark mode. Supports CSS gradients.

colors.anchors.fromstring

Start color of the anchor icon gradient in the sidebar.

colors.anchors.tostring

End color of the anchor icon gradient in the sidebar.

json

"colors": {
  "primary": "#ff5800",
  "light": "#ff5800",
  "dark": "#ff7733",
  "background": {
    "dark": "radial-gradient(ellipse 80% 50% at 50% -20%, rgba(255,88,0,0.15), transparent), #0c0d0f",
    "light": "#ffffff"
  },
  "anchors": {
    "from": "#ff5800",
    "to": "#ce0569"
  }
}

Fonts

Custom font configuration for headings and body text.

font.headings.familystring

Font family name for headings. Example: Inter

font.headings.urlstring

URL to load the heading font from. Example: a Google Fonts CSS URL.

font.body.familystring

Font family name for body text.

font.body.urlstring

URL to load the body font from.

json

"font": {
  "headings": {
    "family": "Geist",
    "url": "https://fonts.googleapis.com/css2?family=Geist"
  },
  "body": {
    "family": "Geist",
    "url": "https://fonts.googleapis.com/css2?family=Geist"
  }
}

The sidebar navigation structure. Viabl supports three navigation formats — a simple array of groups, a dictionary mapped to tabs, and raw strings for headerless sidebar items.

navigationNavigationGroup[] | Record<string, NavigationGroup[]>required

The sidebar navigation structure. Accepts a flat array of groups for simple sites, or a dictionary object mapping tab URLs to navigation arrays for tabbed sites.

json

"navigation": [
  {
    "group": "Getting Started",
    "icon": "BookOpen",
    "pages": ["introduction", "getting-started"]
  }
]

See the Navigation page for all supported formats including dictionary navigation, persistent sidebar items, and raw string pages.

Top Bar

Links

topbarLinks[].namestringrequired

Display text for the link.

topbarLinks[].urlstringrequired

URL the link points to.

topbarLinks[].blankboolean

Whether the link opens in a new tab. Defaults to false.

json

"topbarLinks": [
  { "name": "Support", "url": "https://example.com/support", "blank": true }
]

CTA Button

topbarCtaButton.namestringrequired

Button label text.

topbarCtaButton.urlstringrequired

URL the button links to.

topbarCtaButton.style"fill" | "outline"

Visual style of the button. Defaults to fill.

topbarCtaButton.arrowboolean

Whether to show an arrow icon next to the label. Defaults to false.

topbarCtaButton.iconstring

Icon name to show inside the button.

topbarCtaButton.anchorboolean

Pin the button to the right side of the top bar.

json

"topbarCtaButton": {
  "name": "Get Started",
  "url": "https://example.com/signup",
  "style": "fill",
  "arrow": true
}

Tabs

Tabs shown below the top navigation bar for switching between major sections.

tabs[].namestringrequired

Tab label text.

tabs[].urlstringrequired

URL default path that should be open by default when we open the tab.

tabs[].iconstring

Icon name shown next to the tab label.

tabs[].anchorboolean

Pin this tab to the right side of the tab bar.

json

"tabs": [
  { "name": "Documentation", "url": "docs", "icon": "BookOpen" },
  { "name": "API Reference", "url": "api-reference", "icon": "Code2" }
  {"name": "Feedback", "url": "feedback", "icon": "Code2", "anchor": true }
]

Anchors

Special links shown at the top of the sidebar before navigation groups. Good for GitHub, Discord, or any external link you want to surface prominently.

anchors[].namestringrequired

Display name of the anchor link.

anchors[].urlstringrequired

URL the anchor links to.

anchors[].iconstring

Icon name shown next to the anchor.

anchors[].colorstring

Custom color for the anchor icon.

json

"anchors": [
  {
    "name": "GitHub",
    "icon": "Github",
    "url": "https://github.com/your-org/your-repo",
    "color": "#333333"
  },
  {
    "name": "Discord",
    "icon": "MessageCircle",
    "url": "https://discord.gg/your-invite",
    "color": "#5865f2"
  }
]

Versions

Show a version switcher in the top bar to let users switch between different versions of your docs.

versionsstring[]

List of version identifiers. Each version should have a corresponding folder at the project root.

defaultVersionstring

The version shown by default. Must match one of the values in versions.

json "versions": ["v1", "v2"], "defaultVersion": "v2"

Each version folder should mirror your root docs structure. For example v2/introduction.mdx serves the introduction page for version v2.

Social media links shown in the footer.

footerSocials.xstring

X (Twitter) profile URL.

footerSocials.githubstring

GitHub profile or organization URL.

footerSocials.linkedinstring

LinkedIn profile or company URL.

footerSocials.discordstring

Discord invite URL.

footerSocials.youtubestring

YouTube channel URL.

footerSocials.websitestring

Your main website URL.

json

"footerSocials": {
  "github": "https://github.com/your-org",
  "x": "https://x.com/your-handle",
  "discord": "https://discord.gg/your-invite"
}

SEO

seo.indexHidingboolean

Set to true to prevent search engines from indexing your entire docs site. Defaults to false. To hide individual pages only, use noIndex in page frontmatter.

seo.og.titlestring

Title shown in social media previews.

seo.og.descriptionstring

Description shown in social media previews.

seo.og.imagestring

Path to the Open Graph image. Recommended size is 1200 × 630px.

aiScrapingboolean

Whether to allow known AI crawlers to index your docs. Defaults to true. Set to false to block AI bots via the generated robots.txt.

json

"aiScraping": false,
"seo": {
  "indexHiding": false,
  "og": {
    "title": "My Docs",
    "description": "Documentation for My Product",
    "image": "/og-image.png"
  }
}

Viabl also generates a sitemap, robots.txt, and llms.txt automatically. See the SEO & Discoverability page for the full reference.

Search

search.promptstring

Placeholder text shown in the search bar. Defaults to Search documentation...

json

"search": {
  "prompt": "Search the docs..."
}

AI assistant

Add an AI assistant to your docs that answers user questions grounded in your content.

ai.provider"anthropic" | "openai" | "ollama"required

The AI provider to use.

ai.apiKeystring

Your API key. Supports ${ENV_VAR} interpolation — never commit keys directly.

ai.modelstring

The model to use for responses.

ai.suggestedQuestionsstring[]

Starter questions shown to users when they open the assistant.

ai.rulesstring[]

Instructions the AI strictly follows when responding.

json

"ai": {
  "provider": "anthropic",
  "apiKey": "${ANTHROPIC_API_KEY}",
  "suggestedQuestions": [
    "How do I get started?",
    "How do I deploy my docs?"
  ]
}

See the AI Assistant page for the full reference including Ollama setup and environment variable usage.

Feedback

Let readers rate pages, suggest edits, or raise issues directly from your docs.

feedback.thumbsRatingboolean

Show thumbs up/down rating buttons at the bottom of each page.

feedback.suggestEditboolean

Show a Suggest Edit link that opens the page source on GitHub.

feedback.raiseIssueboolean

Show a Raise Issue link that opens a new GitHub issue.

feedback.webhookstring

URL to POST feedback data to when a user submits a rating.

feedback.githubRepostring

GitHub repository URL used for Suggest Edit and Raise Issue links.

json

"feedback": {
  "thumbsRating": true,
  "suggestEdit": true,
  "raiseIssue": true,
  "githubRepo": "https://github.com/your-org/your-repo"
}