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:
- Updates the browser URL bar to append
#<slug>(e.g.#background,#phase-2). - Scrolls the page to that heading.
- 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):
- Lowercase the heading text.
- Replace spaces with hyphens.
- Strip characters that are not alphanumeric, hyphens, or underscores.
- 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
pointerwhen 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
h1–h4headings in issue and proposal bodies. - [ ] Clicking the octothorpe updates
window.location.hashand the browser URL bar. - [ ] Direct navigation to a
#slugURL scrolls to and highlights the target heading. - [ ] Slug deduplication: repeated headings get
-2,-3suffixes. - [ ] 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.