gabriel / musehub public
deep-link-issue-headers.md markdown
84 lines 3.0 KB
Raw
sha256:1dd27e6d5c24550177b01b0a171e8375c07cf046b549e7683364706b6522d3bc docs(#139): mark all 11 checklist items resolved, document … Sonnet 5 12 days ago

Deep-link anchors for issue and proposal headings

Background

MuseHub already renders anchor links on hover for headings in README files and mists: when you hover over a heading, an octothorpe (#) appears to the right. Clicking it updates the browser URL bar to #section-slug and produces a shareable deep-link into that specific section.

Issue and proposal bodies are rendered Markdown and support the same heading syntax, but the hover anchor behaviour is absent. This creates an inconsistency: the same ## Background heading in a README gets a deep-link, but the same heading inside an issue body does not.

For long implementation plans (phased issues, design docs, ADRs) the inability to link directly to a phase or section forces authors to add workarounds like HTML anchor tags or redundant section references.

Goal

When viewing any issue or proposal on MuseHub, hovering over a rendered Markdown heading causes an octothorpe to appear. Clicking the octothorpe:

  1. Updates the browser URL bar to append #<slug> (e.g. #background, #phase-2).
  2. Scrolls the page to that heading.
  3. The resulting URL is a shareable deep-link that, when opened, scrolls directly to the heading.

The behaviour and slug generation must be identical to the existing README and mist implementation so that cross-document links work predictably.

Design

Slug generation

Follow the existing rule (already used for READMEs and mists):

  1. Lowercase the heading text.
  2. Replace spaces with hyphens.
  3. Strip characters that are not alphanumeric, hyphens, or underscores.
  4. Deduplicate: if the same slug appears more than once in the document, append -2, -3, etc.

Examples:

## Background            → #background
## Phase 2 — CLI         → #phase-2--cli
## `muse tag add`        → #muse-tag-add

URL shape

The anchor should be appended to the canonical issue or proposal URL:

https://staging.musehub.ai/gabriel/muse/issues/56#phase-2--cli

Navigating to this URL must scroll the rendered body to the matching heading without a full page reload.

Hover UX

Match the existing README and mist behaviour exactly:

  • Octothorpe appears to the right of the heading text on hover.
  • Cursor changes to pointer when hovering the octothorpe.
  • Clicking copies/sets the anchor URL (same as GitHub behaviour).

Deliverables

  • [ ] Anchor slug generation applied to issue and proposal rendered Markdown — same algorithm as README/mist renderer.
  • [ ] Hover octothorpe rendered for h1h4 headings in issue and proposal bodies.
  • [ ] Clicking the octothorpe updates window.location.hash and the browser URL bar.
  • [ ] Direct navigation to a #slug URL scrolls to and highlights the target heading.
  • [ ] Slug deduplication: repeated headings get -2, -3 suffixes.
  • [ ] Regression test: existing README and mist anchor behaviour unchanged.

Out of scope

  • Table of contents auto-generation — separate feature.
  • Anchor links in comments — can follow in a later issue.
  • Cross-issue deep links (#56#background) — deferred.
File History 2 commits
sha256:1dd27e6d5c24550177b01b0a171e8375c07cf046b549e7683364706b6522d3bc docs(#139): mark all 11 checklist items resolved, document … Sonnet 5 12 days ago
sha256:649011bedd713e22f7dca4c4be94bdefbf3b10950d9fc80235928d0b0b823be8 docs: track issue #139 (two-column app-shell refactor) plan… Sonnet 5 12 days ago