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 — the core browser whose Markdown rendering this feature extends.
• Source Browser — Claude Workflow Files — the spec and command files whose relative links are rewritten by this feature.

Change Log

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