feat(build): optional link/anchor/orphan/unused-image validation

Add a post-build validation pass (BuildValidator) that runs after all pages,
assets, and plugin outputs are on disk:
- links: internal href/src targets must resolve to an output file
- anchors: #fragment must match an element id on the target page
- unusedImages: docs images never referenced by a page
- orphanPages: source pages not reachable from the nav

Each problem is logged as a warning; the existing --strict / MKDOCS_STRICT
path turns warnings into a failing build. All checks are opt-in via a new
"validation" config block (SiteConfig.Validation + JsonConfigLoader).

Enable links+anchors on the dogfood site — which surfaced 3 real doc bugs,
now fixed: two stale affiliate-links.md links (plugin renamed to link-notes)
and a wrong #5-verify-parity anchor (slug is #verify-parity).

Docs: new reference/validation.md (+ nav + cli.md cross-link). 8 unit tests
covering each check (219 tests pass).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Netdocs

docs-site/appsettings.json

@@ -58,6 +58,7 @@
           { "path": "reference/configuration.md" },
           { "path": "reference/theme.md" },
           { "path": "reference/cli.md" },
+          { "path": "reference/validation.md" },
           { "path": "setup/migrating-from-mkdocs.md" }
         ]
       },
@@ -132,6 +133,10 @@
       { "name": "social" }
     ],
 
