@umami/shiso 0.55.0 → 0.61.0

package/docs.schema.json

@@ -0,0 +1,835 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "docs.schema.json",
+  "title": "Shiso docs.json",
+  "description": "Configuration for a Shiso docs site. Documented settings are strictly validated and unknown keys are rejected.",
+  "type": "object",
+  "anyOf": [{ "required": ["$ref"] }, { "required": ["navigation"] }],
+  "additionalProperties": false,
+  "properties": {
+    "$ref": {
+      "allOf": [{ "$ref": "#/definitions/configRef" }]
+    },
+    "$schema": {
+      "allOf": [{ "$ref": "#/definitions/stringValue" }],
+      "description": "Path or URL to this schema, for editor autocomplete."
+    },
+    "$shiso": {
+      "type": "object",
+      "description": "Shiso-only options. Namespaced so the rest of the file stays portable.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "docsPrefix": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Route prefix for docs pages. Defaults to \"/docs\"; use \"\" to serve docs at the site root.",
+          "default": "/docs"
+        },
+        "contentDir": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Content directory relative to the project root.",
+          "default": "content/docs"
+        },
+        "siteUrl": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Absolute site origin (e.g. \"https://docs.example.com\"). Required for canonical, og:url, and structured data."
+        },
+        "locale": {
+          "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+          "description": "Locale used for dates and theme-provided interface copy. Defaults to en-US."
+        }
+      }
+    },
+    "name": {
+      "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+      "description": "Site name, shown in the header and the page title."
+    },
+    "description": {
+      "allOf": [{ "$ref": "#/definitions/stringValue" }],
+      "description": "Default meta description for pages without one."
+    },
+    "colors": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "primary": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Primary accent color (any CSS color)."
+        },
+        "light": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Accent color used in dark mode."
+        },
+        "dark": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Fallback accent color when primary is omitted."
+        }
+      }
+    },
+    "logo": {
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Path to the logo image, relative to the public directory."
+        },
+        {
+          "type": "object",
+          "anyOf": [
+            { "required": ["$ref"] },
+            { "required": ["light"] },
+            { "required": ["dark"] }
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "$ref": { "$ref": "#/definitions/configRef" },
+            "light": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Logo shown in light mode." },
+            "dark": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Logo shown in dark mode." },
+            "href": {
+              "allOf": [{ "$ref": "#/definitions/stringValue" }],
+              "description": "URL the logo links to. Defaults to the docs root."
+            },
+            "target": {
+              "allOf": [{ "$ref": "#/definitions/targetValue" }],
+              "description": "Browsing context for the logo link. Defaults from href."
+            }
+          }
+        }
+      ]
+    },
+    "favicon": {
+      "allOf": [{ "$ref": "#/definitions/stringValue" }],
+      "description": "Path to the favicon, relative to the public directory."
+    },
+    "navigation": {
+      "type": "object",
+      "description": "Site navigation. Define exactly one of: tabs, dropdowns, versions, languages, or top-level groups/pages.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "tabs": { "$ref": "#/definitions/tabList" },
+        "dropdowns": { "$ref": "#/definitions/dropdownList" },
+        "anchors": { "$ref": "#/definitions/anchorList" },
+        "versions": { "$ref": "#/definitions/versionList" },
+        "languages": { "$ref": "#/definitions/languageList" },
+        "groups": { "$ref": "#/definitions/groupList" },
+        "pages": { "$ref": "#/definitions/pageItemList" }
+      }
+    },
+
+    "theme": {
+      "anyOf": [
+        { "type": "string", "enum": ["shiso"] },
+        { "$ref": "#/definitions/configRefValue" }
+      ],
+      "default": "shiso",
+      "description": "Layout theme name. Only \"shiso\" is implemented."
+    },
+    "styling": {
+      "type": "object",
+      "description": "Visual styling configuration.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "eyebrows": {
+          "anyOf": [
+            { "enum": ["section", "breadcrumbs"] },
+            { "$ref": "#/definitions/configRefValue" }
+          ],
+          "description": "Page eyebrow style: the section name (default) or the full navigation path.",
+          "default": "section"
+        }
+      }
+    },
+    "fonts": {
+      "type": "object",
+      "description": "Custom fonts. Google Fonts families load automatically; use source/format for self-hosted files.",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["family"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "family": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Font family name, e.g. \"Open Sans\"." },
+        "weight": { "allOf": [{ "$ref": "#/definitions/numberValue" }], "description": "Font weight, e.g. 400 or 700." },
+        "source": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "URL or path to a hosted font file." },
+        "format": {
+          "anyOf": [
+            { "enum": ["woff", "woff2"] },
+            { "$ref": "#/definitions/configRefValue" }
+          ],
+          "description": "Font file format, for `source`."
+        },
+        "heading": { "allOf": [{ "$ref": "#/definitions/fontSpec" }], "description": "Override for headings." },
+        "body": { "allOf": [{ "$ref": "#/definitions/fontSpec" }], "description": "Override for body text." }
+      }
+    },
+    "appearance": {
+      "type": "object",
+      "description": "Light/dark mode defaults.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "default": {
+          "anyOf": [
+            { "enum": ["system", "light", "dark"] },
+            { "$ref": "#/definitions/configRefValue" }
+          ],
+          "description": "Initial theme mode. \"system\" follows the OS preference.",
+          "default": "system"
+        },
+        "strict": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "Hide the light/dark toggle and ignore stored preferences.",
+          "default": false
+        }
+      }
+    },
+    "background": {
+      "type": "object",
+      "description": "Background color and image settings.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "image": {
+          "description": "Background image, a single path or per-mode paths.",
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "anyOf": [
+                { "required": ["$ref"] },
+                { "required": ["light"] },
+                { "required": ["dark"] }
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "$ref": { "$ref": "#/definitions/configRef" },
+                "light": { "$ref": "#/definitions/stringValue" },
+                "dark": { "$ref": "#/definitions/stringValue" }
+              }
+            }
+          ]
+        },
+        "color": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "$ref": { "$ref": "#/definitions/configRef" },
+            "light": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Background color for light mode." },
+            "dark": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Background color for dark mode." }
+          }
+        }
+      }
+    },
+    "interaction": {
+      "type": "object",
+      "description": "Navigation interaction settings.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "drilldown": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "Collapsible-group click behavior: true navigates to the group's first page on expand, false only expands/collapses. Unset uses the default (headers with a root page navigate, others toggle)."
+        }
+      }
+    },
+    "search": {
+      "description": "Search settings. Set to false to disable search.",
+      "oneOf": [
+        { "const": false },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "$ref": { "$ref": "#/definitions/configRef" },
+            "prompt": {
+              "allOf": [{ "$ref": "#/definitions/stringValue" }],
+              "description": "Placeholder text for the search input."
+            },
+            "provider": {
+              "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+              "description": "Registered search provider id. Defaults to local."
+            },
+            "options": {
+              "type": "object",
+              "description": "Provider-specific configuration."
+            },
+            "shortcut": {
+              "description": "Single Cmd/Ctrl shortcut key, or false to disable it.",
+              "oneOf": [
+                { "type": "string", "minLength": 1, "maxLength": 1 },
+                { "const": false },
+                { "$ref": "#/definitions/configRefValue" }
+              ]
+            },
+            "shortcutLabel": {
+              "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+              "description": "Text displayed for the configured search shortcut."
+            }
+          }
+        }
+      ]
+    },
+    "contextual": {
+      "type": "object",
+      "description": "Contextual menu shown beside the page title.",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["options"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "options": {
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "oneOf": [
+                  {
+                    "enum": [
+                      "copy",
+                      "view",
+                      "chatgpt",
+                      "claude",
+                      "perplexity"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "anyOf": [{ "required": ["$ref"] }, { "required": ["title", "href"] }],
+                    "additionalProperties": false,
+                    "properties": {
+                      "$ref": { "$ref": "#/definitions/configRef" },
+                      "title": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Menu entry title." },
+                      "description": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Menu entry description." },
+                      "icon": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Icon name rendered with the action." },
+                      "target": {
+                        "allOf": [{ "$ref": "#/definitions/targetValue" }],
+                        "description": "Browsing context for the action. Defaults from the destination URL."
+                      },
+                      "href": {
+                        "allOf": [{ "$ref": "#/definitions/stringValue" }],
+                        "description": "Destination URL. \"$path\" expands to the page path, \"$page\" to the page's markdown URL."
+                      }
+                    }
+                  }
+                ]
+              }
+            },
+            { "$ref": "#/definitions/configRefValue" }
+          ],
+          "description": "Menu entries, in order; the first is the primary button."
+        }
+      }
+    },
+    "navbar": {
+      "type": "object",
+      "description": "Links and primary button in the top navigation bar.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "links": {
+          "type": ["array", "object"],
+          "if": { "type": "object" },
+          "then": { "$ref": "#/definitions/configRefValue" },
+          "items": {
+            "type": "object",
+            "anyOf": [
+              { "required": ["$ref"] },
+              {
+                "required": ["href"],
+                "anyOf": [{ "required": ["label"] }, { "required": ["icon"] }]
+              }
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "$ref": { "$ref": "#/definitions/configRef" },
+              "label": {
+                "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+                "description": "Visible link text. Omit for an icon-only link."
+              },
+              "href": { "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }], "description": "Destination URL." },
+              "ariaLabel": {
+                "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+                "description": "Accessible text for an icon-only link."
+              },
+              "icon": {
+                "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+                "description": "Icon name. Rendered alone when label is omitted."
+              },
+              "target": {
+                "allOf": [{ "$ref": "#/definitions/targetValue" }],
+                "description": "Browsing context. Defaults to _self for local links and _blank for external links."
+              }
+            }
+          }
+        },
+        "primary": {
+          "type": "object",
+          "anyOf": [
+            { "required": ["$ref"] },
+            {
+              "required": ["href"],
+              "anyOf": [{ "required": ["label"] }, { "required": ["icon"] }]
+            }
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "$ref": { "$ref": "#/definitions/configRef" },
+            "label": { "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }], "description": "Visible button text. Omit for icon-only." },
+            "href": { "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }], "description": "Button destination URL." },
+            "icon": { "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }], "description": "Icon name." },
+            "ariaLabel": { "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }], "description": "Accessible text for icon-only buttons." },
+            "target": {
+              "allOf": [{ "$ref": "#/definitions/targetValue" }],
+              "description": "Browsing context. Defaults from the destination URL."
+            }
+          }
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Page metadata settings.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "timestamp": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "Show the last-modified date (from git history) on all pages. Override per page with the `timestamp` frontmatter field.",
+          "default": false
+        }
+      }
+    },
+    "footer": {
+      "type": "object",
+      "description": "Footer content: social links and link columns.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "socials": {
+          "type": ["array", "object"],
+          "if": { "type": "object" },
+          "then": { "$ref": "#/definitions/configRefValue" },
+          "description": "Social links displayed in the footer.",
+          "items": {
+            "type": "object",
+            "anyOf": [
+              { "required": ["$ref"] },
+              {
+                "required": ["href"],
+                "anyOf": [{ "required": ["label"] }, { "required": ["icon"] }]
+              }
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "$ref": { "$ref": "#/definitions/configRef" },
+              "href": { "$ref": "#/definitions/stringValue" },
+              "label": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Visible link text." },
+              "icon": { "$ref": "#/definitions/stringValue" },
+              "ariaLabel": { "$ref": "#/definitions/stringValue" },
+              "target": { "$ref": "#/definitions/targetValue" }
+            }
+          }
+        },
+        "links": {
+          "type": ["array", "object"],
+          "if": { "type": "object" },
+          "then": { "$ref": "#/definitions/configRefValue" },
+          "description": "Link columns displayed above the footer bottom row.",
+          "items": {
+            "type": "object",
+            "anyOf": [{ "required": ["$ref"] }, { "required": ["items"] }],
+            "additionalProperties": false,
+            "properties": {
+              "$ref": { "$ref": "#/definitions/configRef" },
+              "header": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Column heading." },
+              "items": {
+                "type": ["array", "object"],
+                "if": { "type": "object" },
+                "then": { "$ref": "#/definitions/configRefValue" },
+                "items": {
+                  "type": "object",
+                  "anyOf": [{ "required": ["$ref"] }, { "required": ["label", "href"] }],
+                  "additionalProperties": false,
+                  "properties": {
+                    "$ref": { "$ref": "#/definitions/configRef" },
+                    "label": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Link text." },
+                    "href": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Link destination URL." },
+                    "target": { "$ref": "#/definitions/targetValue" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "attribution": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "Show the Shiso attribution in the footer. Defaults to true.",
+          "default": true
+        }
+      }
+    },
+    "banner": {
+      "type": "object",
+      "description": "Site-wide banner displayed above the header.",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["content"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "content": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Banner text. Supports basic markdown: links, bold, italic, and inline code."
+        },
+        "dismissible": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "Show a dismiss button. Dismissal persists until the content changes.",
+          "default": false
+        }
+      }
+    },
+    "redirects": {
+      "type": ["array", "object"],
+      "if": { "type": "object" },
+      "then": { "$ref": "#/definitions/configRefValue" },
+      "description": "Redirects for moved, renamed, or deleted pages. Sources are matched exactly.",
+      "items": {
+        "type": "object",
+        "anyOf": [{ "required": ["$ref"] }, { "required": ["source", "destination"] }],
+        "additionalProperties": false,
+        "properties": {
+          "$ref": { "$ref": "#/definitions/configRef" },
+          "source": { "allOf": [{ "$ref": "#/definitions/redirectSourceValue" }], "description": "Exact path to redirect from, e.g. \"/docs/old-page\"." },
+          "destination": {
+            "allOf": [{ "$ref": "#/definitions/stringValue" }],
+            "description": "Path or URL to redirect to, e.g. \"/new-page\"."
+          }
+        }
+      }
+    },
+    "seo": {
+      "type": "object",
+      "description": "SEO indexing configuration.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "metatags": {
+          "type": "object",
+          "description": "Meta tags added to every page, e.g. { \"og:image\": \"/social.png\" }.",
+          "additionalProperties": { "$ref": "#/definitions/stringValue" }
+        },
+        "indexing": {
+          "anyOf": [
+            { "enum": ["navigable", "all"] },
+            { "$ref": "#/definitions/configRefValue" }
+          ],
+          "description": "\"navigable\" (default) marks hidden pages noindex and keeps them out of the sitemap; \"all\" indexes every page.",
+          "default": "navigable"
+        }
+      }
+    },
+    "errors": {
+      "type": "object",
+      "description": "Error handling settings.",
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "404": {
+          "type": "object",
+          "description": "\"Page not found\" behavior.",
+          "additionalProperties": false,
+          "properties": {
+            "$ref": { "$ref": "#/definitions/configRef" },
+            "redirect": {
+              "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+              "description": "Navigate to the docs home when a page is not found. Defaults to true.",
+              "default": true
+            },
+            "title": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Custom title for the 404 page." },
+            "description": {
+              "allOf": [{ "$ref": "#/definitions/stringValue" }],
+              "description": "Custom description. Supports basic markdown: links, bold, italic, and inline code."
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "configRef": {
+      "type": "string",
+      "pattern": "^(?![A-Za-z][A-Za-z0-9+.-]*:)(?![/\\\\]).+\\.json$",
+      "description": "Relative path to another JSON configuration file. Resolved relative to the file containing this reference."
+    },
+    "configRefValue": {
+      "type": "object",
+      "description": "Reference to a JSON file used in place of this configuration value.",
+      "required": ["$ref"],
+      "additionalProperties": true,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" }
+      }
+    },
+    "stringValue": {
+      "anyOf": [
+        { "type": "string" },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "nonEmptyStringValue": {
+      "anyOf": [
+        { "type": "string", "minLength": 1 },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "booleanValue": {
+      "anyOf": [
+        { "type": "boolean" },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "numberValue": {
+      "anyOf": [
+        { "type": "number" },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "targetValue": {
+      "anyOf": [
+        { "enum": ["_self", "_blank"] },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "redirectSourceValue": {
+      "anyOf": [
+        { "type": "string", "pattern": "^/[^*]*$" },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "pageItemList": {
+      "anyOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/pageItem" } },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "groupList": {
+      "anyOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/group" } },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "dropdownList": {
+      "anyOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/dropdown" } },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "tabList": {
+      "anyOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/tab" } },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "anchorList": {
+      "anyOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/anchor" } },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "versionList": {
+      "anyOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/version" } },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "languageList": {
+      "anyOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/language" } },
+        { "$ref": "#/definitions/configRefValue" }
+      ]
+    },
+    "fontSpec": {
+      "type": "object",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["family"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "family": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Font family name, e.g. \"Open Sans\"." },
+        "weight": { "allOf": [{ "$ref": "#/definitions/numberValue" }], "description": "Font weight, e.g. 400 or 700." },
+        "source": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "URL or path to a hosted font file." },
+        "format": {
+          "anyOf": [
+            { "enum": ["woff", "woff2"] },
+            { "$ref": "#/definitions/configRefValue" }
+          ],
+          "description": "Font file format, for `source`."
+        }
+      }
+    },
+    "pageItem": {
+      "anyOf": [
+        {
+          "type": "string",
+          "description": "Page reference relative to the content directory, without extension (e.g. \"components/tabs\")."
+        },
+        { "$ref": "#/definitions/pageObject" },
+        { "$ref": "#/definitions/linkItem" },
+        { "$ref": "#/definitions/group" }
+      ]
+    },
+    "pageObject": {
+      "type": "object",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["page"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "page": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Page reference relative to the content directory, without extension."
+        },
+        "title": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Custom sidebar label. Overrides the label derived from the file name."
+        },
+        "label": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Custom sidebar label. Takes precedence over title."
+        },
+        "icon": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Icon name shown beside the label." },
+        "tag": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Short label shown after the page name." },
+        "hidden": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "Hide from the sidebar and search. The page is still built and reachable by URL."
+        }
+      }
+    },
+    "linkItem": {
+      "type": "object",
+      "description": "An external link in the navigation tree.",
+      "anyOf": [
+        { "required": ["$ref"] },
+        {
+          "required": ["href"],
+          "anyOf": [{ "required": ["label"] }, { "required": ["anchor"] }]
+        }
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "href": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Destination URL." },
+        "label": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Link text." },
+        "anchor": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Alias for label." },
+        "icon": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Icon name shown beside the label." },
+        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide from the sidebar." },
+        "target": { "$ref": "#/definitions/targetValue" }
+      }
+    },
+    "anchor": {
+      "type": "object",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["anchor"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "anchor": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Anchor label." },
+        "href": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Destination URL." },
+        "icon": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Icon name shown beside the label." },
+        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide the anchor." },
+        "target": { "$ref": "#/definitions/targetValue" }
+      }
+    },
+    "group": {
+      "type": "object",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["group", "pages"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "group": { "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }], "description": "Group heading shown in the sidebar." },
+        "root": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Optional landing page for the group. When set, the group title links to this page (chevron still expands/collapses)."
+        },
+        "pages": { "$ref": "#/definitions/pageItemList" },
+        "icon": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Icon name shown beside the heading." },
+        "expanded": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "When true, nested groups start expanded. Top-level groups start expanded by default. Groups that contain the current page always expand."
+        },
+        "collapsible": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "When false, the group stays expanded and its heading does not show a collapse control."
+        },
+        "hidden": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "Hide the group and its pages from the sidebar."
+        }
+      }
+    },
+    "dropdown": {
+      "type": "object",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["dropdown"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "dropdown": {
+          "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+          "description": "Dropdown label rendered by the selected theme."
+        },
+        "groups": { "$ref": "#/definitions/groupList" },
+        "pages": { "$ref": "#/definitions/pageItemList" },
+        "icon": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Icon name shown beside the label." },
+        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide the dropdown." }
+      }
+    },
+    "tab": {
+      "type": "object",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["tab"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "tab": { "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }], "description": "Tab label shown in the top navigation." },
+        "groups": { "$ref": "#/definitions/groupList" },
+        "pages": { "$ref": "#/definitions/pageItemList" },
+        "dropdowns": { "$ref": "#/definitions/dropdownList" },
+        "icon": { "allOf": [{ "$ref": "#/definitions/stringValue" }], "description": "Icon name shown beside the tab label." },
+        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide the tab from the top navigation." }
+      }
+    },
+    "version": {
+      "type": "object",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["version"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "version": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Version label. Only the default (or first) version is rendered."
+        },
+        "default": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Marks this version as the one to render." },
+        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide this version." },
+        "tabs": { "$ref": "#/definitions/tabList" },
+        "dropdowns": { "$ref": "#/definitions/dropdownList" },
+        "groups": { "$ref": "#/definitions/groupList" },
+        "pages": { "$ref": "#/definitions/pageItemList" }
+      }
+    },
+    "language": {
+      "type": "object",
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["language"] }],
+      "additionalProperties": false,
+      "properties": {
+        "$ref": { "$ref": "#/definitions/configRef" },
+        "language": {
+          "allOf": [{ "$ref": "#/definitions/stringValue" }],
+          "description": "Language code or label. Only the default (or first) language is rendered."
+        },
+        "default": {
+          "allOf": [{ "$ref": "#/definitions/booleanValue" }],
+          "description": "Marks this language as the one to render."
+        },
+        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide this language." },
+        "versions": { "$ref": "#/definitions/versionList" },
+        "tabs": { "$ref": "#/definitions/tabList" },
+        "dropdowns": { "$ref": "#/definitions/dropdownList" },
+        "groups": { "$ref": "#/definitions/groupList" },
+        "pages": { "$ref": "#/definitions/pageItemList" }
+      }
+    }
+  }
+}