Fix Markdown ToC anchor navigation in notebooks by haikomatt · Pull Request #10143 · warpdotdev/warp

haikomatt · 2026-05-05T12:17:11Z

Description

Fixes rendered Markdown fragment links in notebook editors so links like [Goal](#goal) scroll to the matching Markdown heading instead of being routed through normal external URL/file link handling.

This adds notebook-local anchor resolution that:

matches fragments against rendered Markdown headings
normalizes heading text into GitHub-like slugs
supports duplicate headings with -1, -2, etc.
handles percent-encoded fragments

Linked Issue

Fixes #10058

The linked issue is labeled ready-to-implement.
Where appropriate, screenshots or a short video of the implementation are included below (especially for user-visible or UI changes).

Screenshots / Videos

Manual verification of rendered Markdown ToC anchor navigation using crates/editor/test_fixtures/toc_anchor_test.md.

Before navigation, the rendered Markdown viewer shows the table of contents with fragment links:

After clicking ToC links, the viewer scrolls to the corresponding normalized and duplicate heading targets:

Testing

Added regression coverage for:

matching a simple Markdown heading anchor
normalizing heading text before matching
duplicate heading anchors using numeric suffixes

Validated locally with:

cargo fmt -- --check
cargo clippy --workspace --exclude warp_completer --all-targets --tests -- -D warnings
cargo clippy -p warp_completer --all-targets --tests -- -D warnings
./script/run-clang-format.py -r --extensions 'c,h,cpp,m' ./crates/warpui/src/ ./app/src/
find . -name "*.wgsl" -exec wgslfmt --check {} +
cargo test --manifest-path app/Cargo.toml --lib test_markdown_anchor_target
cargo test --manifest-path app/Cargo.toml --lib test_inline_markdown
cargo nextest run --no-fail-fast --workspace --exclude command-signatures-v2 -E 'not test(/_ssh_/)'
- Passed locally: 5952 passed, 106 skipped
- SSH integration tests were excluded because they require Warp GCP SSH test infrastructure credentials.
cargo nextest run -p warp_completer --features v2
cargo test --doc

PowerShell lint was skipped locally because pwsh is not installed.

Agent Mode

Warp Agent Mode - This PR was created via Warp's AI Agent Mode

CHANGELOG-BUG-FIX: Fixed Markdown table-of-contents anchor links in rendered notebooks.

Co-Authored-By: Oz oz-agent@warp.dev

Resolve rendered Markdown fragment links inside notebook editors by matching URL fragments against Markdown heading slugs and scrolling to the target heading. Add regression coverage for normalized and duplicate heading anchors. Co-Authored-By: Oz <oz-agent@warp.dev>

cla-bot · 2026-05-05T12:17:16Z

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have the users @haikomatt on file. In order for us to review and merge your code, each contributor must visit https://cla.warp.dev to read and agree to our CLA. Once you have done so, please comment @cla-bot check to trigger another check.

oz-for-oss · 2026-05-05T12:17:26Z

@haikomatt

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR adds notebook-local resolution for rendered Markdown fragment links, including heading slug normalization, percent-decoded fragments, duplicate heading suffixes, and regression tests for the model-level anchor targeting.

Concerns

The change is user-visible click-to-scroll behavior, but the PR does not include screenshots or a video demonstrating the behavior end to end. For faster review, please upload screenshots or a video of the feature working end to end.

Verdict

Found: 0 critical, 1 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

haikomatt · 2026-05-05T12:43:03Z

@cla-bot check

For the visual/demo request from Oz:

Manual scenario verified for this change:

Render Markdown containing a table-of-contents style link and matching heading:
- [Goal](#goal)
- ## Goal
Click the rendered Goal link.
The notebook scrolls to the ## Goal heading instead of routing the fragment through external URL/file link handling.

The PR also includes regression coverage for simple anchors, normalized heading text, and duplicate headings (#goal, #goal-1).

cla-bot · 2026-05-05T12:43:08Z

The cla-bot has been summoned, and re-checked this pull request!

haikomatt · 2026-05-05T12:56:59Z

Added visual artifacts for the Markdown anchor navigation behavior requested by Oz:

Recording: https://raw.githubusercontent.com/haikomatt/warp/anchor-demo-artifacts/recording.mp4
Before screenshot: https://raw.githubusercontent.com/haikomatt/warp/anchor-demo-artifacts/before_anchor_navigation.png
After screenshot: https://raw.githubusercontent.com/haikomatt/warp/anchor-demo-artifacts/after_anchor_navigation.png
Artifact branch README: https://github.com/haikomatt/warp/tree/anchor-demo-artifacts

The recording shows a notebook with a rendered Markdown anchor link navigating to the ## Goal heading. These artifacts were generated from a temporary local-only integration recording test and are not part of the PR diff.

haikomatt · 2026-05-05T12:57:05Z

/oz-review

oz-for-oss · 2026-05-05T12:57:20Z

@haikomatt

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR adds notebook-local Markdown fragment navigation, including slug normalization, duplicate heading support, percent-decoding, and regression tests for the new anchor resolver.

Concerns

Duplicate anchor generation can collide when an earlier heading naturally uses the same suffixed slug that a later duplicate heading generates, leaving one heading unreachable.

Verdict

Found: 0 critical, 1 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

Co-Authored-By: Oz <oz-agent@warp.dev>

haikomatt · 2026-05-05T13:30:52Z

/oz-review

oz-for-oss · 2026-05-05T13:31:07Z

@haikomatt

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR routes fragment-only Markdown links in notebook editors to local heading ranges using GitHub-like slug normalization and adds regression coverage for heading matching and duplicate headings.

Concerns

Normal editable clicks on #... links are intercepted before the existing tooltip/edit flow, so users can no longer edit anchor link targets from the link tooltip.
For faster review, please upload screenshots or a video of the anchor navigation working end to end; this is a user-visible notebook behavior change and the PR does not include visual evidence.

Verdict

Found: 0 critical, 2 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

This updates the Markdown anchor navigation logic to only intercept fragment links when cmd/ctrl-clicking or when the editor is in a read-only/selectable mode. Normal clicks in editable mode now properly fall through to show the link editing tooltip. A manual test fixture for anchor links was also added. Co-Authored-By: Oz <oz-agent@warp.dev>

haikomatt · 2026-05-05T14:51:16Z

/oz-review

oz-for-oss · 2026-05-05T14:51:31Z

@haikomatt

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

The PR adds notebook-local handling for rendered Markdown fragment links and tests for simple, normalized, and duplicate anchors. I found a correctness issue in the slug algorithm: it collapses separator runs, which can route a GitHub-style anchor to the wrong heading when headings differ only by punctuation around spaces.

Concerns

GitHub-style slugs preserve separator positions after punctuation removal, but the new slugger collapses those runs, so distinct headings like A & B (#a--b) and A B (#a-b) become the same base slug and #a-b can scroll to the wrong heading.

Verdict

Found: 0 critical, 1 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

Keep whitespace-generated hyphens distinct when normalizing Markdown heading anchors so symbol-separated headings like "A & B" do not collide with space-separated headings like "A B". Add regression coverage and update the manual ToC anchor fixture for the separator-run collision case. Co-Authored-By: Oz <oz-agent@warp.dev>

haikomatt · 2026-05-05T15:17:36Z

/oz-review

oz-for-oss · 2026-05-05T15:17:50Z

@haikomatt

I'm re-reviewing this 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: @kevinyang372.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

Oz no longer requests changes for this pull request after the latest automated review.

oz-for-oss

Overview

This PR adds notebook-local Markdown fragment navigation by resolving rendered heading anchors, including normalized text, percent-encoded fragments, and duplicate-heading suffixes, with regression tests and a manual fixture.

Concerns

Fragment clicks are consumed before confirming a target exists; consider falling back to existing link handling when scrolling returns false.

Verdict

Found: 0 critical, 0 important, 1 suggestions

Approve with nits

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss · 2026-05-05T15:25:00Z

+            {
+                self.open_link = None;
+                self.model.update(ctx, |model, ctx| {
+                    model.scroll_to_markdown_anchor(&url, ctx);


💡 [SUGGESTION] Only consume anchor clicks after scroll_to_markdown_anchor succeeds; otherwise missing or malformed fragments are swallowed and never reach existing link resolution.

Co-Authored-By: Oz <oz-agent@warp.dev>

haikomatt · 2026-05-05T15:50:20Z

Addressed the latest anchor-fallback nit.

Changes:

#... clicks now only short-circuit when scroll_to_markdown_anchor returns true.
Missing or malformed fragments fall through to existing link resolution.
Added a regression test covering cmd-click on a missing fragment that resolves as a local file link.

Validation:

cargo nextest run --manifest-path Cargo.toml -p warp --no-fail-fast markdown_anchor
cargo fmt --manifest-path Cargo.toml --all -- --check
git --no-pager diff --check
cargo clippy --manifest-path Cargo.toml -p warp --all-targets --tests -- -D warnings

I did not request another Oz re-review since human review is already requested.

kevinyang372

Thanks for contributing! High-level approach makes sense

I think we could significantly simplify the code here tho

kevinyang372 · 2026-05-06T19:34:55Z

        self.content.as_ref(app).link_url_at_offset(offset)
    }

+    pub fn scroll_to_markdown_anchor(


This is semantically not an anchor -- we have a dedicated Anchor type in the core editor infra and this could confuse readers. It's really just scroll_to_matching_header

kevinyang372 · 2026-05-06T19:37:08Z

+            let heading = content
+                .text_in_range(outline.start + 1..outline.end)
+                .into_string();
+            let slug = Self::markdown_anchor_slug(&heading);


What's the purpose of these slug logic? This is not user visible so I don't think it's valueable

This really just boils down to:

Takes the url content

Iterate the list of headers until we find one with content matching the url content

kevinyang372 · 2026-05-06T19:37:56Z

+    link_url: &str,
+    ctx: &warpui::AppContext,
+) -> CharOffset {
+    let max_offset = editor.markdown(ctx).chars().count() + 10;


What is this + 10 for?

Rename scroll_to_markdown_anchor -> scroll_to_matching_header, replace slug machinery with direct case-insensitive heading comparison, tighten test bound, simplify fixture. Co-Authored-By: Oz <oz-agent@warp.dev>

kevinyang372

Nice! Thanks for contributing!

haikomatt · 2026-05-07T21:25:03Z

Thanks man, always happy to help my favourite terminal.

## Description Fixes rendered Markdown fragment links in notebook editors so links like `[Goal](#goal)` scroll to the matching Markdown heading instead of being routed through normal external URL/file link handling. This adds notebook-local anchor resolution that: - matches fragments against rendered Markdown headings - normalizes heading text into GitHub-like slugs - supports duplicate headings with `-1`, `-2`, etc. - handles percent-encoded fragments ## Linked Issue Fixes warpdotdev#10058 - [x] The linked issue is labeled `ready-to-implement`. - [x] Where appropriate, screenshots or a short video of the implementation are included below (especially for user-visible or UI changes). ## Screenshots / Videos Manual verification of rendered Markdown ToC anchor navigation using `crates/editor/test_fixtures/toc_anchor_test.md`. Before navigation, the rendered Markdown viewer shows the table of contents with fragment links: ![Rendered Markdown ToC before anchor navigation](https://raw.githubusercontent.com/haikomatt/warp/anchor-demo-artifacts/warp-fix-markdown-toc-1.png) After clicking ToC links, the viewer scrolls to the corresponding normalized and duplicate heading targets: ![Rendered Markdown ToC after anchor navigation](https://raw.githubusercontent.com/haikomatt/warp/anchor-demo-artifacts/warp-fix-markdown-toc-2.png) ## Testing Added regression coverage for: - matching a simple Markdown heading anchor - normalizing heading text before matching - duplicate heading anchors using numeric suffixes Validated locally with: - `cargo fmt -- --check` - `cargo clippy --workspace --exclude warp_completer --all-targets --tests -- -D warnings` - `cargo clippy -p warp_completer --all-targets --tests -- -D warnings` - `./script/run-clang-format.py -r --extensions 'c,h,cpp,m' ./crates/warpui/src/ ./app/src/` - `find . -name "*.wgsl" -exec wgslfmt --check {} +` - `cargo test --manifest-path app/Cargo.toml --lib test_markdown_anchor_target` - `cargo test --manifest-path app/Cargo.toml --lib test_inline_markdown` - `cargo nextest run --no-fail-fast --workspace --exclude command-signatures-v2 -E 'not test(/_ssh_/)'` - Passed locally: `5952 passed`, `106 skipped` - SSH integration tests were excluded because they require Warp GCP SSH test infrastructure credentials. - `cargo nextest run -p warp_completer --features v2` - `cargo test --doc` PowerShell lint was skipped locally because `pwsh` is not installed. ## Agent Mode - [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode CHANGELOG-BUG-FIX: Fixed Markdown table-of-contents anchor links in rendered notebooks. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>

github-actions Bot added the external-contributor Indicates that a PR has been opened by someone outside the Warp team. label May 5, 2026

oz-for-oss Bot previously requested changes May 5, 2026

View reviewed changes

cla-bot Bot added the cla-signed label May 5, 2026

oz-for-oss Bot previously requested changes May 5, 2026

View reviewed changes

Comment thread app/src/notebooks/editor/model.rs Outdated

Avoid Markdown anchor slug collisions

904f92d

Co-Authored-By: Oz <oz-agent@warp.dev>

oz-for-oss Bot previously requested changes May 5, 2026

View reviewed changes

Comment thread app/src/notebooks/editor/view.rs Outdated

oz-for-oss Bot previously requested changes May 5, 2026

View reviewed changes

Comment thread app/src/notebooks/editor/model.rs Outdated

oz-for-oss Bot reviewed May 5, 2026

View reviewed changes

oz-for-oss Bot requested a review from kevinyang372 May 5, 2026 15:25

Fall back when Markdown anchors are missing

7ea7982

Co-Authored-By: Oz <oz-agent@warp.dev>

kevinyang372 requested changes May 6, 2026

View reviewed changes

Simplify heading navigation per review feedback

81c2c23

Rename scroll_to_markdown_anchor -> scroll_to_matching_header, replace slug machinery with direct case-insensitive heading comparison, tighten test bound, simplify fixture. Co-Authored-By: Oz <oz-agent@warp.dev>

kevinyang372 approved these changes May 7, 2026

View reviewed changes

kevinyang372 enabled auto-merge (squash) May 7, 2026 18:21

kevinyang372 merged commit 606e165 into warpdotdev:master May 7, 2026
23 checks passed

timomak mentioned this pull request May 10, 2026

[twarp upstream] docs-readme timomak/twarp#27

Merged

1 task

Uh oh!

Conversation

haikomatt commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Linked Issue

Screenshots / Videos

Testing

Agent Mode

Uh oh!

cla-bot Bot commented May 5, 2026

Uh oh!

oz-for-oss Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

haikomatt commented May 5, 2026

Uh oh!

cla-bot Bot commented May 5, 2026

Uh oh!

haikomatt commented May 5, 2026

Uh oh!

haikomatt commented May 5, 2026

Uh oh!

oz-for-oss Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

Uh oh!

haikomatt commented May 5, 2026

Uh oh!

oz-for-oss Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

Uh oh!

haikomatt commented May 5, 2026

Uh oh!

oz-for-oss Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

Uh oh!

haikomatt commented May 5, 2026

Uh oh!

oz-for-oss Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

oz-for-oss Bot May 5, 2026

Choose a reason for hiding this comment

Uh oh!

haikomatt commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

haikomatt commented May 5, 2026 •

edited

Loading

oz-for-oss Bot commented May 5, 2026 •

edited

Loading

oz-for-oss Bot commented May 5, 2026 •

edited

Loading

oz-for-oss Bot commented May 5, 2026 •

edited

Loading

oz-for-oss Bot commented May 5, 2026 •

edited

Loading

oz-for-oss Bot commented May 5, 2026 •

edited

Loading

haikomatt commented May 5, 2026 •

edited

Loading