Skip to content

configuration.mdx

Latest commit

 

History

History
375 lines (313 loc) · 7.42 KB

configuration.mdx

File metadata and controls

375 lines (313 loc) · 7.42 KB
title Configuration
description Learn how to customize your ObjectDocs site through objectdocs.json and meta.json files.

import { Settings, Palette, Navigation, Layout } from 'lucide-react';

Configuration

ObjectDocs follows a Configuration as Code approach. All site settings are defined in JSON files, making it easy to version control and collaborate.

Global Configuration

objectdocs.json

The main configuration file is located at packages/site/objectdocs.json. This file controls global settings for your entire documentation site.

{
  "meta": {
    "title": "ObjectStack Docs",
    "description": "Enterprise-grade low-code platform documentation",
    "url": "https://docs.objectstack.ai",
    "favicon": "/favicon.ico"
  },
  "i18n": {
    "enabled": true,
    "defaultLanguage": "en",
    "languages": ["en", "cn"]
  },
  "branding": {
    "logo": {
      "text": "ObjectStack",
      "light": "/logo.svg",
      "dark": "/logo.svg"
    },
    "theme": {
      "accentColor": "blue",
      "radius": "0.5rem"
    }
  },
  "layout": {
    "navbar": {
      "enabled": true,
      "transparentMode": "top",
      "links": [
        {
          "text": "Home",
          "url": "https://www.objectstack.ai",
          "external": true
        }
      ],
      "socials": [
        { "platform": "github", "url": "https://github.com/objectstack-ai/" }
      ]
    },
    "sidebar": {
      "enabled": true,
      "prefetch": true,
      "defaultOpenLevel": 1,
      "collapsible": true
    },
    "toc": {
      "enabled": true,
      "depth": 3
    },
    "footer": {
      "enabled": false,
      "copyright": "© 2026 ObjectStack Inc."
    }
  },
  "page": {
    "showLastUpdate": true,
    "showEditLink": true,
    "repoBaseUrl": "https://github.com/objectstack-ai/docs"
  },
  "content": {
    "math": false,
    "imageZoom": true,
    "codeBlock": {
      "theme": "vesper",
      "showLineNumbers": true
    }
  }
}

Configuration Sections

Meta Settings

} title="Basic Info"> Configure site title, description, URL, and favicon } title="Branding"> Customize logo, theme colors, and visual style

meta

{
  "meta": {
    "title": "Your Site Title",
    "description": "Site description for SEO",
    "url": "https://docs.example.com",
    "favicon": "/favicon.ico"
  }
}

Internationalization (i18n)

Enable multi-language support:

{
  "i18n": {
    "enabled": true,
    "defaultLanguage": "en",
    "languages": ["en", "cn", "es", "fr"]
  }
}

When enabled, ObjectDocs will:

  • Create language-specific routes (/en/docs, /cn/docs)
  • Look for translated content in language-specific directories
  • Display language switcher in the navbar

Branding

Logo Configuration

{
  "branding": {
    "logo": {
      "text": "Your Brand",
      "light": "/logo-light.svg",
      "dark": "/logo-dark.svg"
    }
  }
}
  • text: Displayed next to the logo image
  • light: Logo for light mode
  • dark: Logo for dark mode (optional, falls back to light)

Theme

{
  "branding": {
    "theme": {
      "accentColor": "blue",
      "radius": "0.5rem"
    }
  }
}
  • accentColor: Primary theme color (blue, purple, green, etc.)
  • radius: Border radius for UI components

Layout Configuration

Navbar

} title="Navigation Links"> Add custom links to the top navigation bar } title="Social Links"> Connect to GitHub, Twitter, and other platforms 
{
  "layout": {
    "navbar": {
      "enabled": true,
      "transparentMode": "top",
      "links": [
        {
          "text": "Guide",
          "url": "/docs",
          "external": false
        },
        {
          "text": "Blog",
          "url": "https://blog.example.com",
          "external": true
        }
      ],
      "socials": [
        { "platform": "github", "url": "https://github.com/yourusername" },
        { "platform": "twitter", "url": "https://twitter.com/yourusername" }
      ]
    }
  }
}
  • transparentMode: "top" | "always" | "none"
  • links: Array of navigation links
  • socials: Social platform links (supports github, twitter, discord, etc.)

Sidebar

{
  "layout": {
    "sidebar": {
      "enabled": true,
      "prefetch": true,
      "defaultOpenLevel": 1,
      "collapsible": true,
      "tabs": []
    }
  }
}
  • prefetch: Prefetch linked pages for faster navigation
  • defaultOpenLevel: How many levels to expand by default (0 = collapsed, 1 = first level, etc.)
  • collapsible: Allow users to collapse sidebar sections
  • tabs: Optional sidebar tabs for multi-product docs

Table of Contents (TOC)

{
  "layout": {
    "toc": {
      "enabled": true,
      "depth": 3
    }
  }
}
  • depth: Maximum heading level to show (1-6)

Page Settings

{
  "page": {
    "showLastUpdate": true,
    "showEditLink": true,
    "repoBaseUrl": "https://github.com/yourusername/yourrepo"
  }
}
  • showLastUpdate: Display last modified date from git
  • showEditLink: Show "Edit this page" link
  • repoBaseUrl: GitHub repository URL for edit links

Content Settings

{
  "content": {
    "math": false,
    "imageZoom": true,
    "codeBlock": {
      "theme": "vesper",
      "showLineNumbers": true
    }
  }
}
  • math: Enable LaTeX math rendering
  • imageZoom: Allow users to click images to zoom
  • codeBlock.theme: Syntax highlighting theme
  • codeBlock.showLineNumbers: Display line numbers in code blocks

Local Configuration

meta.json

Each directory in content/docs/ can have a meta.json file to control its sidebar structure:

{
  "title": "Section Title",
  "pages": [
    "first-page",
    "second-page",
    "---Subsection---",
    "nested-directory"
  ]
}
**Critical**: The sidebar structure is **entirely** controlled by `meta.json` files. Never edit React components to change page ordering.

Page Order

The order of items in the pages array determines the sidebar order:

{
  "title": "Getting Started",
  "pages": [
    "installation",      // Appears first
    "architecture",      // Appears second
    "configuration"      // Appears third
  ]
}

Separators

Add visual separators in the sidebar:

{
  "pages": [
    "intro",
    "---Basic Guides---",
    "guide-1",
    "guide-2",
    "---Advanced---",
    "advanced-1"
  ]
}

Best Practices

### Keep Configuration DRY

Don't repeat configuration across multiple files. Use the global objectdocs.json for site-wide settings.

Use Semantic Names

Choose descriptive names for page slugs that reflect the content:

  • ✅ installation.mdx
  • ✅ api-reference.mdx
  • ❌ page1.mdx
  • ❌ doc.mdx

Version Control Everything

All configuration is in JSON files, making it easy to:

  • Track changes in git
  • Review configuration updates
  • Roll back if needed

Test Locally

Always run pnpm dev to verify configuration changes before deploying.

Next Steps

Understand how configuration flows through the system Learn about available components for your content