docs: explain which links mint broken-links checks

agent-context/context/skills/mintlify/reference/cli.md

@@ -73,7 +73,7 @@ JSON report fields:
 
 ## Content quality
 
-- `mint broken-links` — Check for broken internal links. `--files <paths...>` 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 that snippet import paths resolve. Paths without a leading `/`, `#`, or `?` (for example, `next` or `./next`) resolve from the page's directory, as in the browser. Inside snippets, these and `#` links are checked against each page that renders the snippet. Reference-style link definitions and `href`/`src` values written as string or static template literals (`href={"/a"}`) are checked; dynamic expressions are skipped.
+- `mint broken-links`: Check for broken internal links. `--files <paths...>` 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 that snippet import paths resolve. Checks Markdown links and images, `href` on `<a>` and `<Card>`, and `src` on `<img>` and `<source>`. Paths without a leading `/`, `#`, or `?` (for example, `next` or `./next`) resolve from the page's directory, as in the browser; start with `/` to link from the site root. Inside snippets, these and `#` links are checked against each page that renders the snippet. Reference-style link definitions and `href`/`src` values written as string or static template literals (`href={"/a"}`) are checked; dynamic expressions are skipped.
 - `mint a11y` — Accessibility checks (alt text, color contrast). `--skip-contrast` or `--skip-alt-text` to narrow scope.
 - `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.

cli/commands.mdx

@@ -100,8 +100,8 @@
 | `--org-name` | Organization display name. |
 | `--directory` | Documentation directory for the site. Defaults to the current directory. |
 | `--new` | Create another site instead of reusing the site for this directory. |
 | `--email` | Email address to create a claim link for. Can't be combined with `--github`. |
 | `--github` | Trust the current GitHub repository to deploy the site and write `.github/workflows/mintlify.yml`. |
 | `--force` | With `--github`, overwrite an existing workflow file that has different contents. |
 
 Run the command again from the same directory to get a fresh write token for the same site. In GitHub Actions, `mint deploy` pushes the checked-out commit to a site that trusts the repository. The workflow needs the `id-token: write` permission.
@@ -135,7 +135,7 @@
 | `--code` | Code from the claim page that finishes the claim. |
 | `--directory` | Documentation directory used for `mint deploy`. Defaults to the current directory. |
 
 Run `mint claim --email` to get a claim link. After the site owner opens the link and signs in, run `mint claim --code` with the code from the claim page. `--email` and `--code` can't be combined.
 
 ### Examples
 
@@ -211,7 +211,7 @@
 
 Add the `TXT` records first, then add the `CNAME` once the verification records validate. See [Custom domain](/customize/custom-domain) for full DNS setup instructions, apex domain requirements, and TLS provisioning details.
 
 If the command fails with `Domain is already in use by another deployment in your organization` or `Domain is already claimed by another organization`, the domain is bound to another Mintlify project. See [Add domain fails with "Domain is already claimed by another organization"](/help-center/domain-already-claimed-by-another-organization) to release it and re-add it.
 
 <Note>
   If some `TXT` records are still generating when the command exits, check the [Custom domain setup](https://app.mintlify.com/settings/project/custom-domain) page in your dashboard for the remaining values.
@@ -258,7 +258,7 @@
 
 ### `mint analytics stats`
 
 Display top-line KPIs for a date range: views, visitors, searches, feedback, and assistant usage. The output reports human and agent traffic separately.
 
 ```bash
 mint analytics stats [flags]
@@ -388,7 +388,7 @@
 
 | Agent | Project file | User account file (`--global`) |
 | --- | --- | --- |
 | Claude Code | `.mcp.json` | `~/.claude.json` |
 | Codex | `.codex/config.toml` | `~/.codex/config.toml`, or `config.toml` in `CODEX_HOME` when set |
 | Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
 
@@ -400,7 +400,7 @@
 claude mcp add --scope user --transport http mintlify-admin https://mcp.mintlify.com
 ```
 
 Setup keeps your existing configuration and skips an agent that already has a matching `mintlify-admin` entry. If a `mintlify-admin` entry has a different configuration, or a configuration file can't be parsed, setup stops before it installs skills. Rename or remove the conflicting entry, then run the command again.
 
 Rerunning the command refreshes the installed skills and replaces any local edits you made to them.
 
@@ -499,7 +499,11 @@
 
 The command scans `.mdx` and `.md` files for links and excludes files matching [.mintignore](/organize/mintignore) patterns. Links inside OpenAPI specification files (`.yaml`, `.yml`, `.json`) are not checked. Links that point to ignored files report as broken.
 
-Relative links (`./`, `../`) and anchor links (`#`) inside a snippet are checked against each page that renders the snippet. The command reports one of these links only if it is broken on at least one of those pages. With `--check-anchors`, headings inside a snippet count as anchors on the pages that render it.
+The command checks Markdown links and images, including reference-style links such as `[text][id]`. It also checks the `href` of `<a>` and `<Card>` components and the `src` of `<img>` and `<source>` tags, whether written as a plain string or as a fixed value in braces, such as `href={"/quickstart"}`. Values computed from variables are not checked.
+
+Links without a leading `/`, such as `quickstart` or `../quickstart`, resolve from the directory of the page that contains them, the same way a browser resolves them. To link from the root of your site, start the path with `/`.
+
+For links without a leading `/` and anchor links (`#`) inside a snippet, the command checks each page that renders the snippet. The command reports one of these links only if it is broken on at least one of those pages. With `--check-anchors`, headings inside a snippet count as anchors on the pages that render it.
 
 | Flag | Description |
 | --- | --- |
