{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://basedoc.co/basedoc.schema.json",
  "title": "Basedoc Project Configuration",
  "description": "Schema for basedoc.json files used in Basedoc documentation projects",
  "type": "object",
  "required": ["title"],
  "properties": {
    "title": {
      "type": "string",
      "description": "The title of your documentation site. This is required and will be displayed in the site header and metadata.",
      "examples": ["My Documentation", "API Reference", "Product Docs"]
    },
    "description": {
      "type": "string",
      "description": "A brief description of your documentation site. Used for SEO and metadata.",
      "examples": [
        "Complete guide to our product",
        "API documentation and reference"
      ]
    },
    "theme": {
      "type": "string",
      "enum": ["default"],
      "description": "The theme to use for your documentation site. Defaults to 'default' if not specified.",
      "default": "default"
    },
    "layout": {
      "type": "string",
      "description": "The layout to use for your documentation site",
      "default": "default",
      "examples": ["default"]
    },
    "highlightColors": {
      "type": "object",
      "description": "Provide your brand color, which will be added to links, buttons and icons. If not provided, a standard grey colour will be used. If you provide only one color, it will be used for both modes. `darkMode` gives the option to use a more muted brand colour when your site is in dark mode.",
      "properties": {
        "lightMode": {
          "type": "string",
          "description": "A hex colour, e.g. #FF3300"
        },
        "darkMode": {
          "type": "string",
          "description": "A hex colour, e.g. #FF3300"
        }
      },
      "additionalProperties": false
    },
    "navigation": {
      "description": "Navigation array for simple sites. Use either 'navigation' (for simple sites) or 'sections' (for multi-section sites). Both are supported. Can contain strings (page paths), objects with title and path, or groups with title and pages. Groups can be nested to any depth.",
      "type": "array",
      "items": { "$ref": "#/$defs/navigationItem" }
    },
    "sections": {
      "description": "Sections allow you to organize your documentation into separate top-level areas (like 'API Docs' and 'Guides') with independent navigation lists. Each section can have its own navigation sidebar. Use either 'navigation' (for simple sites) or 'sections' (for multi-section sites).",
      "type": "array",
      "items": {
        "type": "object",
        "required": ["title", "navigation"],
        "properties": {
          "title": {
            "type": "string",
            "description": "Section title (e.g., 'API Reference', 'Guides')"
          },
          "path": {
            "type": "string",
            "description": "Optional: landing page path for this section. If specified, clicking the section title navigates to this path (e.g., 'api' looks for /api/index.mdx or /api.mdx). If omitted, navigates to the first page in the section's navigation."
          },
          "navigation": {
            "type": "array",
            "description": "Navigation array for this section. Same structure as root navigation (strings, link objects, or nested groups to any depth).",
            "items": { "$ref": "#/$defs/navigationItem" }
          }
        },
        "additionalProperties": false
      }
    },
    "homepage": {
      "description": "Your site's homepage is /index.mdx by default. If you want a different page to load at your site's root, use this config key. Can be a page path string or an object with path and title.",
      "oneOf": [
        {
          "type": "string",
          "description": "Page path (e.g., 'intro')",
          "default": "index",
          "examples": ["intro", "getting-started"]
        },
        {
          "type": "object",
          "required": ["path"],
          "properties": {
            "path": {
              "type": "string",
              "description": "Page path"
            },
            "title": {
              "type": "string",
              "description": "Optional title for the homepage"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "favicon": {
      "type": "string",
      "description": "Path to your favicon file in the /media folder.",
      "examples": ["/media/favicon.ico"]
    },
    "logo": {
      "type": "object",
      "description": "Path to the logo file in the /media folder. If you want to use a different logo for dark mode, you can provide a different logo in the darkMode property. If you don't provide a logo for dark mode, the light mode logo will be used in dark mode.",
      "properties": {
        "lightMode": {
          "type": "string",
          "examples": ["/media/logo.png"],
          "description": "Used in light mode. Path to the logo file in the /media folder."
        },
        "darkMode": {
          "type": "string",
          "examples": ["/media/logo-dark.png"],
          "description": "Used in dark mode. Path to the logo file in the /media folder."
        }
      },
      "additionalProperties": false
    },
    "externalLinks": {
      "type": "array",
      "description": "A list of external link items",
      "items": {
        "type": "object",
        "required": ["title", "href"],
        "properties": {
          "title": {
            "type": "string",
            "description": "The text displayed in the link"
          },
          "href": {
            "type": "string",
            "description": "The URL of the link"
          },
          "isExternal": {
            "type": "boolean",
            "description": "Whether the link is external. If true, the link will be opened in a new tab.",
            "default": false
          },
          "highlight": {
            "type": "boolean",
            "description": "Whether to highlight the link in an inverse design",
            "default": false
          }
        },
        "additionalProperties": false
      }
    },
    "api": {
      "type": "object",
      "description": "API documentation configuration",
      "properties": {
        "custom": {
          "type": "object",
          "description": "Custom API settings",
          "properties": {
            "serverUrl": {
              "type": "string",
              "description": "Default base URL for your API endpoints (e.g., 'https://api.example.com').",
              "examples": [
                "https://api.example.com",
                "https://api.example.com/v1"
              ]
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "postCollections": {
      "type": "array",
      "description": "Post collections for blog-type content (blogs, changelogs, product updates, etc.). Each collection defines a directory that contains date-based posts with automatic index pages and RSS feeds.",
      "items": {
        "type": "object",
        "required": ["directory"],
        "properties": {
          "directory": {
            "type": "string",
            "description": "Folder under docs root containing post files (e.g., 'blog', 'changelog'). Must be unique. Files in this directory must have a 'date' field in frontmatter.",
            "examples": ["blog", "changelog", "updates"]
          },
          "indexLayout": {
            "type": "string",
            "enum": ["list", "list-full", "list-compact"],
            "description": "Layout for the index page listing posts. 'list' shows titles, dates, and excerpts. 'list-full' renders complete post content. 'list-compact' shows titles and dates only.",
            "default": "list"
          },
          "pageSize": {
            "type": "number",
            "description": "Number of posts per index page. Defaults to 15.",
            "default": 15,
            "minimum": 1
          },
          "title": {
            "type": "string",
            "description": "Title for the collection (shown on index page and in meta tags). If omitted, defaults to capitalized directory name (e.g., 'blog' → 'Blog').",
            "examples": ["Product Blog", "Changelog", "Release Notes"]
          },
          "description": {
            "type": "string",
            "description": "Description for the collection (shown on index page and in meta tags/RSS feed).",
            "examples": ["Updates from our team", "Product changelog and release notes"]
          }
        },
        "additionalProperties": false
      }
    },
    "additionalProperties": false
  },
  "$defs": {
    "navigationItem": {
      "oneOf": [
        {
          "type": "string",
          "description": "Page path or URL path (e.g., 'page-slug', 'another-page')"
        },
        {
          "type": "object",
          "required": ["title", "path"],
          "properties": {
            "title": { "type": "string", "description": "Custom title for the navigation item" },
            "path": { "type": "string", "description": "Page path or URL path" }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": ["title", "pages"],
          "properties": {
            "title": { "type": "string", "description": "Group name for nested navigation" },
            "pages": {
              "type": "array",
              "description": "Nested items (strings, link objects, or nested groups — any depth).",
              "items": { "$ref": "#/$defs/navigationItem" }
            }
          },
          "additionalProperties": false
        }
      ]
    }
  },
  "examples": [
    {
      "title": "My Documentation",
      "description": "Complete guide to our product",
      "theme": "default",
      "navigation": [
        "getting-started",
        {
          "title": "API Reference",
          "path": "api/overview"
        },
        {
          "title": "Advanced Topics",
          "pages": ["advanced/deployment", "advanced/troubleshooting"]
        }
      ],
      "homepage": "getting-started"
    },
    {
      "title": "Product Documentation",
      "description": "Complete guide to our product",
      "theme": "default",
      "homepage": {
        "path": "intro",
        "title": "Welcome to our docs"
      },
      "sections": [
        {
          "title": "API Reference",
          "path": "api",
          "navigation": [
            "api/overview",
            {
              "title": "Authentication",
              "path": "api/auth"
            },
            {
              "title": "Endpoints",
              "pages": ["api/users", "api/posts", "api/comments"]
            }
          ]
        },
        {
          "title": "Guides",
          "path": "guides",
          "navigation": [
            "guides/getting-started",
            "guides/deployment",
            "guides/troubleshooting"
          ]
        }
      ],
      "navigation": []
    }
  ]
}