{ "title": "Diplodoc (.yfm)", "type": "object", "properties": { "input": { "type": "string", "description": "Path to input directory with documentation sources.", "markdownDescription": "**`string`** Path to the directory containing documentation sources (`.md` files, `toc.yaml`, `presets.yaml`, etc.)." }, "output": { "type": "string", "description": "Path to output directory for build artifacts.", "markdownDescription": "**`string`** Path to the directory where build artifacts are written." }, "quiet": { "type": "boolean", "description": "Suppress stdout logs.", "markdownDescription": "**`boolean`** Suppress all stdout log output during the build." }, "strict": { "type": "boolean", "description": "Exit with non-zero code on errors or warnings.", "markdownDescription": "**`boolean`** Exit with a non-zero code if any errors **or warnings** are emitted during the build." }, "jobs": { "type": "integer", "minimum": 0, "description": "Number of parallel worker threads. 0 means single-threaded, omitted value uses cpus-1.", "markdownDescription": "**`integer (≥0)`** Number of parallel worker threads.\n\n- `0` — single-threaded (no workers)\n- omitted — uses `CPU count − 1`" }, "workerMaxOldSpace": { "type": "integer", "minimum": 0, "description": "Max old space size for worker threads in megabytes.", "markdownDescription": "**`integer`** Maximum V8 old-space heap size (in **megabytes**) for each worker thread." }, "config": { "type": "string", "description": "Path to an alternative config file.", "markdownDescription": "**`string`** Path to an alternative config file. Useful for environment-specific overrides." }, "copyOnWrite": { "type": "boolean", "description": "Use COPYFILE_FICLONE flag for file copying.", "markdownDescription": "**`boolean`** Use `COPYFILE_FICLONE` (copy-on-write / reflinks) when copying files. Faster on supported filesystems (APFS, Btrfs)." }, "originAsInput": { "type": "boolean", "description": "Allow modifying the input directory in-place.", "markdownDescription": "**`boolean`** Allow the build to modify the `input` directory in-place (used in `md` output mode)." }, "lang": { "type": "string", "description": "Default language code.", "markdownDescription": "**`string`** Default language code for the documentation (ISO 639-1, e.g. `en`, `ru`)." }, "langs": { "type": "array", "items": { "$ref": "#/definitions/LangItem" }, "description": "Languages supported by the documentation project. Each item is a language code string or an extended object.", "markdownDescription": "**`LangItem[]`** All languages supported by the project. Used to generate language-switcher links.\n\nEach item is a language code string or an extended object:\n```yaml\nlangs:\n - en\n - ru\n - lang: zh\n tld: .cn\n```" }, "outputFormat": { "type": "string", "enum": ["html", "md"], "description": "Output format. html — render to static HTML. md — render to enriched Markdown with metadata.", "markdownDescription": "**`'html' | 'md'`** Output format for the build.", "markdownEnumDescriptions": [ "**html** — render to a fully static HTML site (default).", "**md** — render to enriched Markdown with injected metadata (for further processing or translation)." ] }, "varsPreset": { "type": "string", "description": "Name of the variables preset from presets.yaml. Merged with the \"default\" section.", "markdownDescription": "**`string`** Name of a preset from `presets.yaml` to activate.\n\nThe named preset is deep-merged with the `default` preset." }, "vars": { "type": "object", "description": "Template variables passed directly to the build. Overrides matching keys from presets.yaml.", "markdownDescription": "**`object`** Template variables passed directly to the build. Overrides matching keys from `presets.yaml`.\n\n```yaml\nvars:\n version: '2.0'\n env: production\n```" }, "allowHTML": { "type": "boolean", "description": "Allow raw HTML inside Markdown files (legacy alias for allowHtml).", "markdownDescription": "**`boolean`** *(legacy alias)* Allow raw HTML inside Markdown files. Prefer `allowHtml`.", "deprecationMessage": "Deprecated: use allowHtml instead." }, "allowHtml": { "type": "boolean", "description": "Allow raw HTML inside Markdown files.", "markdownDescription": "**`boolean`** Allow raw HTML tags inside Markdown files. When `false` (default), HTML tags are escaped." }, "sanitizeHtml": { "type": "boolean", "description": "Sanitize transformed HTML output. Slow but more secure.", "markdownDescription": "**`boolean`** Run the generated HTML through an HTML sanitizer. Slower but removes potentially dangerous markup." }, "sanitizeOptions": { "type": "object", "description": "Sanitizer configuration options (passed to the HTML sanitizer).", "additionalProperties": true, "markdownDescription": "**`object`** Options passed to the HTML sanitizer (when `sanitizeHtml: true`). See the sanitizer's documentation for available keys." }, "linkifyTlds": { "oneOf": [ { "type": "string", "markdownDescription": "**`string`**" }, { "type": "array", "items": { "type": "string", "markdownDescription": "**`string`**" }, "markdownDescription": "**`string[]`**" } ], "description": "TLD configuration for the linkify plugin.", "markdownDescription": "**`string | string[]`** Additional TLDs recognized by the linkify plugin as auto-link candidates.\n\nExample: `['.internal', '.corp']`" }, "ignore": { "type": "array", "items": { "type": "string", "markdownDescription": "**`string`**" }, "description": "Glob patterns for paths to exclude from processing.", "markdownDescription": "**`string[]`** Glob patterns for files/directories to exclude from processing.\n\n```yaml\nignore:\n - '**/draft/**'\n - '**/*.tmp.md'\n```" }, "ignoreStage": { "type": "array", "items": { "type": "string", "enum": ["new", "preview", "tech-preview", "skip"], "markdownDescription": "**`'new' | 'preview' | 'tech-preview' | 'skip'`**", "markdownEnumDescriptions": [ "Exclude pages tagged `new`.", "Exclude pages tagged `preview`.", "Exclude pages tagged `tech-preview`.", "Exclude pages tagged `skip` (already excluded by default)." ] }, "description": "TOC stages to exclude from the build.", "markdownDescription": "**`string[]`** TOC `stage` values to exclude from the build.\n\nExample: `['new', 'preview']` — only ship stable pages." }, "staticContent": { "type": "boolean", "description": "Allow loading custom resources into statically generated pages.", "markdownDescription": "**`boolean`** Allow custom resources (`script`, `style`) to be injected in static output mode." }, "addSystemMeta": { "type": "boolean", "description": "Include system variables from presets in file metadata.", "markdownDescription": "**`boolean`** Inject preset variables into each page's `__system` metadata field." }, "addMapFile": { "type": "boolean", "description": "Write all documentation paths to file.json.", "deprecated": "Use buildManifest instead.", "markdownDescription": "**`boolean`** *(deprecated)* Write all documentation paths to `file.json`.", "deprecationMessage": "Deprecated: use buildManifest instead.", "doNotSuggest": true }, "addAlternateMeta": { "type": "boolean", "description": "Add alternate and canonical meta tags to pages.", "markdownDescription": "**`boolean`** Emit `` and `` meta tags." }, "supportGithubAnchors": { "type": "boolean", "description": "Use GitHub-compatible heading anchor format.", "markdownDescription": "**`boolean`** Generate GitHub-compatible heading anchors (lowercase, hyphens) in addition to standard anchors." }, "breaks": { "type": "boolean", "description": "Treat single newlines in Markdown as hard line breaks.", "markdownDescription": "**`boolean`** Treat single newlines in Markdown as `
` hard line breaks (CommonMark 'breaks' option)." }, "linkify": { "type": "boolean", "description": "Automatically convert URL-like text to links.", "markdownDescription": "**`boolean`** Automatically convert plain URL-like text into clickable `` links." }, "vcs": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "markdownDescription": "**`boolean`**" }, "endpoint": { "type": "string", "description": "VCS provider API endpoint (from github-vcs / arcadia-vcs).", "markdownDescription": "**`string`** VCS provider API endpoint (from github-vcs / arcadia-vcs)." }, "owner": { "type": "string", "description": "Repository owner (from github-vcs).", "markdownDescription": "**`string`** Repository owner (from github-vcs)." }, "repo": { "type": "string", "description": "Repository name (from github-vcs).", "markdownDescription": "**`string`** Repository name (from github-vcs)." }, "branch": { "type": "string", "description": "Default branch (from github-vcs).", "markdownDescription": "**`string`** Default branch (from github-vcs)." }, "initialCommit": { "type": "string", "description": "Initial commit SHA for redirect tracking (from github-vcs / arcadia-vcs).", "markdownDescription": "**`string`** Initial commit SHA for redirect tracking (from github-vcs / arcadia-vcs)." }, "scopes": { "type": "array", "items": { "type": "string", "markdownDescription": "**`string`**" }, "description": "VCS scopes (from arcadia-vcs).", "markdownDescription": "**`string[]`** VCS scopes (from arcadia-vcs)." } }, "additionalProperties": true, "markdownDescription": "**`{enabled, endpoint, owner, ...}`**" } ], "description": "Enable or disable the VCS connector. Object form accepts extension-specific fields.", "markdownDescription": "**`boolean | object`** Version control system connector.\n\n- `false` — disable VCS integration\n- `true` — enable with defaults\n- Object — explicit settings:\n - `enabled` **`boolean`**\n - `endpoint` **`string`** — API endpoint URL\n - `owner` **`string`** — repository owner (GitHub)\n - `repo` **`string`** — repository name (GitHub)\n - `branch` **`string`** — default branch\n - `initialCommit` **`string`** — SHA for redirect tracking\n - `scopes` **`string[]`** — VCS scopes (Arcadia)", "defaultSnippets": [ { "label": "GitHub VCS config", "body": { "enabled": true, "endpoint": "${1:https://api.github.com}", "owner": "${2:my-org}", "repo": "${3:my-repo}", "branch": "${4:main}" } } ] }, "vcsToken": { "type": "string", "sensitive": true, "description": "VCS access token. WARNING: Do not store secrets in the config file. Use environment variables or CLI arguments instead.", "markdownDescription": "**`string`** ⚠️ VCS access token.\n\n> **WARNING:** Do not store secrets in the config file. Use environment variables or CLI `--vcs-token` argument instead." }, "vcsPath": { "$ref": "#/definitions/Toggleable", "description": "Show the VCS file path in the page header.", "markdownDescription": "**`boolean | {enabled: boolean}`** Show the VCS file path (\"Edit on GitHub\" link) in the page header." }, "mtimes": { "$ref": "#/definitions/Toggleable", "description": "Collect file modification timestamps from VCS.", "markdownDescription": "**`boolean | {enabled: boolean}`** Collect file modification timestamps from VCS for the \"Last updated\" footer." }, "authors": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "markdownDescription": "**`boolean`**" }, "ignore": { "type": "array", "items": { "type": "string", "markdownDescription": "**`string`**" }, "markdownDescription": "**`string[]`**" } }, "additionalProperties": false, "markdownDescription": "**`{enabled, ignore}`**" } ], "description": "Collect per-file authors from VCS.", "markdownDescription": "**`boolean | object`** Collect per-file author information from VCS commit history." }, "contributors": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "markdownDescription": "**`boolean`**" }, "ignore": { "type": "array", "items": { "type": "string", "markdownDescription": "**`string`**" }, "markdownDescription": "**`string[]`**" } }, "additionalProperties": false, "markdownDescription": "**`{enabled, ignore}`**" } ], "description": "Collect per-file contributors from VCS.", "markdownDescription": "**`boolean | object`** Collect per-file contributor list from VCS commit history." }, "template": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "$ref": "#/definitions/TemplateConfig" } ], "description": "Configure the Liquid template engine.", "markdownDescription": "**`boolean | TemplateConfig`** Configure the Liquid template engine.\n\n- `false` — disable templating entirely\n- Object — fine-grained control over features and scopes", "defaultSnippets": [ { "label": "Template engine config", "body": { "enabled": true, "features": { "substitutions": true, "conditions": true, "cycles": true }, "scopes": { "text": true, "code": false } } } ] }, "lint": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "$ref": "#/definitions/LintConfig" } ], "description": "Configure YFM linting during build.", "markdownDescription": "**`boolean | LintConfig`** Configure YFM linting during the build.\n\n- `false` — disable linting\n- Object — enable with custom config path or inline rules", "defaultSnippets": [ { "label": "Lint with config file", "body": { "enabled": true, "config": "${1:.yfmlint}" } } ] }, "extensions": { "type": "array", "items": { "$ref": "#/definitions/ExtensionItem" }, "description": "External extensions loaded on startup. Each item is a package name or an object with name and options.", "markdownDescription": "**`ExtensionItem[]`** External extensions loaded at build startup.\n\nEach item is an npm package name or an object with `name` and options:\n```yaml\nextensions:\n - '@diplodoc/openapi-extension'\n - name: my-extension\n option: value\n```" }, "interface": { "type": "object", "properties": { "toc": { "type": "boolean", "description": "Show the table of contents sidebar.", "markdownDescription": "**`boolean`** Show (`true`) or hide (`false`) the table-of-contents sidebar globally." }, "toc-header": { "type": "boolean", "description": "Show the TOC header section.", "markdownDescription": "**`boolean`** Show (`true`) or hide (`false`) the TOC header section globally." }, "search": { "type": "boolean", "description": "Show the search input.", "markdownDescription": "**`boolean`** Show (`true`) or hide (`false`) the search input globally." }, "feedback": { "type": "boolean", "description": "Show feedback controls (likes / dislikes).", "markdownDescription": "**`boolean`** Show (`true`) or hide (`false`) the like/dislike feedback widget globally." }, "gallery": { "type": "boolean", "description": "Enable opening images in the gallery.", "markdownDescription": "**`boolean`** Enable (`true`, default) or disable (`false`) opening images in the gallery viewer globally." }, "favicon-src": { "type": "string", "description": "URL to a custom favicon.", "markdownDescription": "**`string`** Default favicon URL for all pages." } }, "additionalProperties": false, "description": "Viewer interface visibility flags.", "markdownDescription": "**`{toc, toc-header, search, ...}`** Global UI visibility flags. Per-page `interface` frontmatter overrides these values.\n\nAvailable fields:\n- `toc` — show/hide the sidebar\n- `toc-header` — show/hide the TOC header section\n- `search` — show/hide the search input\n- `feedback` — show/hide like/dislike controls\n- `gallery` — enable/disable opening images in the gallery\n- `favicon-src` — custom favicon URL" }, "feedbackUrl": { "type": "string", "format": "uri", "description": "URL endpoint for feedback submission.", "markdownDescription": "**`string (uri)`** URL endpoint that receives feedback submissions (POST). Used by the feedback widget." }, "resources": { "$ref": "#/definitions/Resources", "description": "Custom scripts, styles, and CSP directives.", "markdownDescription": "**`Resources`** Custom scripts, stylesheets, and CSP directives injected into every page.\n\n```yaml\nresources:\n style:\n - _assets/custom.css\n script:\n - _assets/custom.js\n```" }, "allowCustomResources": { "type": "boolean", "description": "Allow loading custom resources in static output mode.", "markdownDescription": "**`boolean`** Allow the `resources` field to inject scripts/styles in static output mode." }, "disableCsp": { "type": "boolean", "description": "Do not inject Content-Security-Policy meta tags into generated HTML pages. Use when CSP is managed externally (e.g. via server HTTP headers).", "markdownDescription": "**`boolean`** Do **not** inject `Content-Security-Policy` `` tags into the HTML output.\n\nUse this when CSP is managed via HTTP headers on the server." }, "theme": { "oneOf": [ { "type": "string", "markdownDescription": "**`string`**" }, { "type": "null", "markdownDescription": "**`null`**" } ], "description": "Override the base brand color or disable theming. null disables theme.yaml processing.", "markdownDescription": "**`string | null`** Path to a `theme.yaml` file that overrides brand colors.\n\n- `null` — disable theme processing entirely" }, "codeHighlight": { "type": ["object", "null"], "properties": { "light": { "type": "string", "markdownDescription": "**`string`** Highlight.js theme for the light UI theme.", "description": "Highlight.js theme for light UI theme." }, "dark": { "type": "string", "markdownDescription": "**`string`** Highlight.js theme for the dark UI theme.", "description": "Highlight.js theme for dark UI theme." } }, "additionalProperties": false, "description": "Code highlighting themes for light and dark UI variants. Use any theme name from highlight.js/styles without .css extension. Use \"diplodoc\" to keep the built-in Diplodoc code highlighting style.\n", "markdownDescription": "**`{light, dark} | null`** Code highlighting themes for light and dark UI variants.\n\nUse any theme name from `highlight.js/styles` (without the `.css` extension),\nor `diplodoc` to keep the built-in Diplodoc code highlighting style." }, "search": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "$ref": "#/definitions/SearchConfig" } ], "description": "Configure the documentation search feature.", "markdownDescription": "**`boolean | SearchConfig`** Documentation search feature.\n\n- `false` — disable search\n- Object — configure provider (local or algolia)", "defaultSnippets": [ { "label": "Local search", "body": { "enabled": true, "provider": "local" } }, { "label": "Algolia search", "body": { "enabled": true, "provider": "algolia", "appId": "${1:YOUR_APP_ID}", "apiKey": "${2:YOUR_API_KEY}", "indexName": "${3:my-docs}" } } ] }, "singlePage": { "type": "boolean", "description": "Produce a single-page HTML variant for each TOC.", "markdownDescription": "**`boolean`** Generate a single-page HTML variant for each TOC that concatenates all pages." }, "pdf": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "type": "object", "properties": { "enabled": { "type": "boolean", "markdownDescription": "**`boolean`**" }, "hiddenPolicy": { "type": "boolean", "description": "Exclude hidden TOC items from PDF output.", "markdownDescription": "**`boolean`** Exclude hidden TOC items from PDF output." }, "icon": { "type": "string", "description": "Custom icon for the PDF download button. Accepted values: inline SVG markup, absolute URL, or a project-relative path starting with _assets/. For md output, paths under _assets/ are copied to the output directory.", "markdownDescription": "**`string`** Custom icon for the PDF download button. Accepted values: inline SVG markup, absolute URL, or a project-relative path starting with _assets/. For md output, paths under _assets/ are copied to the output directory." }, "position": { "type": "string", "enum": ["toc", "header"], "description": "Where to render the PDF download button. toc — below the table of contents (default). header — in the page header next to other controls.", "markdownDescription": "**`'toc' | 'header'`** Where to render the PDF download button. toc — below the table of contents (default). header — in the page header next to other controls." }, "size": { "type": "string", "enum": ["S", "M", "L"], "description": "Size of the PDF download button icon.", "markdownDescription": "**`'S' | 'M' | 'L'`** Size of the PDF download button icon." }, "pdfFileUrl": { "type": "string", "description": "URL or path to the generated PDF file. Used only in static HTML builds (outputFormat: html) where the PDF download link cannot be resolved automatically. In the web viewer this value is computed on the server side.", "markdownDescription": "**`string`** URL or path to the generated PDF file. Used only in static HTML builds (outputFormat: html) where the PDF download link cannot be resolved automatically. In the web viewer this value is computed on the server side." } }, "additionalProperties": false, "markdownDescription": "**`{enabled, hiddenPolicy, icon, ...}`**" } ], "description": "Configure PDF output generation.", "markdownDescription": "**`boolean | object`** PDF output generation.\n\n- `false` — disable\n- `true` — enable with defaults\n- Object — enable with `hiddenPolicy`" }, "pdfDebug": { "type": "boolean", "description": "Include PDF start pages in the output for debugging.", "markdownDescription": "**`boolean`** Include PDF start/end pages in the HTML output for debugging page breaks." }, "llms": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "type": "object", "properties": { "enabled": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "type": "string", "enum": ["md"], "markdownDescription": "**`'md'`**" } ], "description": "Enable or disable LLMS files generation.", "markdownDescription": "**`boolean | 'md'`** Enable (`true`/`false`) or configure output format (`'md'`) for LLMS files generation." }, "description": { "type": "string", "description": "Custom description metadata for LLMS indexing.", "markdownDescription": "**`string`** Custom description metadata for LLMS indexing." }, "llmsFullMaxSize": { "$ref": "#/definitions/FileSize", "description": "Maximum size of llms-full.txt. Article ingestion stops when the limit is reached (YFM022 info). Default: 4M.", "markdownDescription": "**`string | integer`** Maximum size of `llms-full.txt`. When the accumulated content exceeds this limit, article ingestion stops and `YFM022` is logged as info. Default: `4M`." }, "url": { "type": "string", "format": "uri", "description": "Override URL for llms.txt used in md companion AI hints.", "markdownDescription": "**`string (uri)`** Override URL for `llms.txt` used in md companion AI hints. When set, md companions link to this URL instead of the generated `llms.txt`." } }, "additionalProperties": false, "markdownDescription": "**`{enabled, description, llmsFullMaxSize, url}`**" } ], "description": "Configure LLMS (Large Language Model Structure) file generation.", "markdownDescription": "**`boolean | object`** Configure LLMS (Large Language Model Structure) files (`llms.txt` / `llms-full.txt`) generation.\n\n- `false` — disable LLMS generation entirely\n- Object — fine-grained control over format and indexing metadata\n - `llmsFullMaxSize` — max size of `llms-full.txt` (default `4M`)", "defaultSnippets": [ { "label": "Standard LLMS setup", "body": { "enabled": true, "description": "${1:Project documentation for LLM ingestion.}" } }, { "label": "Markdown format LLMS setup", "body": { "enabled": "md", "description": "${1:Project documentation for LLM ingestion.}" } } ] }, "preprocess": { "type": "object", "properties": { "hashIncludes": { "type": "boolean", "markdownDescription": "**`boolean`** Replace included file paths with content hashes." }, "mergeIncludes": { "type": "boolean", "markdownDescription": "**`boolean`** Inline `{% include %}` directives — merge the included content into the parent file." }, "mergeAutotitles": { "type": "boolean", "markdownDescription": "**`boolean`** Merge auto-generated heading anchors." }, "mergeSvg": { "type": "boolean", "markdownDescription": "**`boolean`** Inline SVG `` references as `` blocks." }, "disableMetaMaxLineWidth": { "type": "boolean", "markdownDescription": "**`boolean`** Disable the maximum line-width limit on metadata output." } }, "additionalProperties": false, "description": "Fine-tune Markdown preprocessing for md output format.", "markdownDescription": "**`{hashIncludes, mergeIncludes, mergeAutotitles, ...}`** Markdown preprocessing flags for `md` output format only.\n\n- `hashIncludes` **`boolean`** — replace include paths with content hashes\n- `mergeIncludes` **`boolean`** — inline `{% include %}` directives\n- `mergeAutotitles` **`boolean`** — merge auto-generated heading anchors\n- `mergeSvg` **`boolean`** — inline SVG `` as `` blocks\n- `disableMetaMaxLineWidth` **`boolean`** — disable metadata line-width limit" }, "mergeIncludes": { "type": "boolean", "description": "Merge include contents into parent files (shorthand).", "markdownDescription": "**`boolean`** Shorthand for `preprocess.mergeIncludes: true`." }, "content": { "type": "object", "properties": { "maxInlineSvgSize": { "$ref": "#/definitions/FileSize", "description": "Maximum size for inline SVG embedding.", "markdownDescription": "**`string | integer`** Maximum SVG file size for inline embedding.\n\nFormat: `'100K'`, `'2M'`, or bytes as integer. Larger files are kept as `` references." }, "maxHtmlSize": { "$ref": "#/definitions/FileSize", "description": "Maximum rendered HTML file size.", "markdownDescription": "**`string | integer`** Maximum rendered HTML file size. Build warns if a page exceeds this limit." }, "maxAssetSize": { "$ref": "#/definitions/FileSize", "description": "Maximum asset file size. 0 disables the check.", "markdownDescription": "**`string | integer`** Maximum single asset file size. `0` disables the check." }, "maxOpenapiIncludeSize": { "$ref": "#/definitions/FileSize", "description": "Maximum size of a generated OpenAPI page (and its spec companion). Pages above the limit are replaced with a stub; companions above the limit are not emitted. 0 disables the check.\n" }, "maxOpenapiIncludeInlineSize": { "$ref": "#/definitions/FileSize", "description": "Maximum size of the OpenAPI specification embedded inline on a leading page. If exceeded, 'leadingPage.spec.renderMode: inline' auto-switches to 'link'. Default: 100K. Hard-capped at 1M. 0 means always render the spec as a link.\n" }, "multilineTermDefinitions": { "type": "boolean", "description": "Allow term definitions to span multiple lines. When enabled, a definition continues until the next [*key]: or end of block. Default: false.", "markdownDescription": "**`boolean`** Allow term definitions (`[*key]: ...`) to span multiple lines. Default: `false`." } }, "additionalProperties": false, "markdownDescription": "**`{maxInlineSvgSize, maxHtmlSize, maxAssetSize, multilineTermDefinitions}`** Content size limits and processing options.\n\n- `maxInlineSvgSize` **`string | integer`** — max SVG size for inline embedding\n- `maxHtmlSize` **`string | integer`** — max rendered HTML page size\n- `maxAssetSize` **`string | integer`** — max asset file size (`0` = no limit)\n- `multilineTermDefinitions` **`boolean`** — allow multi-line term definitions", "defaultSnippets": [ { "label": "Set content size limits", "body": { "maxInlineSvgSize": "${1:10K}", "maxHtmlSize": "${2:1M}", "maxAssetSize": "${3:5M}" } } ] }, "ai": { "type": "object", "properties": { "openapiCompanions": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": ["md"] } ], "description": "Emit standalone OpenAPI spec companions (*.openapi.json, name derived from the source spec) next to generated OpenAPI leading pages. true — emit in both md2md and md2html; 'md' — emit only in md2md (default); false — disabled.\n", "markdownDescription": "**`boolean | 'md'`** Emit standalone OpenAPI spec companions (`*.openapi.json`)\nnext to generated OpenAPI leading pages.\n\n- `true` — emit in both md2md and md2html\n- `'md'` — emit only in md2md (default)\n- `false` — disabled" } }, "additionalProperties": false, "description": "AI-related build options.", "markdownDescription": "**`{openapiCompanions}`** AI-related build options." }, "removeHiddenTocItems": { "type": "boolean", "description": "Strip hidden items from the table of contents.", "markdownDescription": "**`boolean`** Strip `hidden: true` items from the compiled TOC JSON." }, "removeEmptyTocItems": { "type": "boolean", "description": "Strip empty items from the table of contents.", "markdownDescription": "**`boolean`** Strip TOC sections that have no visible child pages after filtering." }, "buildManifest": { "type": "boolean", "description": "Emit yfm-build-manifest.json with all documentation paths.", "markdownDescription": "**`boolean`** Emit `yfm-build-manifest.json` listing all built page paths." }, "crawlerManifest": { "type": "boolean", "description": "Emit crawler-manifest.json mapping each source file to its external links. Useful for link-health checks (detecting 404, 403, etc.).", "markdownDescription": "**`boolean`** Emit `crawler-manifest.json` mapping each source file to its external links. Useful for link-health checks (404/403 detection)." }, "changelogs": { "oneOf": [ { "type": "boolean", "markdownDescription": "**`boolean`**" }, { "type": "string", "markdownDescription": "**`string`**" } ], "description": "Enable changelog generation. String value selects the format.", "markdownDescription": "**`boolean | string`** Enable changelog generation. String value selects the output format." }, "watch": { "type": "boolean", "description": "Enable file-watching mode with incremental rebuilds.", "markdownDescription": "**`boolean`** Enable file-watching mode with incremental rebuilds on change." }, "skipHtmlExtension": { "type": "boolean", "description": "Remove .html extension from generated links.", "markdownDescription": "**`boolean`** Remove `.html` extension from all generated internal links." }, "rawAddMeta": { "type": "boolean", "markdownDescription": "**`boolean`**" }, "addResourcesMeta": { "type": "boolean", "markdownDescription": "**`boolean`**" }, "addMetadataMeta": { "type": "boolean", "markdownDescription": "**`boolean`**" }, "aiChat": { "$ref": "#/definitions/AiChatConfig", "description": "AI chat widget configuration (internal docs-viewer).", "markdownDescription": "**`AiChatConfig`** AI chat widget configuration (internal docs-viewer).\n\n- `requestExamples`**`string[] | false | object`** — example prompts, optionally per-language map\n- `soTags`**`string | string[]`** — Stack Overflow tags attached to the chat context\n- `stIssues`**`AiChatStIssuesSlice[]`** — Startrek tracker slices attached to the chat context" }, "analytics": { "$ref": "#/definitions/AnalyticsConfig", "markdownDescription": "**`AnalyticsConfig`** Web analytics configuration.\n\n- `gtm` **`AnalyticsConfig`** — Google Tag Manager (`id: string`, `mode: 'base' | 'notification'`)", "properties": { "gtm": { "markdownDescription": "**`object`** Google Tag Manager settings.\n\n- `id` **`string`** — GTM container ID (e.g. `GTM-XXXXXX`)\n- `mode` **`'base' | 'notification'`** — consent mode", "properties": { "id": { "markdownDescription": "**`string`** GTM container ID (e.g. `GTM-XXXXXX`)." }, "mode": { "markdownDescription": "**`'base' | 'notification'`** GTM consent mode.", "markdownEnumDescriptions": [ "Base consent mode — basic analytics.", "Notification consent mode — additional consent signals." ] } } } } }, "neuroExpert": { "$ref": "#/definitions/NeuroExpertConfig", "description": "AI expert widget configuration.", "markdownDescription": "**`NeuroExpertConfig`** AI expert widget global configuration.\n\n- `projectId` **`NeuroExpertConfig`** — language → project ID map\n- `hasOutsideClick` **`boolean`** — close on outside click\n- `parentId` **`string | null`** — parent element ID\n- `disabled` **`boolean`** — disable widget globally\n- `customLabel` **`NeuroExpertConfig`** — language → custom header label map\n- `type` **`'widget' | 'search'`** — widget integration type" }, "yabug": { "$ref": "#/definitions/YaBugConfig", "description": "Bug report widget configuration (docs-viewer).", "markdownDescription": "**`YaBugConfig`** Bug-report widget (docs-viewer) global configuration.\n\n- `disabled` **`boolean`** — disable widget globally\n- `form` **`string`** — custom bug-report form URL or path" }, "yafeedback": { "$ref": "#/definitions/YaFeedbackConfig", "description": "Feedback widget configuration (docs-viewer).", "markdownDescription": "**`YaFeedbackConfig`** Yandex Feedback (Pythia) widget global configuration.\n\n- `ownerId` **`string | object`** — feedback owner ID or per-language map\n- `hideHeader` **`boolean`** — hide widget header\n- `disabled` **`boolean`** — disable widget globally\n- `testIds` **`YaFeedbackConfig`** — A/B test form IDs" }, "docs-viewer": { "$ref": "#/definitions/DocsViewerConfig", "description": "Configuration for the docs-viewer preview server.", "markdownDescription": "**`DocsViewerConfig`** Configuration for the docs-viewer preview server.\n\nKey fields: `project-name`, `lang`, `langs`, `favicon-src`, `logo-options`, `metrika`, `gtm`, `themes`.", "defaultSnippets": [ { "label": "Docs viewer config", "body": { "project-name": "${1:my-project}", "lang": "${2:en}", "langs": ["${3:en}"] } } ] }, "pages": { "type": "object", "properties": { "accessDenied": { "type": "object", "additionalProperties": true, "markdownDescription": "**`object`** Custom 403 access-denied page settings (passed to the viewer's page renderer)." }, "notFound": { "type": "object", "additionalProperties": true, "markdownDescription": "**`object`** Custom 404 not-found page settings (passed to the viewer's page renderer)." }, "serverError": { "type": "object", "additionalProperties": true, "markdownDescription": "**`object`** Custom 500 server-error page settings (passed to the viewer's page renderer)." } }, "additionalProperties": false, "description": "Custom error/access-denied page configuration.", "markdownDescription": "**`{accessDenied, notFound, serverError}`** Custom error and access-denied page configuration.\n\n- `accessDenied` **`{accessDenied, notFound, serverError}`** — custom 403 page settings\n- `notFound` **`{accessDenied, notFound, serverError}`** — custom 404 page settings\n- `serverError` **`{accessDenied, notFound, serverError}`** — custom 500 page settings" }, "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": "**`{domain, parameters}[]`**" } }, "additionalProperties": false, "description": "Query parameter forwarding rules for embedded iframes.", "markdownDescription": "**`{iframes}`** Global query parameter forwarding rules for `