@@ -509,7 +513,7 @@
 | `--check-redirects` | Also check that redirect destinations in `docs.json` resolve to valid paths. |
 | `--check-snippets` | Also check that snippet import paths resolve to existing files. |
 
 Pass `--files` to limit the check to specific pages. This is useful for validating a single page you just edited or scoping checks to a directory in CI. When `--files` is set with `--check-external`, only external URLs on the selected pages are fetched.
 
 ```bash
 # Check a specific page
@@ -566,7 +570,7 @@
 | `missing-file` | `content` | Reports imported files that don't exist. Needs the build. |
 | `import-error` | `content` | Reports imports in pages and snippets that don't resolve. Needs the build. |
 | `missing-nav-page` | `nav` | Reports pages in your navigation that have no file. Needs the build. |
 | `package-import` | `config` | Reports npm package imports that are undeclared or conflict. Needs the build. |
 | `build-failed` | `config` | Reports a strict build failure that no other rule explains. Needs the build. |
 | `openapi-spec` | `openapi` | Reports OpenAPI specifications in `docs.json` or `mint.json` that don't parse or validate, with overlays applied. |
 | `openapi-build` | `openapi` | Reports OpenAPI pages the build could not generate. Needs the build. |
@@ -590,7 +594,7 @@
   Commit or stash your changes before you run `--fix`, so you can review its edits.
 </Tip>
 
 With `--format json`, progress output is hidden and other console output goes to stderr, so you can parse stdout directly. The report has these fields:
 
 - `passed`: `true` when no rule reported an error.
 - `summary`: `errors` and `warnings` counts, plus `byRule` with a count for each rule ID.
@@ -650,9 +654,9 @@
 | `--surface` | Try a surface (`brand` or `neutral`) without editing `docs.json`. |
 | `--appearance` | Try an appearance (`light` or `dark`) without editing `docs.json`. |
 | `--output` | Where to write the PNG. Defaults to a temporary file. |
 | `--no-open` | Don't open the image after rendering. The command also skips opening it when the `CI` environment variable is set. |
 
 The command prints warnings when the title is too long to fit on two lines, when no logo is configured or the logo fails to load, when the font fails to load, and when text has low contrast on a `brand` surface. Warnings don't change the exit code. The command exits with code `1` if `docs.json` is invalid or the page doesn't exist.
 
 ```bash
 # Render one page and open it
@@ -761,13 +765,13 @@
 mint format
 ```
 
 Run the command from the root of your docs project. It walks every subdirectory, skipping paths matched by `.gitignore` and any Mintlify ignore rules. Files that already match the canonical output are left untouched.
 
 <Tip>
   Running `mint format` can result in many changes depending on the size of your project. To avoid merge conflicts and introducing changes to other in progress work, first resolve all important pending branches. Then create a new branch for formatting changes and run `mint format` on that branch.
 </Tip>
 
 When it finishes, the command prints how many MDX files were reformatted and how many failed to parse. If any file fails, the command exits with code `1` and prints the file path and error, so you can run it in CI to enforce consistent formatting. See [Install in CI](/cli/install#install-in-ci) for an example pipeline.
 
 ---
 
@@ -786,7 +790,7 @@
 | `--agent` | Start a coding agent in the current directory and have it run the migration. Accepts `claude`, `codex`, `cursor`, or `gemini`. Combine with `--from` to include a platform guide. |
 | `--claude` | Alias for `--agent claude`. |
 
 Without flags, the command prints an overview of the migration workflow followed by the available topics and source platforms. The instructions are written for coding agents, so you can paste them into your agent or let your agent run `mint migrate` itself.
 
 With `--agent`, the CLI launches the specified agent's command-line tool with a prompt to run `mint migrate` and follow the instructions it prints. You must already have the agent's CLI installed. If the Mintlify CLI can't find the agent CLI, `mint migrate` exits with an error that includes the install command.
 
@@ -855,7 +859,7 @@
 
 ## Telemetry
 
 The CLI collects usage telemetry to help improve Mintlify. Telemetry data includes the command name, CLI version, operating system, architecture, and Node.js version. It also records whether the CLI runs in a CI environment, whether it runs in an interactive terminal, whether this is the first time the CLI has run on your machine, and whether you are signed in. If the CLI detects an AI coding agent running it, telemetry also includes the agent's name. If you are signed in, telemetry events also include your account email address. Signed-out usage stays anonymous, and signing out removes your stored email. Mintlify does **not** collect project content or file paths.
 
 By default, the CLI collects telemetry data. You can opt out at any time using the `--telemetry` flag: