From 45fa3f06cb60f0d9a9c8924da30a869388f60622 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 01:56:20 +0000 Subject: [PATCH] docs: document mint broken-links --links-to --- .../context/skills/mintlify/reference/cli.md | 2 +- cli/commands.mdx | 17 +++++++++++++++++ guides/linking.mdx | 2 +- mint-instructions/configure/navigation.mdx | 2 +- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/agent-context/context/skills/mintlify/reference/cli.md b/agent-context/context/skills/mintlify/reference/cli.md index 57703bd566..5e0e1ddd2a 100644 --- a/agent-context/context/skills/mintlify/reference/cli.md +++ b/agent-context/context/skills/mintlify/reference/cli.md @@ -75,7 +75,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. 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 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. `mint broken-links --links-to /guides/setup` lists every internal link (file and line) that resolves to that page instead of checking for broken links; add `#anchor` to match one section. 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 ffea06453b..4d8dbd5c8d 100644 --- a/cli/commands.mdx +++ b/cli/commands.mdx @@ -518,6 +518,7 @@ For links without a leading `/` and anchor links (`#`) inside a snippet, the com | `--check-external` | Also check external URLs for broken links. | | `--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. | +| `--links-to` | List every internal link that points to a page instead of checking for broken links. | 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. @@ -532,6 +533,22 @@ mint broken-links --files "guides/**/*.mdx" mint broken-links --files introduction.mdx "guides/**/*.mdx" ``` +### Find links to a page + +Pass `--links-to` with a page path to list every internal link that points to that page, with the file and line of each link. Use it when you move, rename, or delete a page to find the links you need to update. + +The command matches links by the page they resolve to, so relative links and links with a file extension also match. Add an anchor, such as `/guides/setup#install`, to list only links to that section. + +```bash +# List links to a page +mint broken-links --links-to /guides/setup + +# List links to a section of a page +mint broken-links --links-to /guides/setup#install +``` + +Combine `--links-to` with `--files` to search only specific pages. The command exits with code `0` whether or not it finds links. Pass a page path, not a full URL or an anchor on its own. + --- ## `mint a11y` diff --git a/guides/linking.mdx b/guides/linking.mdx index 37423bbc88..5abd0d40b5 100644 --- a/guides/linking.mdx +++ b/guides/linking.mdx @@ -180,7 +180,7 @@ When moving or renaming pages: 1. Update the page path in your navigation configuration. 2. Configure redirects from the old path to the new path. -3. Search your documentation for references to the old path. +3. Find references to the old path with `mint broken-links --links-to /old-path`. 4. Update all internal links to use the new path. 5. Run `mint broken-links` to verify. diff --git a/mint-instructions/configure/navigation.mdx b/mint-instructions/configure/navigation.mdx index cf68fb4cb8..086b63289b 100644 --- a/mint-instructions/configure/navigation.mdx +++ b/mint-instructions/configure/navigation.mdx @@ -12,7 +12,7 @@ related: false 1. Read the current `navigation` object and identify its root pattern (`groups`, `tabs`, `anchors`, `dropdowns`, `products`, `versions`, `languages`, or plain `pages`). Keep that pattern; add inside it. 2. Create the page file first (`guides/setup.mdx`), then add its path to a `pages` array as `"guides/setup"`: relative to the `docs.json` directory, no leading slash, no extension. 3. To add a section, add an object to the existing array at the right level (a new `{ "group": ..., "pages": [...] }` or `{ "tab": ..., "groups": [...] }`). -4. When moving or renaming a page: move the file, update its path in `navigation`, add a `redirects` entry from the old URL to the new one, and fix internal links. +4. When moving or renaming a page: move the file, update its path in `navigation`, add a `redirects` entry from the old URL to the new one, and fix internal links. Find them with `mint broken-links --links-to /guides/old`. 5. Run `mint validate`, then `mint broken-links --check-redirects`, then `mint dev --no-open` and click through the new section. ## Rules