Docs broken links fix. Phase 1#319
Open
pmcfadin wants to merge 2 commits intoapache:trunkfrom
Open
Conversation
Resolves five distinct fix classes in the asf-staging source tree: - blog/Apache-Cassandra-4.0-Overview.adoc: xref target extension .html -> .adoc so Antora resolves the AsciiDoc source instead of a rendered URL. - blog/Configurable-Storage-Ports-and-Why-We-Need-Them.adoc: remove a duplicate document title line that triggered a level-0 section error. - blog/Even-Higher-Availability-with-5x-Faster-Streaming-in-Cassandra-4.adoc: update xref from removed faster_streaming_in_cassandra.adoc to current Hardware-bound-Zero-Copy-Streaming-in-Apache-Cassandra-4.adoc. - development/gettingstarted.adoc, development/ide.adoc: replace malformed xref:: (double colon) with xref:development/... so the target resolves. - development/index.adoc: add leveloffset=+1 to all include:: directives so included pages' = document titles render as sub-sections rather than firing level-0 errors. Verified locally against both pre- and post-fix builds via site-content/bin/xref-report.sh --baseline: fixed 11, introduced 0. Remaining 9 errors in the local build (missing images, partials, and a few path rewrites) are separate fix classes and will follow. patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21342
Second batch of broken-xref / broken-asset fixes on the asf-staging
source tree:
- blog/Apache-Cassandra-Changelog-{19-September,20-November}-2022.adoc:
replace rendered-site xref target doc/latest/cassandra/architecture/
overview.adoc with the Antora component-qualified form
Cassandra:cassandra:architecture/overview.adoc.
- blog/Apache-Cassandra-Changelog-20-November-2022.adoc: remove a space
that had crept into the xref target for the Cassandra-Day-SC-Bellevue-
Houston-WakandaForever.adoc file.
- glossary.adoc: remove three include directives that referenced partials
never present in this repo (persistent-volume, persistent-volume-claim,
segment).
- download.adoc: rewrite image target from absolute rendered URL
/assets/img/caution.svg to the Antora-relative form caution.svg (the
asset lives in modules/ROOT/images/).
- apachecon_cfp.adoc: remove reference to /img/apachecon-2019.jpg, an
asset that was lost during the 2020 Jekyll-to-Antora migration
(CASSANDRA-16066). Surrounding 2019 archival prose stays intact.
Local verification via xref-report.sh delta against the post-batch-1
build: 8 of 9 targeted errors demonstrably resolved (total went from 9
to 3). Remaining 3 errors (2 from the architecture/overview rewrites,
1 from the main-nav Cassandra::index.adoc reference) all depend on the
Cassandra component being present in the Antora build. The local
verification build was a minimal website-only run (no -g flag) that
does not import the Cassandra component, so these three cannot be
validated locally; the Jenkins build resolves the Cassandra component
from multiple version sources and is the authoritative test for them.
The main-nav Cassandra::index.adoc xref was NOT touched in this commit.
Root cause analysis shows cassandra/doc/antora.yml declares the 6.0
version as prerelease, which disqualifies it as the default target for
unversioned xrefs. Fix direction (un-prerelease, pin a version, or
re-point the nav) is production-config-sensitive and left for a
separate ticket.
patch by Patrick McFadin; reviewed by TBD for CASSANDRA-21342
pmcfadin
force-pushed
the
broken-link-fix
branch
from
764ee46 to
22b83fd
Compare
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is the start of a few PRs to retire the pile of technical debt we have, going back to Cassandra 4 with broken links.
Two-commit fix for 19 broken Antora references in cassandra-website's own content. A separate PR will land on the in-tree docs after this passes staging. Together, the two PRs retire the broken-link tech debt that has been showing up in the Jenkins build's error-level log.
JIRA: https://issues.apache.org/jira/browse/CASSANDRA-21342