holydocs links

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:

text
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:

text
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 foundChecked 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 CIcheck-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 -- Full project validation including config and content
• holydocs build -- Build static HTML (fails on render errors but not broken links)
• holydocs dev -- Preview locally to manually verify link targets