Skip to content

[docs]: broken links #167

@yaythomas

Description

@yaythomas

Summary

zensical build --clean prints 19 validation warnings about broken
intra-doc links in docs/sdk-reference/. Every warning is one of
three mistakes:

  • singular vs plural filename (steps.md, callbacks.md,
    child-contexts.md — the actual files are singular);
  • a stale path from an earlier doc reorganization
    (../advanced/error-handling.md, error-handling.md,
    ../../testing/basic-tests.md, ../getting-started.md);
  • one anchor slug that no longer matches its heading
    (#retrying-specific-errors vs ## Retry only specific errors,
    which Zensical slugifies to retry-only-specific-errors).

None of these break the published site (links render but 404 on
click), but they surface as build warnings and should resolve cleanly.

Broken links

# File Line Broken link Suggested fix
1 sdk-reference/error-handling/retries.md 111 #retrying-specific-errors #retry-only-specific-errors
2 sdk-reference/observability/logging.md 406 ../operations/child-contexts.md ../operations/child-context.md
3 sdk-reference/observability/logging.md 407 error-handling.md ../error-handling/errors.md
4 sdk-reference/operations/child-context.md 322 steps.md step.md
5 sdk-reference/operations/map.md 689 steps.md step.md
6 sdk-reference/operations/map.md 690 ../advanced/error-handling.md ../error-handling/errors.md
7 sdk-reference/operations/parallel.md 736 steps.md step.md
8 sdk-reference/operations/parallel.md 737 ../advanced/error-handling.md ../error-handling/errors.md
9 sdk-reference/operations/step.md 431 ../../testing/basic-tests.md ../../testing/index.md
10 sdk-reference/operations/wait-for-condition.md 7 steps.md step.md
11 sdk-reference/operations/wait-for-condition.md 19 callbacks.md callback.md
12 sdk-reference/operations/wait-for-condition.md 184 callbacks.md callback.md
13 sdk-reference/operations/wait-for-condition.md 185 steps.md step.md
14 sdk-reference/operations/wait-for-condition.md 186 ../getting-started.md ../../getting-started/index.md
15 sdk-reference/operations/wait.md 24 steps.md step.md
16 sdk-reference/operations/wait.md 35 callbacks.md callback.md
17 sdk-reference/operations/wait.md 263 steps.md step.md
18 sdk-reference/operations/wait.md 265 callbacks.md callback.md
19 sdk-reference/operations/wait.md 266 ../getting-started.md ../../getting-started/index.md

Repro

pip install zensical==0.0.40
zensical build --clean 2>&1 | grep -E 'Warning:|issues found'
# 19 issues found

Acceptance criteria

  • zensical build --clean prints No issues found.
  • Every listed link resolves to an existing page in the built site.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

Status

Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions