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. An array of groups each containing pages or nested groups.

navigation[].groupstringrequired

Display name of the navigation group shown in the sidebar.

navigation[].iconstring

Icon name shown next to the group label.

navigation[].pagesstring[] | NavigationGroup[]required

Pages or nested groups inside this group. Pages are slugs relative to the project root with no file extension — introduction maps to introduction.mdx.

json

"navigation": [
  {
    "group": "Getting Started",
    "icon": "BookOpen",
    "pages": ["introduction", "getting-started"]
  },
  {
    "group": "Guides",
    "pages": [
      "guides/overview",
      {
        "group": "Advanced",
        "pages": ["guides/advanced/custom-domain"]
      }
    ]
  }
]

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 path this tab links to.

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

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 docs. Defaults to false.

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. Example: /og-image.png

json

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

Search

search.promptstring

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

json

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

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