{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "https://viabl.dev/schema/docs.json",
    "title": "Viabl Docs Configuration",
    "description": "Configuration file for a Viabl documentation project.",
    "type": "object",
    "required": [
        "name",
        "navigation"
    ],
    "additionalProperties": false,
    "properties": {
        "$schema": {
            "type": "string",
            "description": "Points to the Viabl docs.json schema for editor intellisense and validation."
        },
        "name": {
            "type": "string",
            "description": "The name of your documentation site. Shown in the browser tab and header."
        },
        "url": {
            "type": "string",
            "description": "THe domain that your docs is hosted under. SUitable for OG sahring sutemaps and llms"
        },
        "favicon": {
            "type": "string",
            "description": "Path to your favicon relative to the project root. Example: /favicon.ico"
        },
        "versions": {
            "type": "array",
            "description": "List of documentation versions to show in the version switcher.",
            "items": {
                "type": "string"
            },
            "examples": [
                [
                    "v1",
                    "v2"
                ]
            ]
        },
        "defaultVersion": {
            "type": "string",
            "description": "The version shown by default when no version is selected. Must match one of the values in 'versions'."
        },
        "logo": {
            "type": "object",
            "description": "Logo configuration for light and dark mode.",
            "additionalProperties": false,
            "properties": {
                "light": {
                    "type": "string",
                    "description": "Path to the logo image used in light mode. Example: /logo-light.png"
                },
                "dark": {
                    "type": "string",
                    "description": "Path to the logo image used in dark mode. Example: /logo-dark.png"
                },
                "href": {
                    "type": "string",
                    "description": "URL to navigate to when the logo is clicked. Defaults to the docs root."
                }
            }
        },
        "font": {
            "type": "object",
            "description": "Custom font configuration for headings and body text.",
            "additionalProperties": false,
            "properties": {
                "headings": {
                    "type": "object",
                    "description": "Font used for all headings.",
                    "additionalProperties": false,
                    "required": [
                        "family"
                    ],
                    "properties": {
                        "family": {
                            "type": "string",
                            "description": "Font family name. Example: Inter"
                        },
                        "url": {
                            "type": "string",
                            "description": "URL to load the font from. Example: https://fonts.googleapis.com/css2?family=Inter"
                        }
                    }
                },
                "body": {
                    "type": "object",
                    "description": "Font used for body text.",
                    "additionalProperties": false,
                    "required": [
                        "family"
                    ],
                    "properties": {
                        "family": {
                            "type": "string",
                            "description": "Font family name. Example: Inter"
                        },
                        "url": {
                            "type": "string",
                            "description": "URL to load the font from. Example: https://fonts.googleapis.com/css2?family=Inter"
                        }
                    }
                }
            }
        },
        "colors": {
            "type": "object",
            "description": "Brand color configuration. Controls the accent colors used throughout the docs.",
            "additionalProperties": false,
            "properties": {
                "primary": {
                    "type": "string",
                    "description": "Base brand color used as the default accent. Example: #6366f1"
                },
                "light": {
                    "type": "string",
                    "description": "Color variant for light backgrounds — usually darker/more saturated for contrast on white. Example: #4f46e5"
                },
                "dark": {
                    "type": "string",
                    "description": "Color variant for dark backgrounds — usually lighter/more vibrant to pop on dark. Example: #818cf8"
                },
                "background": {
                    "type": "object",
                    "description": "Background colors for light and dark mode.",
                    "additionalProperties": false,
                    "properties": {
                        "light": {
                            "type": "string",
                            "description": "Background color for light mode. Supports CSS gradients. Example: #ffffff or linear-gradient(135deg, #f5f7fa, #c3cfe2)"
                        },
                        "dark": {
                            "type": "string",
                            "description": "Background color for dark mode. Supports CSS gradients. Example: #0f0f0f or linear-gradient(135deg, #0f0c29, #302b63, #24243e)"
                        }
                    }
                },
                "anchors": {
                    "type": "object",
                    "description": "Gradient colors used for anchor icons in the sidebar.",
                    "additionalProperties": false,
                    "properties": {
                        "from": {
                            "type": "string",
                            "description": "Start color of the anchor icon gradient. Example: #6366f1"
                        },
                        "to": {
                            "type": "string",
                            "description": "End color of the anchor icon gradient. Example: #8b5cf6"
                        }
                    }
                }
            }
        },
        "topbarLinks": {
            "type": "array",
            "description": "Links shown in the top navigation bar.",
            "items": {
                "type": "object",
                "required": [
                    "name",
                    "url"
                ],
                "additionalProperties": false,
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Display text for the link."
                    },
                    "url": {
                        "type": "string",
                        "description": "URL the link points to."
                    },
                    "blank": {
                        "type": "boolean",
                        "description": "Dtetermines whether the link opens in a new tab or  on the same tab"
                    }
                }
            }
        },
        "topbarCtaButton": {
            "type": "object",
            "description": "A prominent call-to-action button in the top navigation bar.",
            "required": [
                "name",
                "url"
            ],
            "additionalProperties": false,
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Button label text."
                },
                "url": {
                    "type": "string",
                    "description": "URL the button links to."
                },
                "style": {
                    "type": "string",
                    "enum": [
                        "fill",
                        "outline"
                    ],
                    "description": "Visual style of the button. 'fill' is solid background, 'outline' is bordered.",
                    "default": "fill"
                },
                "arrow": {
                    "type": "boolean",
                    "description": "Whether to show an arrow icon next to the button label.",
                    "default": false
                },
                "icon": {
                    "type": "string",
                    "description": "Icon name to show inside the button."
                },
                "anchor": {
                    "type": "boolean",
                    "description": "Pin the button to the right side of the top bar.",
                    "default": false
                },
                "blank": {
                    "type": "boolean",
                    "description": "Dtetermines whether the link opens in a new tab or  on the same tab"
                }
            }
        },
        "tabs": {
            "type": "array",
            "description": "Tabs shown below the top navigation bar for switching between major sections.",
            "items": {
                "type": "object",
                "required": [
                    "name",
                    "url"
                ],
                "additionalProperties": false,
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Tab label text."
                    },
                    "url": {
                        "type": "string",
                        "description": "URL path this tab links to."
                    },
                    "icon": {
                        "type": "string",
                        "description": "Icon name to show next to the tab label."
                    },
                    "anchor": {
                        "type": "boolean",
                        "description": "Pin this tab to the right side of the tab bar.",
                        "default": false
                    }
                }
            }
        },
        "anchors": {
            "type": "array",
            "description": "Special links shown at the top of the sidebar before the navigation groups. Good for GitHub, Discord, etc.",
            "items": {
                "type": "object",
                "required": [
                    "name",
                    "url"
                ],
                "additionalProperties": false,
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Display name of the anchor link."
                    },
                    "icon": {
                        "type": "string",
                        "description": "Icon name to show next to the anchor."
                    },
                    "url": {
                        "type": "string",
                        "description": "URL the anchor links to."
                    },
                    "color": {
                        "type": "string",
                        "description": "Custom color for the anchor icon. Example: #6366f1"
                    }
                }
            }
        },
        "navigation": {
            "type": "array",
            "description": "The sidebar navigation structure. An array of groups, each containing pages or nested groups.",
            "items": {
                "$ref": "#/$defs/NavigationGroup"
            }
        },
        "footerSocials": {
            "type": "object",
            "description": "Social media links shown in the footer.",
            "additionalProperties": false,
            "properties": {
                "x": {
                    "type": "string",
                    "description": "X (Twitter) profile URL."
                },
                "github": {
                    "type": "string",
                    "description": "GitHub profile or organization URL."
                },
                "linkedin": {
                    "type": "string",
                    "description": "LinkedIn profile or company URL."
                },
                "discord": {
                    "type": "string",
                    "description": "Discord invite URL."
                },
                "youtube": {
                    "type": "string",
                    "description": "YouTube channel URL."
                },
                "website": {
                    "type": "string",
                    "description": "Your main website URL."
                }
            }
        },
        "seo": {
            "type": "object",
            "description": "SEO and social sharing configuration.",
            "additionalProperties": false,
            "properties": {
                "indexHiding": {
                    "type": "boolean",
                    "description": "Set to true to prevent search engines from indexing your documentation.",
                    "default": false
                },
                "og": {
                    "type": "object",
                    "description": "Open Graph metadata — controls how your docs appear when shared on social media.",
                    "additionalProperties": false,
                    "properties": {
                        "title": {
                            "type": "string",
                            "description": "Title shown in social media previews."
                        },
                        "description": {
                            "type": "string",
                            "description": "Description shown in social media previews."
                        },
                        "image": {
                            "type": "string",
                            "description": "Path to the Open Graph image. Example: /og-image.png"
                        }
                    }
                }
            }
        },
        "search": {
            "type": "object",
            "description": "Search bar configuration.",
            "additionalProperties": false,
            "properties": {
                "prompt": {
                    "type": "string",
                    "description": "Placeholder text shown in the search bar.",
                    "default": "Search documentation..."
                }
            }
        },
        "feedback": {
            "type": "object",
            "description": "User feedback configuration. Lets readers rate pages, suggest edits, or raise issues.",
            "additionalProperties": false,
            "properties": {
                "thumbsRating": {
                    "type": "boolean",
                    "description": "Show thumbs up/down rating buttons at the bottom of each page.",
                    "default": false
                },
                "suggestEdit": {
                    "type": "boolean",
                    "description": "Show a 'Suggest Edit' link that opens the page source on GitHub.",
                    "default": false
                },
                "raiseIssue": {
                    "type": "boolean",
                    "description": "Show a 'Raise Issue' link that opens a new GitHub issue.",
                    "default": false
                },
                "webhook": {
                    "type": "string",
                    "description": "URL to POST feedback data to when a user submits a rating."
                },
                "githubRepo": {
                    "type": "string",
                    "description": "GitHub repository URL used for 'Suggest Edit' and 'Raise Issue' links. Example: https://github.com/your-org/your-repo"
                }
            }
        }
    },
    "$defs": {
        "NavigationGroup": {
            "type": "object",
            "description": "A navigation group containing pages or nested groups.",
            "required": [
                "group",
                "pages"
            ],
            "additionalProperties": false,
            "properties": {
                "group": {
                    "type": "string",
                    "description": "Display name of the navigation group shown in the sidebar."
                },
                "icon": {
                    "type": "string",
                    "description": "Icon name shown next to the group label."
                },
                "pages": {
                    "type": "array",
                    "description": "Pages or nested groups inside this group. Pages are slugs relative to the project root with no file extension. Example: 'introduction' maps to introduction.mdx",
                    "items": {
                        "oneOf": [
                            {
                                "type": "string",
                                "description": "Page slug relative to the project root. Example: guides/getting-started"
                            },
                            {
                                "$ref": "#/$defs/NavigationGroup"
                            }
                        ]
                    }
                }
            }
        }
    }
}