Guides
View as Markdown Open in ChatGPT Open in Claude

syntext.json

The syntext.json file is the central configuration for your documentation site. It controls navigation, theming, integrations, and more.

Basic Structure

{
  "name": "My Docs",
  "description": "Documentation for My Product",
  "theme": "default",
  "colors": {
    "primary": "#6366F1"
  },
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["index", "getting-started"]
    }
  ]
}

Required Fields

name

The project name. Displayed in the header and browser tab.

{
  "name": "My API Docs"
}

Defines the sidebar navigation structure. See Navigation for details.

{
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["index", "quickstart"]
    }
  ]
}

Site Metadata

description

Meta description for SEO and social previews.

{
  "description": "Complete API documentation for MyProduct"
}

github

Link to your GitHub repository. Shown in the header.

{
  "github": "https://github.com/yourorg/yourrepo"
}

Social media links displayed in the header.

{
  "socialLinks": [
    { "platform": "GitHub", "url": "https://github.com/yourorg" },
    { "platform": "X", "url": "https://x.com/yourhandle" },
    { "platform": "Discord", "url": "https://discord.gg/yourserver" }
  ]
}

Supported platforms: GitHub, X, Discord, LinkedIn, YouTube, Slack.

Branding

Logo images for light and dark modes.

{
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg"
  }
}

Or a single logo:

{
  "logo": "/logo.svg"
}

favicon

Favicon configuration.

{
  "favicon": "/favicon.ico"
}

Advanced favicon configuration:

{
  "favicon": {
    "default": "/favicon.ico",
    "apple": "/apple-touch-icon.png",
    "32": "/favicon-32x32.png",
    "16": "/favicon-16x16.png"
  }
}

colors

Brand colors.

{
  "colors": {
    "primary": "#6366F1",
    "accent": "#2AC3DE",
    "background": "#0F172A"
  }
}
Property Description
primary Main brand color (links, buttons, active states)
accent Secondary color for highlights
background Page background (dark mode)

tabs

Top-level navigation tabs.

{
  "tabs": [
    { "name": "Guides", "url": "/guides", "icon": "book" },
    { "name": "API", "url": "/api-reference", "icon": "api" },
    { "name": "SDKs", "url": "/sdks", "icon": "code" }
  ]
}

anchors

Quick links displayed below the search bar.

{
  "anchors": [
    { "name": "API Status", "url": "https://status.example.com", "icon": "signal" },
    { "name": "Support", "url": "mailto:support@example.com", "icon": "help" }
  ]
}

OpenAPI Integration

openapi

Path or URL to your OpenAPI specification.

{
  "openapi": "./openapi.json"
}

Remote URL:

{
  "openapi": "https://api.example.com/openapi.json"
}

Multiple specs (microservices):

{
  "openapi": [
    { "path": "./specs/users.yaml", "prefix": "/api/users" },
    { "path": "./specs/orders.yaml", "prefix": "/api/orders" }
  ]
}

Versioning

versions

Enable versioned documentation.

{
  "versions": [
    { "name": "v3", "branch": "main", "default": true },
    { "name": "v2", "branch": "v2" },
    { "name": "v1", "branch": "v1", "deprecated": true }
  ]
}

Theme Configuration

theme

Theme preset name.

{
  "theme": "default"
}

Available themes: default, minimal, developer.

fonts

Custom font configuration.

{
  "fonts": {
    "heading": "Plus Jakarta Sans",
    "body": "Inter",
    "mono": "JetBrains Mono"
  }
}

codeTheme

Syntax highlighting theme.

{
  "codeTheme": "one-dark-pro"
}

Options: one-dark-pro, github-dark, dracula, nord, monokai.

Custom Code

customCSS

Path to custom CSS file.

{
  "customCSS": "/custom.css"
}

scripts

Custom JavaScript files.

{
  "scripts": [
    { "src": "https://analytics.example.com/script.js", "async": true },
    { "src": "/custom.js", "defer": true }
  ]
}

Site Features

Top announcement banner.

{
  "banner": {
    "text": "🚀 Version 2.0 is now available!",
    "link": "/changelog/v2",
    "dismissible": true
  }
}

Search configuration.

{
  "search": {
    "enabled": true,
    "placeholder": "Search docs..."
  }
}

ai

AI assistant configuration.

{
  "ai": {
    "enabled": true,
    "placeholder": "Ask a question..."
  }
}

Redirects

redirects

URL redirect rules.

{
  "redirects": [
    { "from": "/old-path", "to": "/new-path" },
    { "from": "/docs/*", "to": "/:splat" }
  ]
}

Every doc site renders a full-width footer band at the bottom of each page. By default it shows your social links (from socialLinks and github) alongside a "Powered by Syntext" credit.

Add footer.columns to upgrade to a rich footer with your logo, social icons, and grouped link columns — similar to what you'd find on a marketing site.

{
  "footer": {
    "columns": [
      {
        "title": "Product",
        "links": [
          { "label": "Documentation", "url": "/guides/quickstart" },
          { "label": "API Reference", "url": "/api-reference/overview" }
        ]
      },
      {
        "title": "Legal",
        "links": [
          { "label": "Privacy Policy", "url": "https://example.com/privacy" },
          { "label": "Terms of Service", "url": "https://example.com/terms" }
        ]
      }
    ]
  }
}

Each column takes:

Field Type Description
title string Column heading (optional)
links array Links in the column — each needs a label and a url

Behavior:

  • Full-bleed — the footer spans the entire viewport width, outside the content grid, on both guide and API reference pages
  • Relative URLs (/guides/...) navigate within your doc site; absolute URLs (https://...) open in a new tab
  • The brand column shows your logo (light/dark aware), project name, and social icons automatically
  • Columns with no valid links are skipped; omit footer entirely to keep the compact default footer

Complete Example

{
  "name": "Acme API",
  "description": "Complete API documentation for Acme Platform",
  "theme": "default",
  "logo": {
    "light": "/logo-light.svg",
    "dark": "/logo-dark.svg"
  },
  "favicon": "/favicon.ico",
  "colors": {
    "primary": "#6366F1",
    "accent": "#2AC3DE"
  },
  "github": "https://github.com/acme/api",
  "socialLinks": [
    { "platform": "GitHub", "url": "https://github.com/acme" },
    { "platform": "Discord", "url": "https://discord.gg/acme" }
  ],
  "tabs": [
    { "name": "Guides", "url": "/guides", "icon": "book" },
    { "name": "API Reference", "url": "/api-reference", "icon": "api" }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["index", "quickstart", "authentication"]
    },
    {
      "group": "Guides",
      "pages": ["guides/webhooks", "guides/pagination", "guides/errors"]
    }
  ],
  "openapi": "./openapi.json",
  "ai": { "enabled": true },
  "footer": {
    "columns": [
      {
        "title": "Product",
        "links": [
          { "label": "Documentation", "url": "/guides/quickstart" },
          { "label": "Pricing", "url": "https://acme.com/pricing" }
        ]
      },
      {
        "title": "Company",
        "links": [
          { "label": "About", "url": "https://acme.com/about" },
          { "label": "Blog", "url": "https://acme.com/blog" }
        ]
      }
    ]
  }
}
Was this page helpful?