docs(specs): markdown viewer anchor links (GH13725)#13907
Conversation
…hors Warp's inline parser has no HTML-tag concept at all beyond the <u> special case, so raw <a href>/<a id> tags render as literal text. Separately, and more importantly, a markdown-native [text](#fragment) link already parses today but resolves as a plain URL — there's no anchor/slug concept anywhere in the content model, so neither heading-based nor explicit <a id> fragment targets can be resolved. This adds the product + tech spec for tier-zero tag warpdotdev#1 of warpdotdev#13652 (split into warpdotdev#13725): parse <a href> as a Hyperlink (small, reuses the existing link styling/click path), give headings implicit GitHub-style slugs and let <a id>/<a name> register explicit anchors (medium — a genuinely new content- model concept, not an extension of an existing type), and wire fragment clicks to the scroll-to-character-offset autoscroll API that already exists (request_autoscroll_to_exact_vertical). Phases the work so headings + <a href> ship first, since that slice also fixes markdown-native fragment links and is the highest-value piece; arbitrary <a id> targets are phase 2. Nested under specs/GH13725/ (per the specs/APP-4319/<slug>/ chain precedent).
The prior draft claimed no #-fragment click branch existed and that the fix site was FormattedTextElement::register_default_click_handlers. On master the Markdown viewer already routes #-fragment clicks through maybe_open_url -> scroll_to_matching_header -> find_matching_header, which walks outline_blocks() live per click and scrolls via request_autoscroll_to. The real gap is that find_matching_header compares against exact lowercased heading text, not a GitHub slug. Rescope phase 1 to slug-normalize inside find_matching_header (no anchor index, no cache, no invalidation lifecycle), refresh drifted line refs, add render-surface (GUI vs TUI) and user-content-prefix notes, and flag the untracked html_tag_support_tests.rs probes that must be inverted.
github-actions
Bot
added
the
external-contributor
Restore the cut cross-document non-goal as an in-scope phase, sized MEDIUM after confirming a fragment-less relative link already opens and focuses the target Markdown-viewer tab today. The remaining work is carrying the #section through the existing file-open flow and draining it as a deferred scroll once the destination document parses, reusing the same find_matching_header slug resolver as the same-document jump.
|
I'm starting a first review of this spec-only pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This specs-only PR proposes product and technical specs for Markdown viewer anchor links, covering raw <a href> parsing, GitHub-style heading fragment resolution, explicit <a id>/<a name> anchors, and cross-document fragment navigation.
Concerns
- Phase 2 explicit anchors are still under-specified: the tech spec proposes a marker representation but defers the lookup/indexing strategy and explicit-anchor precedence rules needed to implement
<a id>targets. - The slug normalizer is described as GitHub-compatible while stripping all non-ASCII heading characters, which would break README anchors for non-English headings unless documented as an intentional divergence.
- The testing plan depends on an untracked probe file instead of committed, reproducible tests that an implementation PR can update and CI can run.
Verdict
Found: 0 critical, 3 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
- Specify a genuinely GitHub-compatible slug normalizer that preserves Unicode word characters (accented Latin, CJK) instead of stripping to ASCII, so non-English README anchors keep working. - Specify phase 2's anchor lookup: extend the same live click-time walk find_matching_header already uses (no cache), reading fragment anchor_id styles alongside the header-outline pass, with a defined explicit-anchor-wins precedence rule over colliding heading slugs. - Replace the untracked-probe-file testing plan with committed test cases in markdown_parser_tests.rs and the editor resolution tests, including Unicode slug cases and the phase 2 precedence cases; frame the existing probe file as historical context only.
|
/oz-review |
|
I'm re-reviewing this spec-only pull request in response to a review request. You can view the conversation on Warp. I reviewed this pull request and requested human review from: Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR adds product and technical specs for Markdown viewer anchor-link support, covering raw <a href> links, heading slug normalization, explicit <a id>/<a name> anchors, same-document fragment navigation, cross-document fragment follow-up work, rollout phasing, and validation expectations.
Concerns
- No blocking completeness, clarity, feasibility, issue-alignment, internal-consistency, security, or spec-drift concerns found in the attached diff.
spec_context.mdreports no approved or repository spec context for this PR, so there is no implementation/spec drift to flag.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
1 participant
Closes #13725
What
Spec (product.md + tech.md, per CONTRIBUTING's spec-first workflow for feature requests) for anchor links in the Markdown viewer: parsing raw-HTML
<a href>links, GitHub-style heading auto-slugs, and in-document fragment navigation.Part of #13725 — the focused anchor-links issue split out of #13652 per maintainer guidance there. Sibling raw-HTML issues: #13721, #13726, #13732, #13733, #13734, #13735, #13736.
Why
Anchor links are the backbone of README tables of contents (cross-refs: #13083, #4720), and today both raw
<a href>tags and markdown[text](#heading)fragments dead-end in the viewer. Phase 1 is deliberately small: the notebook viewer already has a#-fragment scroll path (maybe_open_url→find_matching_header), and the actual gap is that it matches exact lowercased heading text instead of GitHub-style slugs — so the spec scopes phase 1 to slug normalization in that existing function, which also repairs markdown fragment links for free. New-surface work (<a id>targets, anchor registry) is sequenced behind it.