Skip to content

馃 [Fix]: Strict documentation builds resolve migrated links#509

Description

Context and request

Observed behavior: Push-Location docs; zensical build --strict aborts with 28 "page does not exist" warnings. The failures are in pre-existing migrated documentation links, including Dictionary/, get-started/, guides/, reference/, and the documentation landing page; the new PowerShell guidance page has no warning.

Expected behavior: The Process-PSModule documentation site builds successfully with zensical build --strict, and every internal documentation link resolves.

Reproduction:

Push-Location docs
zensical build --strict

Environment: Windows, PowerShell 7.6.4, Zensical installed from Python 3.14.

Regression: Unknown. The broken links predate the guidance-script import and appear to be migration residue.

Workaround: Run zensical build without --strict; it completes and generates the site while reporting the warnings.

Acceptance criteria:

  • zensical build --strict exits successfully from docs/.
  • Every currently reported internal-link warning is corrected or intentionally removed.
  • The documentation site continues to generate successfully.

Technical decisions

The correction is limited to resolving existing internal documentation references and must not add unrelated content. Start from the reported warning locations, verify each intended target, and update only the incorrect links or missing target pages. The likely cause is incomplete path migration during documentation consolidation; verify that hypothesis while implementing.

Use the strict Zensical build as the regression check because it deterministically demonstrates the defect before and after the repair.


Implementation plan

  1. Reproduce the strict-build failure and record the complete warning set.
  2. Resolve each affected internal link or restore the intended target page with the smallest compatible change.
  3. Run zensical build --strict and the normal documentation build.
  4. Link this repair to the documentation-consolidation context in Consolidate PSModule documentation into Process-PSModule and retire PSModule/docs聽#423.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions