Validating Relative Paths and Internal Anchors
Not every link points to an external website. Many of the most important references in technical documentation are internal: links to other pages in the same repository, sections within the current document, or assets like images and downloads. These relative paths and anchor fragments must be validated too, but they require a completely different approach since no network request is involved.
For relative paths, the checker needs context about the document's location. When run against a single file, it assumes the file is at the root or uses a provided base directory. When scanning an entire folder or git repository, it resolves paths relative to the source file's position in the directory tree. This allows accurate checking of links like ../getting-started/introduction.md or images/logo.png without guessing.
Local File Existence Checks
Once resolved, the checker verifies that the target file actually exists on disk. If the path points to a Markdown file, it can optionally recurse and validate links within that file too, creating a complete internal graph. Missing files are reported as errors with the exact relative path that failed, making it easy for authors to correct typos or move content without breaking references.
Anchor and Heading Fragments
In-page anchors are handled by parsing the target document for matching identifiers. For standard Markdown headings, the checker automatically generates slugified IDs based on the heading text, following common conventions such as lowercase, hyphen-separated words. It then checks whether the fragment after the hash symbol matches any heading ID or explicit anchor in the linked document. Custom IDs defined with attributes are also recognized and validated.
Same-page anchors, where the link starts with a hash and no path, are resolved against the current file. This ensures that table-of-contents entries, jump links, and section references work as expected even after content is rearranged. Invalid anchors are flagged so authors can fix typos or update headings without leaving dangling references.
Offline-First Validation
All of this happens offline, using only the local filesystem and parsed Markdown content. No internet connection is required, making internal link checking fast, private, and reliable even in air-gapped environments or during CI runs without network access. By treating internal references with the same rigor as external ones, the tool helps maintain a fully navigable documentation experience from start to finish.
Comprehensive internal validation closes the loop on link hygiene. When combined with external checks, it ensures documentation is robust, discoverable, and user-friendly regardless of where readers start reading.
This concludes the technical insights series on the Markdown Link Checker. Thank you for reading.