Skip to content

docs(quarto): fix build-log broken refs and fenced-div warnings#321

Open
WhalerMike wants to merge 1 commit intomainfrom
claude/fervent-neumann-ce7adb
Open

docs(quarto): fix build-log broken refs and fenced-div warnings#321
WhalerMike wants to merge 1 commit intomainfrom
claude/fervent-neumann-ce7adb

Conversation

@WhalerMike
Copy link
Copy Markdown
Owner

Summary

Resolves all WARN entries from the most recent Quarto render run on PR #317 (build succeeded, but the log carried 5 broken-link warnings, 1 broken-link inside adapter-authoring-tutorial.md, and 8 Pandoc fenced-div parser warnings). Each touched file was re-rendered individually with no WARN/ERROR output after the fix.

What changed

File Fix
docs/404.qmd Replaced dead targets (adapter-framework.qmd, executive_summary_v1.0.qmd) with 13_FIMF_AdapterRegistry.qmd and customer-documents/executive-briefs/uiao-executive-brief.qmd.
docs/academy/image-pipeline-guide.qmd Removed link to orphaned inbox/UIAO-Master-Document-Spec.md; kept prose mention (spec is pending canon ingestion per the charter restoration plan).
docs/customer-documents/ROADMAP.qmd ../substrate-status.qmd../docs/substrate-status.qmd.
customer-documents/modernization/access-plane/index.qmd zero-trust.qmdzero-trust.md.
customer-documents/modernization/client-server-to-hybrid-cloud/08-access-plane.qmd zero-trust.qmdzero-trust.md.
customer-documents/modernization/uiao-modernization-program/03-phase2-governance-os.qmd ../../findings/...../../../findings/... (matches the convention in 01-phase0 and 04-phase3).
customer-documents/substrate/platform-tooling/quarto-pipeline.qmd §12.4 Replaced multiline-table whose cells contained literal ::: (which tripped the Pandoc fenced-div parser 8 times) with a clean pipe-table where the syntax examples are wrapped in inline-code backticks.
docs/docs/adapter-authoring-tutorial.md Dropped refs to nonexistent adapter-framework.qmd and adapter-development-guide.md; pointed to the live adapters/adapter-contract.qmd instead.

Not addressed (filed for follow-up)

  • The DOCX-only image resource-path warnings (~20 figures referenced as relative paths that Pandoc can't resolve from its temp dir during --to docx). HTML render is unaffected. Different class of fix (Quarto config / resource-path) — left out to keep this PR's scope tight.

Test plan

  • Quarto --to html render of the changed files completes with no WARN or ERROR lines (verified locally).
  • Full-site CI render (render job) passes with the previously-flagged WARN: Unable to resolve link target: and Pandoc fenced div lines absent from the log.
  • link-check CI job passes.

🤖 Generated with Claude Code

Resolves all WARN entries from the latest Quarto render run:

- 404.qmd: replace dead targets (adapter-framework.qmd,
  executive_summary_v1.0.qmd) with FIMF Adapter Registry and the
  UIAO Executive Brief.
- academy/image-pipeline-guide.qmd: drop link to orphaned
  inbox/UIAO-Master-Document-Spec.md (kept prose mention; spec is
  pending canon ingestion per the charter restoration plan).
- ROADMAP.qmd: ../substrate-status.qmd -> ../docs/substrate-status.qmd.
- access-plane (index + 08-access-plane): zero-trust.qmd -> .md.
- 03-phase2-governance-os.qmd: align findings/ relative path with the
  convention used in 01-phase0 and 04-phase3 (../../../findings/).
- adapter-authoring-tutorial.md: drop refs to nonexistent
  adapter-framework.qmd and adapter-development-guide.md; point
  to the live adapters/adapter-contract.qmd instead.
- quarto-pipeline.qmd 12.4: replace multiline table whose cells
  contained literal "::: {.callout-...}" (which triggered 8x the
  Pandoc fenced-div parser warning) with a pipe-table where the
  syntax examples are wrapped in inline-code backticks.

Each touched file re-rendered individually with no WARN/ERROR.
Does not address the DOCX-only image resource-path warnings
(filed as a follow-up; HTML render unaffected).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR cleans up Quarto documentation links and markdown constructs to eliminate render-log warnings (broken internal references and Pandoc fenced-div parser warnings), keeping the docs site build output warning-free.

Changes:

  • Fixes multiple broken internal doc links by pointing to existing .qmd/.md targets.
  • Updates modernization/access-plane references to the current zero-trust.md target.
  • Replaces a problematic table whose cells contained literal ::: with a pipe table using inline-code formatting to avoid Pandoc fenced-div warnings.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file
File Description
docs/404.qmd Updates quick-link targets to existing docs and executive brief pages.
docs/academy/image-pipeline-guide.qmd Removes a broken link to an orphaned inbox spec while preserving the informational reference in prose.
docs/customer-documents/ROADMAP.qmd Fixes the Substrate Status relative link to the correct docs location.
docs/customer-documents/modernization/access-plane/index.qmd Updates Zero Trust leaf link to the live zero-trust.md document.
docs/customer-documents/modernization/client-server-to-hybrid-cloud/08-access-plane.qmd Updates Zero Trust cross-reference link to zero-trust.md.
docs/customer-documents/modernization/uiao-modernization-program/03-phase2-governance-os.qmd Corrects the relative path to the docs/findings/ location for FINDING-002.
docs/customer-documents/substrate/platform-tooling/quarto-pipeline.qmd Replaces the warning-triggering table with a pipe table and inline-code examples.
docs/docs/adapter-authoring-tutorial.md Replaces dead adapter framework/guide references with a live adapter contract reference.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants