← md-viewer Open the viewer
001   md-viewer · how it works grid

How a Markdown file becomes a split view

One file, one pipeline, zero servers. The same base64-injected, self-contained HTML powers both the macOS Finder Quick Action and this web app — rendered document on the left, syntax-highlighted source on the right.

Nothing is uploaded. Everything locally rendered.

01

Two ways in, one engine

Finder Quick Action macOS

Right-click any .md in Finder — no app to launch.

  • 1Right-click → Quick Actions → View Markdown
  • 2Automator service runs mdview "$file"
  • 3Bash generates a temp HTML and opens it

Web app browser

Drop, paste, or open a file right here. Fully client-side.

  • 1Drag & drop · paste (⌘V) · file picker
  • 2Repo README renders by default
  • 3Nothing is uploaded — it all runs in your browser
02

The rendering pipeline

Source
Markdown file (.md)
Any bytes — Unicode, emoji, embedded HTML.
↓
Encode
base64 the content + filename
Turns the file into a single safe line — no character can break the HTML or JS it's injected into.
↓
Inject
Substitute into the self-contained template
One HTML file with every CSS/JS library already inlined. No network needed from here on.
↓
Browser
Decode base64 → UTF-8 text
Then two renderers run over the same text, in parallel:
↓
Left · Rendered
Pretty document
marked→DOMPurify→innerHTML
Markdown → HTML, then sanitized so a downloaded file's scripts can't run.
Right · Source
Highlighted source
highlight.js→markdown grammar
The raw text stays verbatim — colour-coded so headings, bullets and code are visible in the source too.
↓
Result
Split view · scroll-synced · resizable & collapsible
Read the formatted version and the source at once. Drag the divider to rebalance — or to an edge to collapse a pane; double-click resets to 50/50. On a phone, a [Rendered | Raw] tab gives each pane the full screen.
03

What makes it hold together

Self-contained & offline

Fonts, CSS and every JS library are inlined into one HTML file. It works with no internet, no npm, no runtime dependencies.

Safe by construction

base64 sidesteps every HTML-escaping bug; DOMPurify strips scripts and event handlers from the rendered side.

Token-driven themes

[data-theme] × [data-mode] drive Minimalist and Swiss Grid, each in light and dark — all from CSS custom properties.

No build chain

A pure Bash generator assembles both outputs. The whole thing is text in, text out — reviewable and diff-able.

Resize, collapse, or tab

Drag the divider to rebalance the panes — or to an edge to collapse one (it glows red, so you can grab it back). Double-click resets to 50/50, and it's fully keyboard-operable. On a phone, a [Rendered | Raw] tab gives each pane the whole screen.

Reads without JavaScript

The intro is pre-rendered into the page at build time — jsdom running the same marked + DOMPurify — so search engines and AI assistants see the content with scripts off. For you it renders identically, just a touch faster.

04

Fastest access from Finder

md-viewer is a Quick Action, not an app — double-click / Enter opens your default editor (TextEdit / VS Code), not the viewer. Use one of these, fastest first:

1 Keyboard shortcut recommended

Select the .md → press the shortcut → open. One keystroke. Set it up once: System Settings → Keyboard → Keyboard Shortcuts… → Services → “Files and Folders” → View Markdown → assign e.g. ⌃⌘M.

2 Finder preview pane

Show the preview pane (⌘⇧P), select the file → the Quick Action buttons appear at the bottom → click View Markdown. No submenus.

3 Right-click

Right-click the .md → Quick Actions → View Markdown. Solid, but one submenu deep.