From 4f6914f0dd7aaeb3e71a366c039ffcdeeb540b6a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 31 Oct 2026 09:17:20 +0000 Subject: [PATCH] docs: explain which links mint broken-links checks --- agent-context/context/skills/mintlify/reference/cli.md | 2 +- cli/commands.mdx | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/agent-context/context/skills/mintlify/reference/cli.md b/agent-context/context/skills/mintlify/reference/cli.md index cae9baa23..9096855cd 100644 --- a/agent-context/context/skills/mintlify/reference/cli.md +++ b/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 ` 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 ` 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 `` and ``, and `src` on `` and ``. 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. diff --git a/cli/commands.mdx b/cli/commands.mdx index 2678edefb..323914101 100644 --- a/cli/commands.mdx +++ b/cli/commands.mdx @@ -499,7 +499,11 @@ mint broken-links [flags] 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 `` and `` components and the `src` of `` and `` 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 | | --- | --- |