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.
Summary
zensical build --cleanprints 19 validation warnings about brokenintra-doc links in
docs/sdk-reference/. Every warning is one ofthree mistakes:
steps.md,callbacks.md,child-contexts.md— the actual files are singular);(
../advanced/error-handling.md,error-handling.md,../../testing/basic-tests.md,../getting-started.md);(
#retrying-specific-errorsvs## 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
sdk-reference/error-handling/retries.md#retrying-specific-errors#retry-only-specific-errorssdk-reference/observability/logging.md../operations/child-contexts.md../operations/child-context.mdsdk-reference/observability/logging.mderror-handling.md../error-handling/errors.mdsdk-reference/operations/child-context.mdsteps.mdstep.mdsdk-reference/operations/map.mdsteps.mdstep.mdsdk-reference/operations/map.md../advanced/error-handling.md../error-handling/errors.mdsdk-reference/operations/parallel.mdsteps.mdstep.mdsdk-reference/operations/parallel.md../advanced/error-handling.md../error-handling/errors.mdsdk-reference/operations/step.md../../testing/basic-tests.md../../testing/index.mdsdk-reference/operations/wait-for-condition.mdsteps.mdstep.mdsdk-reference/operations/wait-for-condition.mdcallbacks.mdcallback.mdsdk-reference/operations/wait-for-condition.mdcallbacks.mdcallback.mdsdk-reference/operations/wait-for-condition.mdsteps.mdstep.mdsdk-reference/operations/wait-for-condition.md../getting-started.md../../getting-started/index.mdsdk-reference/operations/wait.mdsteps.mdstep.mdsdk-reference/operations/wait.mdcallbacks.mdcallback.mdsdk-reference/operations/wait.mdsteps.mdstep.mdsdk-reference/operations/wait.mdcallbacks.mdcallback.mdsdk-reference/operations/wait.md../getting-started.md../../getting-started/index.mdRepro
Acceptance criteria
zensical build --cleanprintsNo issues found.