Link Validation and Linting

Every sarde build checks the internal links in your content, and sarde check-links runs the same check without building. Optionally, Sarde also probes external URLs. A separate content linter flags Markdown quality problems such as skipped heading levels and missing image alt text. Each link problem has a policy that decides whether it fails the build, logs a warning, or is ignored.

Link checker overview

The checker validates internal links and #anchor references to headings. It resolves each link inside its own lane, the language and version of the page that contains it: a link in French v2 docs resolves against French v2 pages. Use the ?lang= and ?version= query parameters for links that cross lanes (see Internal Links).

No configuration is needed. The build prints a summary line that counts the findings by policy, followed by one line per finding with its path:line:col location:

[links] checked 12 links across 2 lanes: 1 error
  ERROR  content/docs/guide.md:7:3  broken target    ./missing.md

A run without findings prints no issues after the lane count. Identical findings in one file appear once, followed by a count such as (x3).

Each finding has one of these types:

Sarde never guesses what a bare name.md means. It reports the link as an ambiguous link, and the finding's hint gives the fix: write ./name.md for a sibling page or docs/name.md from the content root. Every finding carries the 1-based line and column of the link in its source file: the pretty report shows them as path:line:col, and the json report as line and col.

Image sources in the body are not checked, and static assets such as /img/logo.png and the site root / linked from the body are never reported as unverified.

A full build re-validates every link target and anchor, including on pages served from the page cache, so renaming a linked page is caught without editing the file that links to it.

Frontmatter links

The checker also covers the frontmatter fields the theme writes into the page as a URL. The theme uses these values unchanged, so write them as site URLs, not .md paths:

---
title: Field trip
image: /images/field-trip.jpg
prev:
  link: /blog/lab-safety/
next: pond-samples
---

→ The build checks that public/images/field-trip.jpg exists, that /blog/lab-safety/ is a page, and that the blog collection has a page with the slug pond-samples.

A relative value resolves from the page's URL, as a browser resolves it: image: photo.jpg on a bundle page finds the photo.jpg beside its index.md. External URLs are skipped, unless external URL probing is on. A frontmatter finding has no line number: the report shows the field instead, as content/blog/field-trip.md (frontmatter image), and the json report adds a field key. link_validation.exclude patterns apply to these values too.

Configurable policies

A policy is "error" (fails the build), "warn" (logs a warning), or "ignore" (skips the finding). Defaults:

link_validation:
  enabled: true
  on_broken: "error"
  on_broken_anchor: "error"
  on_relative_links: "warn"
  on_local_links: "warn"
  on_unverified_internal: "warn"

External URL probing

External link checking is off by default. Turn it on to probe http:// and https:// URLs for reachability during the build:

link_validation:
  external:
    check: true
    on_broken: "warn"

A URL counts as reachable when it returns a status from 200 to 399. Results, failures included, are cached in .sarde/linkcache.json and reused until cache_ttl expires, so a fixed URL is not rechecked until then. Delete the cache file to force a fresh probe.

sarde check-links

Run link validation without rendering templates or writing output:

sarde check-links

→ The command prints the summary line and one line per finding, ordered by source file. It exits with code 1 when any finding has the error policy. The report goes to stderr in every format.

sarde check is an alias for sarde check-links.

Report formats

Choose a format with --report or link_validation.report:

Set the default format in sarde.yaml:

link_validation:
  report: "github-actions"

Fail CI on link problems

sarde build and sarde check-links exit with code 1 when any finding has the error policy, which blocks a deployment step. The defaults already do this for broken targets and anchors. To fail on every kind of finding, run the stricter check in CI before the build:

sarde check-links --strict

Content lint rules

The content linter checks Markdown structure independently of link validation. It runs as the content_lint plugin during the build and only ever warns, so it never fails a build. Configure it under the top-level content_lint key:

content_lint:
  enabled: true
  rules:
    heading_max_length: 60
    heading_increment: true
    image_alt_required: true
    no_empty_links: true
    frontmatter_required: []
    tabs_marker_syntax: true

Each warning names the file and the line, for example line 13: heading level skipped from h1 to h4. Draft pages are skipped. To lint without building, run sarde validate. It lints by default (--lint=false skips it), and --strict exits with code 1 when any warning exists.

In sarde dev, an incremental rebuild lints only the changed pages, so warnings for other pages do not repeat until the next full build.