+    "validation": { "links": true, "anchors": true },
+
+    
+
     "markdownExtensions": [
       { "name": "admonition" },
       { "name": "pymdownx.details" },

docs-site/docs/about/netdocs-vs-mkdocs.md

@@ -89,4 +89,4 @@ Choose **Netdocs** if you want a fast, single-binary/container build, typed exte
 built-in deploy/optimization, and your Markdown + plugin needs are covered above. Stay on
 **Material for MkDocs** if you depend on a niche PyMdown extension, the Python plugin ecosystem, or
 mike-based doc versioning that isn't implemented yet — or run both and
-[diff the output](../setup/migrating-from-mkdocs.md#5-verify-parity) before switching.
+[diff the output](../setup/migrating-from-mkdocs.md#verify-parity) before switching.

docs-site/docs/plugins/index.md

@@ -53,7 +53,7 @@ annotate outbound links (e.g. affiliate disclosures). A few plugins are intentio
 | [blog](blog.md) | Only meaningful for sites with a `blog/` posts directory. |
 | [social](social.md) | Generates images (slower); best gated behind `netdocs build --prod`. |
 | [file-filter](file-filter.md) | Needs a `.file-filter.yml` and env vars to do anything. |
-| [affiliate-links](affiliate-links.md) | Requires you to declare your affiliate programs. |
+| [link-notes](link-notes.md) | Requires you to declare your affiliate programs / link rules. |
 | [arithmatex](arithmatex.md) / [b64](b64.md) | Enable when you actually use math or inline-image embedding. |
 
 Ordering only matters for Markdown preprocessors (they transform source text in sequence);
@@ -99,7 +99,7 @@ content generators — are not page-scoped and always apply.
 | [file-filter](file-filter.md) | Env-driven label include/exclude. |
 | [macros](macros.md) | `fileuri()` / `button()` Markdown macros (mkdocs-macros subset). |
 | [table-reader](table-reader.md) | Expand `read_csv()` / `read_table()` into Markdown tables. |
-| [affiliate-links](affiliate-links.md) | Auto tooltip + footer disclosure for affiliate links. |
+| [link-notes](link-notes.md) | Auto tooltip + footer disclosure for affiliate links. |
 | [b64](b64.md) | Embed local images as inline `data:` URIs (pymdownx.b64). |
 | [arithmatex](arithmatex.md) | LaTeX math typeset with MathJax (pymdownx.arithmatex). |
 | [typeset](typeset.md) | Smart typography (curly quotes, en/em dashes, ellipses) via SmartyPants. |

docs-site/docs/reference/cli.md

@@ -36,7 +36,7 @@ If no command is given, `build` is assumed.
 | `--port <port>` | `-p` | Dev server port for `serve` (default `8000`). |
 | `--clean` | | Remove existing output before building. |
 | `--no-cache` | | Ignore the incremental render cache and re-render every page. |
-| `--strict` | | Fail on plugin/template errors. |
+| `--strict` | | Treat build warnings (including [validation](validation.md) problems, plugin/template errors) as failures. |
 | `--prod` | `--production` | Production build (enables prod-only plugins such as social cards). |
 | `--verbose` | `-v` | Verbose (Trace) logging. |
 | `--remote <name>` | | `watch`: git remote to poll (default `origin`). |

docs-site/docs/reference/validation.md

@@ -0,0 +1,73 @@
+---
+title: Build validation
+---
+
+# Build validation
+
+Netdocs can validate your site as part of the build and report problems as **warnings**. Pair it
+with [`--strict`](cli.md#options) (or the `MKDOCS_STRICT` environment variable) to turn those
+warnings into a non-zero exit code so CI fails on a broken site.
+
+All checks are **opt-in** and default to `false`. Enable the ones you want under a `validation`
+block in `appsettings.json`:
+
+```json
+"validation": {
+  "links": true,
+  "anchors": true,
+  "unusedImages": false,
+  "orphanPages": false
+}
+```
+
+## Checks
+
+| Option | What it checks | Emits a warning when… |
+|---|---|---|
+| `links` | Internal `href`/`src` targets in the rendered pages | a link resolves to a file that isn't in the output |
+| `anchors` | `#fragment` anchors on internal links (requires `links`) | the target page has no element with that `id` |
+| `unusedImages` | Image files under your `docs/` directory | an image is never referenced by any page |
+| `orphanPages` | Source Markdown pages | a page isn't reachable from the navigation tree |
+
+What is **not** flagged:
+
+- **External URLs** (`http://`, `https://`, protocol-relative `//host`), `mailto:`, `tel:`,
+  `data:` URIs, and unresolved template tokens are skipped — link checking is offline and never
+  makes network requests.
+- Generated pages (blog indexes, tag pages, etc.) are ignored by the orphan-page check.
+
+Validation runs **last**, after every page, asset, and plugin output is written, so link targets
+are resolved against the real files on disk.
+
+## Failing the build in CI
+
+Warnings alone don't change the exit code — they're informational. Add `--strict` to abort:
+
+```bash
+netdocs build --strict
+```
+
+```
+warn: Broken link in guide/setup.md: '../missing/' does not resolve to an output file.
+info: Validation found 1 problem(s).
+error: Aborting build: 1 warning(s) treated as errors (strict mode).
+```
+
+The same applies to `netdocs deploy --strict`, which refuses to publish when validation fails.
+`MKDOCS_STRICT=1` is honored as an alias so existing MkDocs CI pipelines keep working.
+
+## Example: strict links in CI, lenient locally
+
+Keep the checks enabled in config, but only fail the build in CI:
+
+```json
+"validation": { "links": true, "anchors": true }
+```
+
+```bash
+# Local authoring — see warnings, but keep building
+netdocs serve
+
+# CI — fail on any broken link or anchor
+netdocs build --prod --strict
+```

src/Netdocs.Abstractions/SiteConfig.cs

@@ -49,6 +49,9 @@ public sealed class SiteConfig
     /// <summary>Output optimization toggles (HTML minification, etc.).</summary>
     public OptimizeConfig Optimize { get; set; } = new();
 
+    /// <summary>Optional build-time validation (internal links, anchors, orphaned files).</summary>
+    public ValidationConfig Validation { get; set; } = new();
+
     /// <summary>Absolute path to the project root (folder containing mkdocs.yml).</summary>
     public string ProjectRoot { get; set; } = "";
 
@@ -182,6 +185,29 @@ public sealed class OptimizeConfig
     public int WebpQuality { get; set; } = 80;
 }
 
+/// <summary>
+/// Build-time validation. Every enabled check emits a <c>warning</c> per problem; combine with
+/// <c>--strict</c> (or <c>MKDOCS_STRICT=1</c>) to turn those warnings into a non-zero build exit.
+/// All checks are opt-in and default to <c>false</c>.
+/// </summary>
+public sealed class ValidationConfig
+{
+    /// <summary>Verify that internal links and asset references (<c>href</c>/<c>src</c>) in the
+    /// rendered pages resolve to a file that exists in the output. External URLs, anchors, and
+    /// <c>mailto:</c>/<c>tel:</c>/<c>data:</c> links are skipped.</summary>
+    public bool Links { get; set; }
+
+    /// <summary>Verify that <c>#fragment</c> anchors in internal links point at an element that
+    /// actually has that <c>id</c> on the target page. Requires <see cref="Links"/>.</summary>
+    public bool Anchors { get; set; }
+
+    /// <summary>Warn about image assets under the docs directory that no rendered page references.</summary>
+    public bool UnusedImages { get; set; }
+
+    /// <summary>Warn about markdown pages that are not reachable from the navigation tree.</summary>
+    public bool OrphanPages { get; set; }
+}
+
 /// <summary>An authored navigation entry: either a link to a page or a titled section.</summary>
 public sealed class NavItem
 {

src/Netdocs.Core/BuildEngine.cs

@@ -125,6 +125,7 @@ public async Task<SiteContext> BuildAsync(CancellationToken ct = default)
         site.State["asset_versioner"] = new AssetVersioner(ThemePaths.AssetsDir, config.AbsoluteDocsDir);
 
         var rendered = new ConcurrentBag<(string Path, string Html)>();
+        var renderedPages = new ConcurrentBag<Validation.RenderedPage>();
         var minify = config.Optimize.MinifyHtml;
         var webpWrap = config.Optimize.ConvertImagesToWebp;
         Parallel.ForEach(site.Pages, new ParallelOptions { CancellationToken = ct }, page =>
@@ -133,6 +134,7 @@ public async Task<SiteContext> BuildAsync(CancellationToken ct = default)
             if (webpWrap) html = Optimization.WebpHtmlRewriter.Rewrite(html);
             if (minify) html = Optimization.HtmlMinifier.Minify(html);
             rendered.Add((page.OutputPath, html));
+            renderedPages.Add(new Validation.RenderedPage(page, html));
         });
         var changed = 0;
         foreach (var (path, html) in rendered)
@@ -184,6 +186,11 @@ public async Task<SiteContext> BuildAsync(CancellationToken ct = default)
         var pruned = OutputWriter.PruneStale(site, config.AbsoluteSiteDir);
         if (pruned > 0) _log.LogInformation("Pruned {Count} stale output files", pruned);
 
+        // 14. Optional build-time validation (links, anchors, unused images, orphan pages).
+        // Runs last so every page/asset/plugin output is materialized on disk. Problems are
+        // logged as warnings; `--strict` (or MKDOCS_STRICT) turns them into a failing build.
+        Validation.BuildValidator.Validate(site, renderedPages.ToList(), _log);
+
         sw.Stop();
         _log.LogInformation("Built {Count} pages in {Ms} ms", site.Pages.Count, sw.ElapsedMilliseconds);
         return site;

src/Netdocs.Core/Configuration/JsonConfigLoader.cs

@@ -43,9 +43,18 @@ public static SiteConfig Load(string appSettingsPath)
             Slugify = ParseSlugify(root.Get("slugify").AsMap()),
             Deploy = ParseDeploy(root.Get("deploy").AsMap()),
             Optimize = ParseOptimize(root.Get("optimize").AsMap()),
+            Validation = ParseValidation(root.Get("validation").AsMap()),
         };
     }
 
+    private static ValidationConfig ParseValidation(IReadOnlyDictionary<string, object?> m) => new()
+    {
+        Links = m.Get("links").AsBool(false),
+        Anchors = m.Get("anchors").AsBool(false),
+        UnusedImages = m.Get("unusedImages").AsBool(false),
+        OrphanPages = m.Get("orphanPages").AsBool(false),
+    };
+
     private static DeployConfig ParseDeploy(IReadOnlyDictionary<string, object?> m) => new()
     {
         Target = m.Get("target").AsString() ?? "none",