This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit e684630a7f38d3ffd6312f7212616f56e457041b Author: Stephen Mallette <[email protected]> AuthorDate: Thu Jul 16 15:39:20 2026 -0400 Note that cross-book xrefs do not resolve in the tinker-doc skill Each book builds separately, so <<anchor>> across books fails silently. Assisted-by: Claude Code:claude-opus-4-8 --- .../tinker-doc/references/asciidoc-and-wiring.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/.skills/tinker-doc/references/asciidoc-and-wiring.md b/.skills/tinker-doc/references/asciidoc-and-wiring.md index 3d6d9d8183..b69572654d 100644 --- a/.skills/tinker-doc/references/asciidoc-and-wiring.md +++ b/.skills/tinker-doc/references/asciidoc-and-wiring.md @@ -16,9 +16,25 @@ anywhere with `<<anchor,display text>>`: ... see the <<where-step,where()-step>> for a related filter. ``` -Anchors are how the whole documentation set links together. Give every section a -stable, descriptive anchor and prefer cross-referencing an existing section over -restating its content. +Give every section a stable, descriptive anchor and prefer cross-referencing an +existing section over restating its content. + +**`<<anchor>>` only resolves inside its own book.** Each book under `docs/src/` +builds as a separate document, so a cross-reference from one book to another does +not work even when the anchor exists. It also fails *silently* rather than +breaking the build: `<<subgraph-step>>` renders as the literal text +`[subgraph-step]`, and `<<gremlin-java-pdt,Gremlin-Java>>` renders as a dead +same-page link to a fragment the page does not contain. + +To point at another book, use a full `link:` to the published site instead: + +``` +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#labels-step[labels()] +``` + +This matters most in the upgrade book, which is nearly always talking about +reference, provider, or IO material that lives elsewhere. Note that upgrade docs +pin a concrete version rather than `x.y.z` — see the exception below. ## The `x.y.z` version placeholder
