Skip to content
contextlint

REF-006 Image references

Overview

Section titled “Overview”

Validates that image references inside Markdown (the form ![alt](./img.png)) point to files that actually exist. If the target does not exist, an error is reported.

Why it matters

Section titled “Why it matters”

Image files break in the same way Markdown links do: through moves, renames, and deletions. Unlike broken links, broken images are visually obvious, but CI does not flag them and reviewers can still miss them. This rule validates image references mechanically.

Options

Section titled “Options”
FieldTypeRequiredDescription
excludestring[]—Array of glob patterns whose targets are excluded from validation

The rule works even with no options at all. Use exclude to skip images that you intentionally reference but that do not live in the repository, such as those served from an external CDN. (Absolute URLs are out of scope, so this only applies when relative paths are used.)

Bad example

Section titled “Bad example”
![Architecture diagram](./images/architecture.png)

If ./images/architecture.png does not exist, this triggers a violation.

docs/overview.md
  line 1  error  Image target "./images/architecture.png" does not exist  REF-006

After fix

Section titled “After fix”
![Architecture diagram](./images/architecture.png)

Either place the image file at the expected location, or update the reference path.

Configuration example

Section titled “Configuration example”
{
  "rule": "ref006",
  "options": {
    "exclude": ["generated/**/*.png"]
  }
}
Section titled “Related rules”