TrailMark

Markdown Browser + Mermaid for VS Code.

Open docs in real preview tabs, follow links without losing your place, use back and forward history, zoom like a browser, and render Mermaid without depending on the built-in Markdown preview pipeline.

TrailMark is a Markdown browser for documentation-heavy workflows: specs, RFCs, runbooks, architecture notes, research docs, and knowledge bases that span multiple files and deep heading structures. Instead of treating Markdown like a one-off render, TrailMark treats it like a browsing surface, with built-in Mermaid support as part of the same reading flow.

Why People Install TrailMark

The built-in Markdown preview is excellent when you want to check how a single file renders.

TrailMark is for the next step:

• keeping multiple Markdown previews open at the same time
• following doc-to-doc links without losing reading context
• using back and forward across both files and heading jumps
• returning to the exact scroll position you left behind
• navigating long documents from a real sections tree
• reading Mermaid-heavy and code-heavy docs with anchored zoom

What Makes TrailMark Different

Most Markdown preview extensions focus mainly on rendering or visual styling.

TrailMark focuses on navigation and reading flow:

• preview tabs behave more like browser tabs than static panels
• zoom stays anchored to the content under your cursor
• Mermaid support is built in, so diagrams render inside TrailMark itself
• files and sections share one navigator built for long-form docs
• history, scroll restoration, and toolbar interactions are designed to preserve context

Highlights

Best For

• engineering docs that link across many Markdown files
• architecture and system design notes with Mermaid diagrams
• long reports where section jumping matters
• code-heavy documentation where zoom and syntax highlighting help
• people who want documentation browsing to feel closer to a docs site or browser tab

Core Features

• dedicated preview tabs for Markdown files
• open Markdown links in the same tab, a new tab, or through history
• mouse back and forward button support inside the preview
• sticky browser-style toolbar with navigation, source jump, zoom, and layout controls
• shared document navigator for sections, files, and links with filtering
• link review mode for outgoing links, missing files/headings, and backlinks
• section links that handle formatted heading text, raw HTML anchors, percent-encoded hashes, query-string links, duplicate headings, and workspace-root-relative paths
• tree-based outline with hover peek and live section tracking
• focused view for code blocks, Mermaid diagrams, images, and tables using the normal toolbar and zoom without changing navigation history
• optional local web server for browser-based workspace viewing with login protection
• built-in Mermaid support for fenced blocks and ::: mermaid
• syntax highlighting for fenced code blocks
• theme-aware presentation for light, dark, and high-contrast themes

Keyboard Shortcuts

You can override any TrailMark shortcut in VS Code’s Keyboard Shortcuts (Ctrl/Cmd+K, then Ctrl/Cmd+S) or by editing keybindings.json.

Mermaid Support

TrailMark renders Mermaid directly inside its own preview surface, so diagrams work as part of the extension rather than through the built-in preview.

Supported examples:

```mermaid
flowchart LR
  A --> B
```

::: mermaid
flowchart LR
  A --> B
:::

Layout Modes

Use the toolbar or markdownBrowserPreview.layoutMode:

• readable: a centered reading surface for long-form docs
• fullWidth: an edge-to-edge document surface for wide or dense content

Theme Modes

Use the toolbar theme button or markdownBrowserPreview.themeMode:

• native: follow VS Code's active theme
• light: use TrailMark's light theme
• dark: use TrailMark's dark theme

Toolbar changes for layout and theme are saved to your VS Code User settings so they do not modify workspace files. Workspace settings can still override these preferences when you intentionally configure them for a project.

Heading and Link Compatibility

TrailMark generates section anchors from the visible rendered heading text, including headings that contain inline links, images, code, entities, or raw HTML. Hash navigation also recognizes explicit raw HTML id targets, <a name="..."> anchors, percent-encoded fragments, duplicate generated headings, query-string Markdown links, and workspace-root-relative Markdown or image paths.

Optional Web Server

TrailMark can expose the current workspace through a lightweight local web server for browser-based viewing. The feature is available by default, but the server stays off until you explicitly start it with the server button in the TrailMark toolbar. Set markdownBrowserPreview.server.enabled to false to hide the server control and prevent the server from starting.

By default the server binds to 127.0.0.1, chooses an available port, and shows a login page. When markdownBrowserPreview.server.port is 0, TrailMark remembers the last successful auto-assigned port for the workspace and tries it first before asking the OS for a new one. The default credentials are configured through VS Code settings; change them before exposing the server beyond your machine. Browser URLs use server-issued document IDs rather than absolute local file paths, and the server only serves files inside TrailMark's allowed workspace roots.

For intentional LAN or remote access, set markdownBrowserPreview.server.host to 0.0.0.0 and keep markdownBrowserPreview.server.requireLogin enabled.

Settings

TrailMark now exposes its main behavior through VS Code's normal Settings UI.

To open it:

1. Open VS Code Settings with Ctrl+, or Cmd+,.
2. Search for TrailMark.

Useful settings to know:

• markdownBrowserPreview.layoutMode
• markdownBrowserPreview.themeMode
• markdownBrowserPreview.files.respectVSCodeExcludes
• markdownBrowserPreview.files.excludeGlobs
• markdownBrowserPreview.files.includeCurrentDocument
• markdownBrowserPreview.files.maxResults
• markdownBrowserPreview.server.enabled
• markdownBrowserPreview.server.host
• markdownBrowserPreview.server.port
• markdownBrowserPreview.server.requireLogin
• markdownBrowserPreview.server.username
• markdownBrowserPreview.server.password

The Files navigator is workspace-focused by default: it excludes dependency and VCS folders out of the box, can respect your VS Code exclude settings, and still keeps the current Markdown document visible when you open a file outside the normal repo listing.

Notes

• TrailMark is intentionally plain JavaScript, which keeps it easy to inspect and extend.
• Local images referenced from Markdown are rewritten into webview-safe URIs.
• The preview refreshes when the underlying Markdown document changes.
• Web server E2E coverage is available with npm run test:e2e, including a headless Chromium browser pass.
• Development fixtures live in test-fixtures/ and are excluded from the packaged .vsix.

License

TrailMark is proprietary software.

The current release is available free of charge under the terms in LICENSE.txt. That license allows use of TrailMark, but it does not make TrailMark open source and does not permit redistribution, relicensing, or derivative works.

Future versions or premium features may be offered under trial, subscription, or other commercial terms.