fix: resolve same-page fragment links via AnchorHyperlinkResolver
#1301
Conversation
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
Same-page fragment links in markdown (e.g., `[Section](#section-one)`)
were producing bare `#section-one` URLs because
`ExternalReferenceResolver` intercepted all `#`-prefixed references and
set bare fragment URLs, preventing `AnchorHyperlinkResolver` from
resolving them to canonical URLs.
When combined with a `<base href>` tag in the HTML template (used by
phpDocumentor for subdirectory pages), browsers resolve bare fragment
URLs against the base URL rather than the current page, causing
table-of-contents links to navigate away instead of scrolling.
Remove the `str_starts_with('#')` branch from
`ExternalReferenceResolver` so fragment-only references are no longer
claimed as "external". Instead, `AnchorHyperlinkResolver` now handles
them: it looks up the anchor in the project's internal targets and
produces a canonical URL (e.g., `/index.html#section-one`). When no
target matches (e.g., RST explicit fragment hyperlinks like
`` `link <#abc>`__ ``), it falls back to the bare fragment URL to
preserve backward compatibility.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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.
Same-page fragment links in markdown (e.g.,
[Section](#section-one)) were producing bare#section-oneURLs becauseExternalReferenceResolverintercepted all#-prefixed references and set bare fragment URLs, preventingAnchorHyperlinkResolverfrom resolving them to canonical URLs.When combined with a
<base href>tag in the HTML template (used by phpDocumentor for subdirectory pages), browsers resolve bare fragment URLs against the base URL rather than the current page, causing table-of-contents links to navigate away instead of scrolling.Remove the
str_starts_with('#')branch fromExternalReferenceResolverso fragment-only references are no longer claimed as "external". Instead,AnchorHyperlinkResolvernow handles them: it looks up the anchor in the project's internal targets and produces a canonical URL (e.g.,/index.html#section-one). When no target matches (e.g., RST explicit fragment hyperlinks like`link <#abc>`__), it falls back to the bare fragment URL to preserve backward compatibility.