MD057 - Check that file links work¶

Aliases: existing-relative-links

What this rule does¶

Verifies that relative links to other files in your documentation actually point to files that exist. This includes both inline links and reference-style link definitions.

Why this matters¶

• Prevents frustration: Broken links waste readers' time and damage trust
• Maintains quality: Working links show your documentation is well-maintained
• Aids navigation: Readers can confidently explore your documentation
• Catches typos: Common mistakes in file paths are caught early

Examples¶

✅ Correct¶

[Installation Guide](install.md)          <!-- File exists -->
[Contributing](../CONTRIBUTING.md)        <!-- File exists -->
[GitHub Repo](https://github.com/org/repo) <!-- External URL -->
[Email Us](mailto:[email protected])       <!-- Email link -->
[Jump to Section](#configuration)         <!-- Same-file anchor -->

<!-- Reference-style links -->
[readme]: ./README.md                     <!-- File exists -->
[external]: https://example.com           <!-- External URL -->

❌ Incorrect¶

[Missing Doc](does-not-exist.md)           <!-- File doesn't exist -->
[Bad Path](../missing/guide.md)            <!-- Path doesn't exist -->
[Typo in Name](READNE.md)                 <!-- Should be README.md -->
[Wrong Extension](setup.markdown)          <!-- File is setup.md -->

<!-- Reference-style links with missing targets -->
[missing]: ./does-not-exist.md            <!-- File doesn't exist -->
[bad-path]: ../missing/doc.md             <!-- Path doesn't exist -->

🔧 Fixed¶

This rule cannot automatically fix broken links because it can't know which file you intended to link to. You must manually:

1. Correct the file path
2. Create the missing file
3. Or remove the broken link

Configuration¶

absolute-links¶

Controls how absolute links (paths starting with /) are handled.

Absolute links like /api/docs or /blog/post.html are typically routes for published documentation sites, not filesystem paths. By default, MD057 ignores these because they can't be validated locally.

If you want to be notified about absolute links in your documentation (perhaps to convert them to relative links), set absolute-links = "warn".

# .rumdl.toml
[MD057]
absolute-links = "warn"

For MkDocs projects, use relative_to_docs to validate absolute links by resolving them relative to the docs_dir configured in mkdocs.yml. This finds the mkdocs.yml by walking up from the file being checked, reads the docs_dir setting (default: docs), and checks that the linked file exists there.

# .rumdl.toml
[global]
flavor = "mkdocs"

[MD057]
absolute-links = "relative_to_docs"

With this configuration, a link like [Guide](/getting-started/) will be validated by checking if docs/getting-started/index.md exists. Extensionless links like /getting-started will also try markdown extensions (e.g., docs/getting-started.md).

If no mkdocs.yml is found, the behavior falls back to warn.

For Hugo, VitePress, or any multi-root content layout, use relative_to_roots together with the roots list to specify which directories serve as the site root(s).

# .rumdl.toml
[MD057]
absolute-links = "relative_to_roots"
roots = ["content/en", "content/zh-cn"]

With this configuration, a link like [Guide](/docs/guide.md) passes when content/en/docs/guide.md or content/zh-cn/docs/guide.md exists. A warning is emitted only when none of the configured roots — or the project root (see below) — contain the target.

Project-root fallback. After every configured root has been tried, the absolute link is also resolved against the project root. This supports two common link styles in the same project without extra configuration:

• [guide](/docs/guide.md) — relative to a configured root (e.g. resolves under content/en/docs/guide.md).
• [guide](/content/en/docs/guide.md) — literal path from the project root.

Both pass as long as the target file exists somewhere on the configured-or-implicit search path. A warning is emitted only when no resolution finds the file.

The project root is discovered by walking up from rumdl's invocation directory looking for the first directory that contains .git, .rumdl.toml, pyproject.toml, or .markdownlint.json. This means absolute links resolve consistently whether you run rumdl from the project root or from any subdirectory.

URL-encoded paths (e.g., /foo%20bar.md) are decoded before the filesystem check. Fragment suffixes (e.g., /page.md#section) are stripped. Roots may be absolute paths or paths relative to the project root; trailing slashes are normalized.

When roots is empty, validation falls through to the project-root resolution alone — useful for single-root projects where every absolute link is meant to resolve from the project root directly.

compact-paths¶

When enabled, warns about relative links that contain unnecessary path traversal. Disabled by default.

For example, in doc/sub_dir/file2.md, the link [text](../sub_dir/file1.md) goes up to doc/ then back into sub_dir/ — the same directory the file is already in. The shorter equivalent is just file1.md.

# .rumdl.toml
[MD057]
compact-paths = true

When enabled, this rule also provides auto-fix support: running rumdl check --fix will replace unnecessarily long paths with their shorter equivalents.

Paths that are already optimal are not flagged:

Fragment (#section) and query (?v=1) suffixes are preserved in the suggested fix.

search-paths¶

Additional directories to search when a relative link target is not found relative to the file's directory. Paths are resolved relative to the discovered project root (the first parent directory containing .git, .rumdl.toml, pyproject.toml, or .markdownlint.json), so they work consistently from any subdirectory.

# .rumdl.toml
[MD057]
search-paths = ["assets", "images", "attachments"]

With this configuration, a link like ![photo](photo.png) will first be checked relative to the markdown file's directory. If not found there, MD057 will also look in assets/photo.png, images/photo.png, and attachments/photo.png.

Obsidian users: When flavor = "obsidian" is set in the global config, the attachment folder is auto-detected from .obsidian/app.json, so this option is typically not needed. Use it for custom setups or non-Obsidian tools with similar asset directory conventions.

# .rumdl.toml — Obsidian auto-detection (no search-paths needed)
[global]
flavor = "obsidian"

Obsidian supports 4 attachment location modes configured via attachmentFolderPath in .obsidian/app.json:

Build-Generated Files¶

Documentation sites often compile markdown files to HTML during build. MD057 automatically checks if a corresponding markdown source file exists when a link points to a .html or .htm file.

For example, [Guide](guide.html) will pass if guide.md exists, even though guide.html doesn't exist in your source tree.

Handling Complex Generator Patterns¶

For documentation generators that place source files in different locations (e.g., mdBook's src/ directory), MD057 checks for markdown sources in the same directory as the HTML file. If your generator uses a different structure, you can disable MD057 for affected directories using per-file-ignores:

[per-file-ignores]

## mdBook projects - HTML links in book/ point to book/src/*.md sources

"book/**/*.md" = ["MD057"]

## Jekyll projects - HTML links in _posts/ point to generated files

"_posts/**/*.md" = ["MD057"]
"_docs/**/*.md" = ["MD057"]

## Hugo projects - HTML links in content/ point to generated files

"content/**/*.md" = ["MD057"]

MD057 will still check for markdown sources in the same directory automatically. Use per-file-ignores only when sources are in different locations.

Automatic fixes¶

Broken links cannot be automatically fixed because the rule cannot determine which file you intended to link to. They must be corrected manually.

When compact-paths = true, unnecessary path traversal can be auto-fixed with rumdl check --fix. The fix replaces long paths with their shorter equivalents while preserving any fragment or query suffix.

Learn more¶

• Markdown Guide: Links
• Writing good documentation

Related rules¶

• MD051 - Fix broken link fragments
• MD042 - Ensure links have content
• MD034 - Format bare URLs properly