docs: document the --links-to flag for mint broken-links

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 <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 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. `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 `<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,10 +100,10 @@
 | `--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` | Also print a claim link, prefilled with this Mintlify account email. Can't be combined with `--github` or `--push`. |
 | `--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. |
 | `--base` | Create a [base](/base/index), which you edit in the Mintlify editor, instead of a docs site. Can't be combined with `--github`. |
 | `--push` | With `--base`, rebase the clone in the given directory onto `main` and push it to the base. For example, `--push ./my-base`. |
 
 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.
@@ -140,7 +140,7 @@
 | `--code` | Code from an older claim link that showed one. Finishes that claim. |
 | `--directory` | Documentation directory used for `mint deploy`. Defaults to the current directory. |
 
 Run `mint claim` to get a claim link. The site owner opens it, signs in with any account, and clicks **Confirm**; the site moves into a new organization in their account. `--email` and `--code` can't be combined.
 
 ### Examples
 
@@ -216,7 +216,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.
@@ -263,7 +263,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]
@@ -393,7 +393,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` |
 
@@ -405,7 +405,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.
 
@@ -509,7 +509,7 @@
 
 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 |
 | --- | --- |
@@ -518,8 +518,9 @@
 | `--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.
 
 ```bash
 # Check a specific page
@@ -532,6 +533,22 @@
 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`
@@ -578,7 +595,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. |
@@ -602,7 +619,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.
@@ -662,9 +679,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
@@ -773,13 +790,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.
 
 ---
 
@@ -798,7 +815,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.
 
@@ -892,7 +909,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. Each event also includes a session identifier that groups events from the same working session. The CLI stores it in `~/.config/mintlify/telemetry-session.json` and replaces it after 30 minutes of inactivity. 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:
 

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.
 

mint-instructions/configure/navigation.mdx

@@ -5,14 +5,14 @@
 when: "Changing navigation: groups, tabs, anchors, dropdowns, products, versions, languages"
 related: false
 ---
 `navigation` in `docs.json` defines the sidebar and every top-level section. A page that is not listed in `navigation` is hidden from the sidebar (still reachable by URL). Use this when adding a page, group or tab, or when restructuring.
 
 ## Workflow
 
 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
@@ -25,7 +25,7 @@
 - `expanded` only affects nested groups. Top-level groups are always expanded.
 - `root` makes the group title open that page. `directory` (`"none"`, `"accordion"`, `"card"`) lists children on root pages and inherits down the tree.
 - Versions: the first entry is the default unless one sets `"default": true`. `tag` adds a badge ("Latest").
 - Languages: use supported codes (`en`, `es`, `fr`, `de`, `jp`, `cn`, `pt-BR`, `zh-Hant`, ...). Each language entry can carry its own `banner`, `footer`, `navbar`.
 - `navigation.global` holds links shown on every page (for example `global.anchors`). Each needs a name key and `href`.
 - To hide a page but keep it in config, set `hidden: true` in its frontmatter.
 - Must not: create circular redirects. Redirect sources cannot contain `#anchor` or `?query`.
@@ -78,7 +78,7 @@
 }
 ```
 
 Anchors, dropdowns and products use the same shape with `anchor`, `dropdown` or `product` as the name key. Tabs containing anchors:
 
 ```json
 "navigation": {
@@ -121,7 +121,7 @@
 }
 ```
 
 OpenAPI in navigation: set `openapi` on a group, tab or anchor. With no `pages`, every endpoint is generated. List endpoints to control which appear. Children inherit the spec. Details: `mint instructions api-docs`.
 
 ```json
 {