Prohlížeč zdrojového kódu

# Spec: Source Browser — Markdown Links

- **Status:** active
- **Created:** 2026-03-05
- **Related code:** `app/helpers/highlight_helper.rb`, `app/views/source/show.html.erb`

## Overview

Markdown files displayed in the Source Browser may contain links to other files accessible through the Source Browser. These links should behave like navigating the file tree — updating the URL, pushing a browser history entry, and syncing the active file in the tree — rather than silently replacing only the content frame.

## Behaviour

- When a Markdown file is viewed in formatted (`:formatted`) mode, links whose `href` points to a `/source/` path cause full-page Turbo Drive navigation when clicked.
- After clicking such a link: the URL updates to the target file's source path, a browser history entry is pushed, and the source tree syncs to mark the target file as active.
- Links to external URLs (http/https) are unaffected.
- This behaviour applies only in formatted view; in source view (syntax-highlighted), there are no clickable links.

## Implementation Notes

- **Root cause:** The content area was wrapped in `<turbo-frame id="source-content">`. Links clicked inside a turbo-frame are intercepted by Turbo and navigate within the frame only — no URL update, no history entry, no `turbo:load` event (so `syncActive` never fires). Removing the frame and using a plain `<div id="source-content">` makes all links trigger full Turbo Drive page navigation naturally, without needing `data-turbo-frame` attributes on individual links.

- **Path rewriting:** `SourceAwareMarkdownRenderer` (a `Redcarpet::Render::HTML` subclass in `app/helpers/highlight_helper.rb`) overrides `link`. For non-external links that aren't already `/source/` paths, it resolves the href relative to the current file's directory (`@base_dir`, set at construction time), then checks `SourceBrowser.file?` to confirm the path is whitelisted. If so, it rewrites to `/source/<path>/`. This lets Markdown files use locally valid relative paths (e.g. `docs/specs/source-browser.md`) that work in any Markdown previewer and are automatically rewritten when served through the Source Browser.

- `render_markdown` now accepts a `base_path:` keyword argument, forwarded to the renderer. The view passes `base_path: @path`.

- Calling `super` in Redcarpet HTML renderer overrides is not possible (the parent `link` method is a C extension). The overridden method must always build the `<a>` tag itself.

## Tests

- `spec/system/source_browser_spec.rb` — clicking a `/source/` link in a rendered Markdown file navigates the full page (URL updates, tree active state updates)

## See Also

- [Source Browser](source-browser.md) — the core browser whose Markdown rendering this feature extends.
- [Source Browser — Claude Workflow Files](source-browser-claude.md) — the spec and command files whose relative links are rewritten by this feature.

## Change Log

- 2026-03-05: Spec created, prospective workflow.