{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://diplodoc.com/schemas/frontmatter/draft-01/schema#",
  "title": "Diplodoc (frontmatter)",
  "description": "YAML frontmatter block at the top of .md files (between --- delimiters). Defines page metadata, SEO fields, resources, and access rules.",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Page title for HTML head and SEO.",
      "markdownDescription": "**`string`** Page title used in the browser tab, navigation sidebar, and SEO `<title>` tag.\n\nOverrides the first `#` heading for display purposes."
    },
    "description": {
      "type": "string",
      "description": "Meta description for SEO.",
      "markdownDescription": "**`string`** Meta description for SEO (`<meta name=\"description\">`). Shown in search engine snippets."
    },
    "keywords": {
      "$ref": "#/definitions/Keywords"
    },
    "noIndex": {
      "type": "boolean",
      "description": "Adds noindex/nofollow meta tag to prevent search engine indexing.",
      "markdownDescription": "**`boolean`** Adds `<meta name=\"robots\" content=\"noindex, nofollow\">` to prevent search engine indexing of this page."
    },
    "canonical": {
      "type": "string",
      "format": "uri",
      "description": "Canonical URL for the page.",
      "markdownDescription": "**`string (uri)`** Canonical URL for this page (`<link rel=\"canonical\">`).\n\nUse when the same content is accessible at multiple URLs."
    },
    "copyright": {
      "type": "string",
      "description": "Copyright owner string.",
      "markdownDescription": "**`string`** Copyright owner string added to the page footer."
    },
    "alternate": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Alternate"
      },
      "description": "Alternate language versions of this page.",
      "markdownDescription": "**`Alternate[]`** Alternate language versions of this page (`<link rel=\"alternate\" hreflang=\"...\">`). Each item must have `href` and optionally `hreflang`.",
      "defaultSnippets": [
        {
          "label": "Add alternate language version",
          "body": [
            {
              "href": "${1:https://example.com/en/page}",
              "hreflang": "${2:en}"
            }
          ]
        }
      ]
    },
    "metadata": {
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/definitions/MetaItem"
          },
          "markdownDescription": "**`MetaItem[]`**"
        },
        {
          "type": "object"
        }
      ],
      "description": "Custom meta tags. Array of {name/property, content} objects or a key-value hash.",
      "markdownDescription": "**`MetaItem[] | object`** Custom HTML `<meta>` tags.\n\n**Array form** — explicit tag definitions: ```yaml metadata:\n  - name: author\n    content: John Doe\n  - property: og:image\n    content: https://example.com/image.png\n``` **Object form** — shorthand key→value: ```yaml metadata:\n  author: John Doe\n```"
    },
    "interface": {
      "type": "object",
      "properties": {
        "toc": {
          "type": "boolean",
          "description": "Show/hide the table of contents sidebar.",
          "markdownDescription": "**`boolean`** Show (`true`) or hide (`false`) the table-of-contents sidebar on this page."
        },
        "toc-header": {
          "type": "boolean",
          "description": "Show/hide the TOC header section.",
          "markdownDescription": "**`boolean`** Show or hide the section above the TOC (project name / logo)."
        },
        "search": {
          "type": "boolean",
          "description": "Show/hide the search input.",
          "markdownDescription": "**`boolean`** Show or hide the search input on this page."
        },
        "feedback": {
          "type": "boolean",
          "description": "Show/hide feedback controls.",
          "markdownDescription": "**`boolean`** Show or hide the like / dislike feedback controls."
        },
        "gallery": {
          "type": "boolean",
          "description": "Enable/disable opening images in the gallery on this page.",
          "markdownDescription": "**`boolean`** Enable (`true`, default) or disable (`false`) opening images in the gallery viewer on this page."
        },
        "favicon-src": {
          "type": "string",
          "description": "Custom favicon URL for this page.",
          "markdownDescription": "**`string`** URL to a custom favicon shown in the browser tab for this page only."
        }
      },
      "additionalProperties": false,
      "description": "Per-page UI overrides (takes precedence over .yfm config).",
      "markdownDescription": "**`{toc, toc-header, search, feedback, gallery, favicon-src}`** Per-page UI element visibility overrides. Takes precedence over the global `.yfm` config.",
      "defaultSnippets": [
        {
          "label": "Configure page UI",
          "body": {
            "toc": "${1:true}",
            "search": "${2:true}",
            "feedback": "${3:true}"
          }
        }
      ]
    },
    "resources": {
      "$ref": "#/definitions/Resources",
      "description": "Per-page resources (legacy, prefer top-level script/style/csp).",
      "markdownDescription": "**`Resources`** Legacy per-page resource injection. Prefer top-level `script`, `style`, `csp`."
    },
    "script": {
      "type": "array",
      "items": {
        "type": "string",
        "markdownDescription": "**`string`**"
      },
      "description": "Script file paths or URLs to include on this page.",
      "markdownDescription": "**`string[]`** JavaScript files to inject into this page only.\n\n```yaml\nscript:\n  - _assets/custom.js\n```"
    },
    "style": {
      "type": "array",
      "items": {
        "type": "string",
        "markdownDescription": "**`string`**"
      },
      "description": "Stylesheet file paths or URLs to include on this page.",
      "markdownDescription": "**`string[]`** CSS files to inject into this page only.\n\n```yaml\nstyle:\n  - _assets/custom.css\n```"
    },
    "csp": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Content Security Policy directive overrides for this page.",
      "markdownDescription": "**`object[]`** Content Security Policy directive overrides for this page.\n\nEach item is an object mapping a directive name to an array of allowed sources."
    },
    "vcsPath": {
      "type": "string",
      "description": "VCS file path override (duplicated keys allowed for this field).",
      "markdownDescription": "**`string`** Override the VCS path shown in the page header \"Edit on GitHub\" link."
    },
    "sourcePath": {
      "type": "string",
      "description": "Source file path (usually set by the build system).",
      "markdownDescription": "**`string`** Source file path — usually set automatically by the build pipeline. Do not set manually."
    },
    "restricted-access": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "string",
          "markdownDescription": "**`string`**"
        },
        "markdownDescription": "**`string[]`**"
      },
      "description": "Access restriction rules. Each item is an array of conditions that must all be satisfied.",
      "markdownDescription": "**`string[][]`** Access restriction rules.\nEach inner array is a list of conditions joined by AND; outer items are joined by OR. The user must match at least one inner array fully to access the page.\n```yaml restricted-access:\n  - [role:admin]\n  - [role:editor, group:docs-team]\n```"
    },
    "stage": {
      "type": "string",
      "enum": ["new", "preview", "tech-preview", "skip"],
      "description": "Document lifecycle stage (inherited from toc.yaml or set manually).",
      "markdownDescription": "**`'new' | 'preview' | 'tech-preview' | 'skip'`** Document lifecycle stage.\n\nInherited from the parent `toc.yaml` entry; override here for this page only.",
      "markdownEnumDescriptions": [
        "New document. Visible only in **preview** and **tech-preview** builds. Excluded from production.",
        "Preview stage. Visible in preview and tech-preview builds. Excluded from production unless explicitly enabled.",
        "Tech-preview stage. Visible only in tech-preview builds.",
        "Excluded from all builds — the page is skipped entirely."
      ]
    },
    "queryParameters": {
      "type": "object",
      "properties": {
        "iframes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "domain": {
                "type": "string",
                "markdownDescription": "**`string`**"
              },
              "parameters": {
                "type": "array",
                "markdownDescription": "**`array`**"
              }
            },
            "additionalProperties": false,
            "markdownDescription": "**`{domain, parameters}`**"
          },
          "markdownDescription": "**`object[]`** Per-domain forwarding rules.\n\nEach item:\n- `domain` **`string`** — iframe host domain to match\n- `parameters` **`array`** — query parameter names to forward",
          "description": "Per-domain iframe query parameter forwarding rules."
        }
      },
      "additionalProperties": false,
      "description": "Per-page query parameter forwarding rules for embedded iframes.",
      "markdownDescription": "**`{iframes}`** Per-page query parameter forwarding rules for `<iframe>` embeds.\n\n- `iframes` **`object[]`** — per-domain forwarding rules (each item: `domain: string`, `parameters: array`)"
    },
    "docs-viewer": {
      "type": "object",
      "properties": {
        "noIndex": {
          "type": "boolean",
          "description": "Disallow indexing by external search engines (viewer-level override).",
          "markdownDescription": "**`boolean`** Disallow indexing by external search engines (viewer-level override)."
        }
      },
      "additionalProperties": true,
      "description": "Per-page docs-viewer overrides.",
      "markdownDescription": "**`{noIndex}`** Per-page docs-viewer overrides.\n\n- `noIndex` **`boolean`** — disallow external search engine indexing"
    },
    "yabug": {
      "type": "object",
      "properties": {
        "disabled": {
          "type": "boolean",
          "markdownDescription": "**`boolean`** Disable the bug-report widget on this page."
        },
        "form": {
          "type": "string",
          "markdownDescription": "**`string`** Custom bug report form ID or URL."
        }
      },
      "additionalProperties": false,
      "description": "Per-page bug report widget overrides.",
      "markdownDescription": "**`{disabled, form}`** Per-page bug-report widget overrides.\n\n- `disabled` **`boolean`** — disable the widget on this page\n- `form` **`string`** — custom form ID"
    },
    "yafeedback": {
      "type": "object",
      "properties": {
        "ownerId": {
          "oneOf": [
            {
              "type": "string",
              "markdownDescription": "**`string`**"
            },
            {
              "type": "object",
              "additionalProperties": {
                "type": "string",
                "markdownDescription": "**`string`**"
              }
            }
          ],
          "markdownDescription": "**`string | object`** Feedback widget owner ID. String for a single ID; object maps language codes to IDs."
        },
        "hideHeader": {
          "type": "boolean",
          "markdownDescription": "**`boolean`** Hide the feedback widget header section."
        },
        "disabled": {
          "type": "boolean",
          "markdownDescription": "**`boolean`** Disable the Yandex Feedback widget on this page."
        },
        "testIds": {
          "type": "object",
          "additionalProperties": true,
          "markdownDescription": "**`object`** A/B test form IDs for the feedback widget."
        }
      },
      "additionalProperties": false,
      "description": "Per-page Yandex Feedback (Pythia) widget overrides.",
      "markdownDescription": "**`{ownerId, hideHeader, disabled, testIds}`** Per-page Yandex Feedback widget overrides.\n\n- `ownerId` **`string | object`** — owner ID or per-language map\n- `hideHeader` **`boolean`** — hide widget header\n- `disabled` **`boolean`** — disable widget\n- `testIds` **`{ownerId, hideHeader, disabled, testIds}`** — A/B test IDs"
    },
    "neuroExpert": {
      "type": "object",
      "properties": {
        "projectId": {
          "type": "object",
          "description": "Map of language codes to project IDs.",
          "markdownDescription": "**`object`** Map of language codes to AI expert project IDs (e.g. `{en: 'proj-123'}`)."
        },
        "hasOutsideClick": {
          "type": "boolean",
          "markdownDescription": "**`boolean`** Close the AI expert widget when the user clicks outside it."
        },
        "parentId": {
          "oneOf": [
            {
              "type": "string",
              "markdownDescription": "**`string`**"
            },
            {
              "type": "null",
              "markdownDescription": "**`null`**"
            }
          ],
          "markdownDescription": "**`string | null`** Parent element ID for widget placement. `null` uses the default."
        },
        "disabled": {
          "type": "boolean",
          "markdownDescription": "**`boolean`** Disable the AI expert widget on this page."
        },
        "customLabel": {
          "type": "object",
          "description": "Map of language codes to custom widget header labels. Use \"default\" key for fallback. Only for whitelisted projects.",
          "additionalProperties": {
            "oneOf": [
              {
                "type": "string",
                "markdownDescription": "**`string`**"
              },
              {
                "type": "boolean",
                "markdownDescription": "**`boolean`**"
              }
            ]
          },
          "markdownDescription": "**`object`** Map of language codes to custom widget header labels. Use `default` as fallback key."
        }
      },
      "additionalProperties": false,
      "description": "Per-page AI expert widget overrides.",
      "markdownDescription": "**`{projectId, hasOutsideClick, parentId, ...}`** Per-page AI expert widget overrides.\n\n- `projectId` **`{projectId, hasOutsideClick, parentId, ...}`** — language → project ID map\n- `hasOutsideClick` **`boolean`** — close on outside click\n- `parentId` **`string | null`** — parent element ID\n- `disabled` **`boolean`** — disable widget\n- `customLabel` **`{projectId, hasOutsideClick, parentId, ...}`** — language → label map"
    },
    "editable": {
      "type": "boolean",
      "description": "Whether the document is editable (system-generated by doc-transform).",
      "markdownDescription": "**`boolean`** *(system-generated)* Whether the document has a VCS edit link. Set automatically by `doc-transform`.",
      "doNotSuggest": true
    },
    "theme": {
      "type": "string",
      "description": "Path to generated theme CSS (system-generated in md2md output).",
      "markdownDescription": "**`string`** *(system-generated)* Path to the generated theme CSS file. Set automatically in `md` output format.",
      "doNotSuggest": true
    },
    "author": {
      "$ref": "#/definitions/Contributor",
      "description": "Page author from VCS (system-generated).",
      "markdownDescription": "**`Contributor`** *(system-generated)* Page author resolved from VCS history.",
      "doNotSuggest": true
    },
    "contributors": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Contributor"
      },
      "description": "Page contributors from VCS (system-generated).",
      "markdownDescription": "**`Contributor[]`** *(system-generated)* List of page contributors resolved from VCS history.",
      "doNotSuggest": true
    },
    "updatedAt": {
      "type": "string",
      "description": "Last modification timestamp from VCS (system-generated).",
      "markdownDescription": "**`string`** *(system-generated)* ISO 8601 timestamp of the last VCS commit touching this file.",
      "doNotSuggest": true
    },
    "__system": {
      "type": "object",
      "description": "System variables from presets (only when addSystemMeta is enabled).",
      "markdownDescription": "**`object`** *(system-generated)* Preset variables injected when `addSystemMeta: true` is set in `.yfm`.",
      "doNotSuggest": true
    },
    "__metadata": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/MetaItem"
      },
      "description": "Metadata items from presets (only when addMetadataMeta is enabled).",
      "markdownDescription": "**`MetaItem[]`** *(system-generated)* Metadata items from presets injected when `addMetadataMeta: true` is set.",
      "doNotSuggest": true
    }
  },
  "additionalProperties": false,
  "definitions": {
    "Alternate": {
      "type": "object",
      "properties": {
        "href": {
          "type": "string",
          "format": "uri",
          "markdownDescription": "**`string (uri)`** Absolute URL of the alternate page."
        },
        "hreflang": {
          "type": "string",
          "markdownDescription": "**`string`** BCP-47 language code (e.g. `en`, `ru`, `zh-Hans`)."
        }
      },
      "required": ["href"],
      "additionalProperties": false,
      "markdownDescription": "**`Alternate`** Alternate language version of this page for `<link rel=\"alternate\">`.",
      "description": "Alternate language version of this page."
    },
    "Keywords": {
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "string",
            "markdownDescription": "**`string`**"
          },
          {
            "type": "object",
            "properties": {
              "keyword": {
                "type": "string"
              }
            },
            "required": ["keyword"],
            "additionalProperties": false
          }
        ]
      },
      "description": "Keywords for the meta keywords tag.",
      "markdownDescription": "**`string[] | {keyword: string}[]`** Keywords for the `<meta name=\"keywords\">` tag.\n\n```yaml\nkeywords:\n  - cloud\n  - storage\n  - s3\n```"
    },
    "MetaItem": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Meta tag name attribute (e.g. \"title\", \"copyright\").",
          "markdownDescription": "**`string`** `name` attribute of the meta tag (e.g. `author`, `copyright`, `robots`)."
        },
        "property": {
          "type": "string",
          "description": "Meta tag property attribute (e.g. \"og:title\", \"article:section\").",
          "markdownDescription": "**`string`** `property` attribute — used for Open Graph tags (e.g. `og:title`, `og:image`)."
        },
        "http-equiv": {
          "type": "string",
          "description": "Meta tag http-equiv attribute (e.g. \"content-type\", \"refresh\").",
          "markdownDescription": "**`string`** `http-equiv` attribute (e.g. `content-type`, `refresh`, `X-UA-Compatible`)."
        },
        "content": {
          "type": "string",
          "description": "Meta tag content value.",
          "markdownDescription": "**`string`** Content value of the meta tag. **Required.**"
        }
      },
      "required": ["content"],
      "additionalProperties": false,
      "markdownDescription": "**`MetaItem`** One custom HTML `<meta>` tag. Must have exactly one of `name`, `property`, or `http-equiv`, plus `content`.",
      "description": "Custom HTML meta tag definition."
    },
    "Contributor": {
      "type": "object",
      "properties": {
        "avatar": {
          "type": "string",
          "markdownDescription": "**`string`** Avatar image URL."
        },
        "email": {
          "type": "string",
          "format": "email",
          "markdownDescription": "**`string (email)`** Contributor email address."
        },
        "login": {
          "type": "string",
          "markdownDescription": "**`string`** VCS login / username."
        },
        "name": {
          "type": "string",
          "markdownDescription": "**`string`** Display name."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "markdownDescription": "**`string (uri)`** Profile URL (e.g. GitHub profile)."
        }
      },
      "additionalProperties": false,
      "markdownDescription": "**`Contributor`** VCS contributor record — populated automatically from Git history.",
      "description": "VCS contributor information (system-generated)."
    },
    "Resources": {
      "type": "object",
      "properties": {
        "script": {
          "type": "array",
          "items": {
            "type": "string",
            "markdownDescription": "**`string`**"
          },
          "markdownDescription": "**`string[]`** JavaScript file paths or URLs."
        },
        "style": {
          "type": "array",
          "items": {
            "type": "string",
            "markdownDescription": "**`string`**"
          },
          "markdownDescription": "**`string[]`** CSS file paths or URLs."
        },
        "csp": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "markdownDescription": "**`object[]`** Content Security Policy directives."
        }
      },
      "additionalProperties": false,
      "markdownDescription": "**`Resources`** *(legacy)* Per-page CSS/JS/CSP resources. Prefer top-level `script`, `style`, `csp` fields.",
      "description": "Legacy per-page resources definition."
    }
  },
  "markdownDescription": "YAML frontmatter block at the very top of a `.md` file (between `---` delimiters).\nDefines page metadata, SEO fields, per-page UI overrides, and access rules.\n```yaml --- title: My page description: Short description for SEO --- ```"
}