> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# holydocs links

Scan your documentation for broken internal links and report issues.

## Usage

```bash
holydocs links [options]
```

Crawls all MDX and Markdown files in your documentation project, extracts internal links, and verifies that each link points to a page that exists. This catches broken links before they reach production.

## Options

| Option | Description | Default |
|---|---|---|
| `--dir <path>` | Root directory of the docs project | Auto-detected |

## Examples

### Check All Links

```bash
holydocs links
```

Output when all links are valid:

```
Checking for broken links...

Found 56 documentation files.

✓ All 312 links are valid!
```

### Check with Broken Links

```bash
holydocs links
```

Output when broken links are found:

```
Checking for broken links...

Found 56 documentation files.

Found 3 broken link(s):

  quickstart.mdx:45
    → /setup — Page not found

  guides/authentication.mdx:12
    → /api/legacy-auth — Page not found

  api-reference/overview.mdx:8
    → /concepts/rate-limiting — Page not found

Checked 312 total links across 56 files.
```

### Check in a Specific Directory

```bash
holydocs links --dir ./docs
```

## What Gets Checked

The link checker scans for two patterns in every `.mdx` and `.md` file:

| Pattern | Example |
|---|---|
| Markdown links | `[Getting Started](/quickstart)` |
| HTML href attributes | `<a href="/guides/cicd">` |

For each internal link found, the checker normalizes the path and verifies that a matching page exists in the project.

### Link Normalization

Links are normalized before checking:

| Raw Link | Normalized Slug |
|---|---|
| `/guides/cicd` | `guides/cicd` |
| `/guides/cicd/` | `guides/cicd` |
| `/` | `index` |
| `guides/cicd` | `guides/cicd` |

The checker also resolves `/index` suffixes, so a link to `/guides` matches a file at `guides/index.mdx`.

## Skipped Links

The following link types are intentionally skipped during checking:

| Type | Examples | Reason |
|---|---|---|
| External URLs | `https://example.com`, `http://...` | External availability is not checked |
| Anchor links | `#section-heading` | Anchor validation requires rendered HTML |
| Email links | `mailto:support@example.com` | Not a page reference |
| Asset paths | `/_assets/logo.png` | Assets are handled separately |
| API routes | `/api/v1/...` | Runtime API endpoints, not doc pages |

The link checker focuses on internal page-to-page links. For external link validation, consider using a dedicated tool like `linkinator` or `broken-link-checker` on your deployed site.

## Exit Codes

| Code | Meaning |
|---|---|
| `0` | All internal links are valid |
| `1` | One or more broken links were found |

The non-zero exit code makes `holydocs links` suitable for CI pipelines and pre-commit hooks.

## CI Integration

Add link checking to your CI pipeline to prevent broken links from reaching production:

```yaml
# GitHub Actions
- name: Check for broken links
  run: npx @holydocs/cli links --dir ./docs
```

```yaml
# GitLab CI
check-links:
  script:
    - npx @holydocs/cli links --dir ./docs
  allow_failure: false
```

Run `holydocs links` alongside `holydocs check` in your CI pipeline for comprehensive validation. While `check` validates configuration and frontmatter, `links` performs a deeper scan of every link in your content.

## Differences from holydocs check

Both `holydocs check` and `holydocs links` validate internal links, but they serve different purposes:

| Feature | `holydocs check` | `holydocs links` |
|---|---|---|
| Config validation | Yes | No |
| Frontmatter validation | Yes | No |
| Navigation completeness | Yes | No |
| Internal link scanning | Basic | Thorough (all files) |
| MDX syntax validation | Yes | No |
| OpenAPI spec validation | Yes | No |
| JSON output | `--json` flag | No |
| Auto-fix | `--fix` flag | No |

For the most thorough pre-deploy validation, run both commands:

```bash
holydocs check && holydocs links
```

## Troubleshooting

### False Positives

If a link is reported as broken but the page exists, check that:

1. The file extension is `.mdx` or `.md` (other extensions are not indexed)
2. The file is not inside `node_modules` or a `.`-prefixed directory
3. The link path matches the file path exactly (link checking is case-sensitive)

### Large Projects

For projects with hundreds of pages, the link checker processes all files in a single pass. No configuration is needed for performance tuning.

## Related

- [holydocs check](/cli/check) -- Full project validation including config and content
- [holydocs build](/cli/build) -- Build static HTML (fails on render errors but not broken links)
- [holydocs dev](/cli/dev) -- Preview locally to manually verify link targets