From d0e172e8ebeaa3fcd073b01a67375f7ad267b7de Mon Sep 17 00:00:00 2001 From: "mintlify-agent-context-sync[bot]" Date: Tue, 8 Sep 2026 15:57:00 +0000 Subject: [PATCH] Sync Mintlify agent context --- .mintlify-agent-context.json | 2 +- skills/mintlify/SKILL.md | 2 +- skills/mintlify/reference/api-docs.md | 18 ++++++++++++++++++ skills/mintlify/reference/cli.md | 1 + skills/mintlify/reference/configuration.md | 4 ++-- 5 files changed, 23 insertions(+), 4 deletions(-) diff --git a/.mintlify-agent-context.json b/.mintlify-agent-context.json index 5189e8f..9835931 100644 --- a/.mintlify-agent-context.json +++ b/.mintlify-agent-context.json @@ -2,6 +2,6 @@ "schemaVersion": 1, "sourceRepository": "mintlify/docs", "sourcePath": "agent-context", - "sourceCommit": "06341336d2beeed2d783317b1d4e9793124fa49a", + "sourceCommit": "4d8f31feb82f7d9b83b62cda4b918492c8a41674", "target": "cursor" } diff --git a/skills/mintlify/SKILL.md b/skills/mintlify/SKILL.md index 57fadbf..bf7907d 100644 --- a/skills/mintlify/SKILL.md +++ b/skills/mintlify/SKILL.md @@ -220,7 +220,7 @@ Use `` to arrange cards (or other content) in a grid. `cols` accepts 1- ## CLI commands -Install with `npm i -g mint`. Key commands: `mint dev` (local preview), `mint validate`, `mint broken-links`, `mint a11y`, `mint score`, `mint automations`, `mint new`, `mint signup`, `mint index` (install the Mintlify Index MCP server in supported coding agents). Read `reference/cli.md` for full flags and subcommands. +Install with `npm i -g mint`. Key commands: `mint dev` (local preview), `mint validate`, `mint broken-links`, `mint a11y`, `mint test` (generate tests for code blocks), `mint score`, `mint automations`, `mint new`, `mint signup`, `mint index` (install the Mintlify Index MCP server in supported coding agents). Read `reference/cli.md` for full flags and subcommands. ## Writing standards diff --git a/skills/mintlify/reference/api-docs.md b/skills/mintlify/reference/api-docs.md index 2c93ee3..6927003 100644 --- a/skills/mintlify/reference/api-docs.md +++ b/skills/mintlify/reference/api-docs.md @@ -30,6 +30,24 @@ Reference individual endpoints in navigation: } ``` +### Overlays + +Transform an OpenAPI spec without editing its source file using [OpenAPI Overlay](https://spec.openapis.org/overlay/v1.1.0.html) documents (Overlay versions 1.0 and 1.1). List overlays with the object form of `openapi`, which works anywhere `openapi` is accepted, including navigation elements and arrays: + +```json +"openapi": { + "source": "openapi.json", + "overlays": ["overlays/rename-paths.yaml", "https://example.com/overlays/servers.yaml"] +} +``` + +An overlay document has an `overlay` version, an `info` object with `title` and `version`, an optional `extends` field linking it to a spec, and an `actions` array. Each action selects nodes with an RFC 9535 JSONPath `target` and applies one modifier: `update` (merge value into node), `remove` (delete node when `true`), or `copy` (copy node from another JSONPath; Overlay 1.1 only). + +- Overlays apply in listed order, after parsing and before validation. Generated pages, navigation, `openapi` frontmatter references, and `mint validate` all use the transformed document, so frontmatter must reference post-overlay paths. +- Overlay paths must point to files inside the docs repo; overlay URLs must use `https`. Referencing the same spec with different `overlays` lists in different places fails the build. +- Auto-discovery: any JSON or YAML file with a top-level `overlay` key whose `extends` field resolves to one of your specs applies automatically, in alphabetical order of file paths. An explicit `overlays` list replaces auto-discovery for that spec. Set `"overlays": []` to disable all overlays for a spec. +- Explicit overlays that fail to load or apply fail the spec's validation; failed auto-discovered overlays are skipped and the spec publishes without them. + ### File uploads For OpenAPI 3.1 specs, describe a file upload field as a string schema with a binary `contentMediaType` inside a `multipart/form-data` request body. The playground renders it as a file input and sends the request as multipart form data. diff --git a/skills/mintlify/reference/cli.md b/skills/mintlify/reference/cli.md index 10064fe..288bcff 100644 --- a/skills/mintlify/reference/cli.md +++ b/skills/mintlify/reference/cli.md @@ -24,6 +24,7 @@ Available on all commands. - `mint broken-links` — Check for broken internal links. `--files ` limits the check to specific files or globs. `--check-anchors` validates `#` anchors. `--check-external` checks external URLs. `--check-redirects` checks that redirect destinations in `docs.json` resolve. `--check-snippets` checks links inside `` components. - `mint a11y` — Accessibility checks (alt text, color contrast). `--skip-contrast` or `--skip-alt-text` to narrow scope. +- `mint test` — Scan content for code blocks and generate unit tests that validate them. Interactive; only pages in the `docs.json` navigation appear for selection. Writes generated test projects to `tests/mint-test//` and run reports/history to `.mintlify/test/`. Add both paths to `.gitignore` to avoid committing test artifacts. - `mint score [url]` — Score a docs site's AI/agent readiness. Checks llms.txt, MCP discoverability, robots.txt, sitemap, structured data, response latency, and more. Requires `mint login`. Defaults to your configured subdomain. `--format` accepts `table` (default), `plain`, or `json`. - `mint format` — Format every `.mdx` file in the current directory and its subdirectories in place. Respects `.gitignore` and Mintlify ignore rules. Commit or stash changes first so you can review the rewrite. diff --git a/skills/mintlify/reference/configuration.md b/skills/mintlify/reference/configuration.md index addd723..4542e43 100644 --- a/skills/mintlify/reference/configuration.md +++ b/skills/mintlify/reference/configuration.md @@ -460,8 +460,8 @@ Controls whether clicking a navigation group navigates to its first page (`true` } ``` -- `openapi`: Single file, array, or object with `source` and `directory`. -- `asyncapi`: Same format as `openapi` for AsyncAPI specs. +- `openapi`: Single path or URL, array of paths/URLs/objects, or object with `source`, `directory`, and `overlays` (array of OpenAPI Overlay paths or URLs applied in order; `[]` disables all overlays, including auto-discovered ones). +- `asyncapi`: Single file, array, or object with `source` and `directory` for AsyncAPI specs. - `playground.display`: `"interactive"`, `"simple"`, `"none"`, or `"auth"`. - `playground.proxy`: Route requests through Mintlify's proxy. Default: `true`. - `playground.credentials`: Include cookies and auth headers for cross-origin requests when proxy is `false`. Default: `false`.