A local, offline, read-only Markdown viewer for macOS. MDViewer opens .md and
.markdown files in native windows, renders with bundled JavaScript inside
system WebKit, and refreshes the preview when the source changes. It is not an
editor, browser service, or Node runtime; no Pi process is needed to use it.
Project page: https://guneriu.github.io/mdviewer/ (source in site/,
deployed by .github/workflows/pages.yml on pushes to main).
Status: local build and automated verification evidence is available, but this
is not a notarized or fully accepted release. Automatic refresh for documents
directly inside /tmp (a symlink parent) was fixed on 2026-10-30. See
limitations and the
historical acceptance results for unresolved checks.
Prerequisites: macOS 13+ (macOS 14+ to run the tests), a Swift 6 toolchain
(xcode-select --install is enough; full Xcode is optional), Python 3, and the
standard codesign/plutil tools. You need Node 22+ only to regenerate renderer
assets.
git clone https://github.com/guneriu/mdviewer.git && cd mdviewer
CONFIGURATION=release bash scripts/package.sh # → .build/release-package/MDViewer.app
bash scripts/test-swift.sh # optional: native unit tests
bash scripts/install.sh --dry-run # shows what would be installed
bash scripts/install.sh --install # copies to ~/Applications/MDViewer.app
open -a ~/Applications/MDViewer.app README.md # first launchTo make it the default viewer, select a .md file in Finder → Get Info →
Open with → MDViewer → Change All. Updating uses --install --replace after
quitting the app. To check which build you're running, choose MDViewer → About
MDViewer; it shows the version from Packaging/Info.plist and the credits line (bump
CFBundleShortVersionString/CFBundleVersion there for each release). The sections
below explain each step, its safety guards, and how to uninstall.
To see every supported feature at once, open
examples/showcase/showcase.md. It doubles as a manual
test checklist; see examples/README.md.
- Headings, paragraphs, emphasis, links, ordered/unordered lists, blockquotes, horizontal rules, fenced/inline code, tables, strikethrough, and disabled, accessible task checkboxes. Raw HTML is displayed as text, not executed.
- Explicit syntax highlighting for JavaScript, TypeScript, JSON, CSS, XML/HTML, Bash, Python, and Swift, including registered aliases. There is no language autodetection. Unknown languages and Mermaid remain escaped plain code; Mermaid diagrams and math are not rendered.
- Relative PNG, JPEG, GIF, and WebP images within the canonical document directory
or its descendants. Missing or blocked images show a placeholder; parser-rejected
image syntax stays literal. Remote, SVG, data, absolute-file,
../assets/, and symlink-escape images are blocked. - Stable Unicode heading fragments, with
-2,-3, etc. for duplicates. Exact IDs take precedence over NFC/case-normalized fallback. For example,#日本-語targets “日本 語”.
Same-document links stay local. Explicit local Markdown links open through the native document coordinator, even outside the image root. Explicit HTTP, HTTPS, and mailto links use the default system application. Other local files require confirmation to reveal in Finder, not execute. Unsafe schemes and executable targets are blocked; the embedded view does not navigate away.
There is one window per canonical file. Sources are read-only UTF-8 (BOM accepted), with a 10 MiB cap, an empty-document state, and readable input errors. MDViewer does not save Markdown, execute code blocks, export documents, accept drag-and-drop, provide tabs or session restore, or aim for exact GitHub rendering parity.
- macOS with a Swift toolchain and SDK capable of building the project, plus Python 3 for bundled-asset verification and the standard macOS signing tools.
- Historical local validation used Apple Silicon, macOS 26.7.1, Swift 6.4 and Command Line Tools SDK 27 without full Xcode. The compiled deployment target is macOS 13, not a runtime-tested compatibility guarantee. The test framework requires macOS 14. Other toolchains, OS versions, and architectures need their own validation.
- Node 22.23.4+, 24.22.1+ or 26.12.1+ (patched for CVE-2026-111497; Node 23, 25 and older lines are end-of-life) and npm are needed only to regenerate renderer assets. Normal app packaging uses the existing vendored assets, not npm or network downloads.
From the project directory:
bash scripts/package.sh
# Debug app: .build/MDViewer.app
CONFIGURATION=release bash scripts/package.sh
# Release app: .build/release-package/MDViewer.app
PYTHONDONTWRITEBYTECODE=1 python3 scripts/verify_assets.py --bundle .build/release-package/MDViewer.app
bash scripts/install.sh --dry-runPackaging verifies asset hashes, sizes, allowlists and notices, builds with SwiftPM's
--build-system swiftbuild, copies the app, lints metadata, and ad-hoc signs and
verifies the host-architecture bundle. It overwrites generated outputs and
does not refuse to package while an older app is running. Quit MDViewer before
rebuilding a bundle you use, then deliberately reopen the intended bundle afterward.
Changing an executable on disk does not replace the live process image.
Packaging does not launch or install the app, explicitly register handlers, change default preferences, remove quarantine, or weaken Gatekeeper. Ad-hoc signing is not Developer ID signing or notarization; no universal binary is promised. See the packaging guide for inputs, outputs, and verification details.
Copying or launching a document-type app can affect macOS app discovery and
default resolution even without an explicit default-setting call. The app's
LSHandlerRank=Alternate is not a guarantee against this. Historical launch testing
observed MDViewer as an effective handler without a captured before-state; the
prior default and causality were not established. Review the
Launch Services caveat
before opting into actual-app testing.
To deliberately launch a locally built release and open a document, choose its bundle in Finder or run the following separately from building:
open -a "$PWD/.build/release-package/MDViewer.app" "/absolute/path/to/report.md"The absolute document path is an example; choose your own file. This is an actual app launch, not an inspection check. Select the intended bundle explicitly when multiple build or installed copies exist.
Optional installation and default-handler selection are separate user decisions:
- Build and verify a release, then inspect
bash scripts/install.sh --dry-run. When ready to copy it, runbash scripts/install.sh --install. The installer targets only~/Applications/MDViewer.app, refuses symlink destinations and a running MDViewer, verifies the staged copy, and does not launch it. No arguments fail closed. Its mutating install/update/rollback paths still require acceptance testing; guard and dry-run checks alone do not prove them. - Launch the installed copy deliberately. To make it the default, select an
.mdfile in Finder → Get Info → Open with → MDViewer → Change All. Repeat for.markdownonly if desired. Neither building nor installation explicitly sets these defaults. - An existing system/external-open action, including pi-files' action, can then route Markdown to the selected viewer. MDViewer has no pi-files source or configuration dependency. Actual pi-files integration remains a manual acceptance check, not a verified feature claim about that external tool.
With MDViewer set as the default for .md (step 2 above), open routes to it:
open README.md # one file
open notes.md todo.md # several files, one window eachTo view in MDViewer while another app (an editor, for example) stays the default,
target it by bundle identifier. Optionally add a shell alias, for example in ~/.zshrc:
open -b de.local.mdviewer README.md
alias mdv='open -b de.local.mdviewer' # then: mdv README.md-b picks the registered MDViewer copy by bundle identifier, so it doesn't depend on
the install path. If several copies exist (a build plus the installed app), pass the
bundle explicitly with open -a ~/Applications/MDViewer.app README.md.
- Update: quit MDViewer, rebuild and verify the release, then explicitly run
bash scripts/install.sh --install --replace. Existing destinations require--replace; the installer never terminates the app for you. It stages/verifies the replacement and attempts rollback on a final-move failure, retaining the previous bundle for recovery if rollback fails. Reopen the intended installed bundle afterward, not an older build or already-running process. - Restore a preferred default: Finder → Get Info → Open with → Sublime Text (or another chosen app) → Change All, separately for each chosen extension. If macOS retains a stale path, choose Other…, select the intended current bundle, reopen a source, and verify. No blanket association reset is provided.
- Uninstall: quit MDViewer, restore a preferred default first, then move only
~/Applications/MDViewer.appto Trash in Finder. Source documents are not part of the app and should not be removed. Generated.build/outputs can be removed separately. Real install/update/uninstall and association preservation remain manual acceptance work.
| Shortcut | Action |
|---|---|
| Cmd-O | Open a document |
| Cmd-R | Reload source and local raster images |
| Cmd-F | Show native find controls |
| Cmd-Shift-F | Toggle View → Follow Changes |
| Cmd-+ or Cmd-= | Zoom in |
| Cmd-- | Zoom out |
| Cmd-0 | Reset zoom |
| Cmd-W | Close the document window |
| Cmd-Q | Quit MDViewer |
Text is selectable and can be copied. Styling follows system light/dark mode; wide tables and code scroll horizontally. Path, status and search controls have accessibility labels. Human keyboard, copy, layout and VoiceOver acceptance is still pending despite automated find/zoom/selection coverage.
The app watches the canonical file and parent directory, debounces changes by about 200 ms, and retries transient failures. It keeps the last good preview with a stale warning when reads/renders fail and can recover after recreation. Generation guards prevent older work from replacing a newer preview. Observed sub-second updates are dated local-disk measurements, not guarantees on all volumes.
Refresh keeps the visible content anchored, even when blocks above it change. If the visible block was deleted, a surviving preceding block is used, or the scroll position is clamped to the new document bounds. Enable View → Follow Changes (⌘⇧F) to jump to and briefly highlight an off-screen changed block. It is off by default; the setting is remembered application-wide and applies to existing and new viewer windows. The brief highlight respects Reduce Motion. First render, explicit heading navigation, find and zoom keep their usual behavior.
Referenced local images refresh automatically; Cmd-R still forces a reload. Contained image overwrite, replacement, deletion and creation update the preview without editing Markdown. Watching is bounded to 256 existing regular-file paths and 256 missing paths from the last successful render. Unreferenced or outside file changes do not trigger image refresh, including during rendering. Ancestor-directory changes, lost/root filesystem events or more than 512 distinct event paths during a render conservatively reload. If image watching cannot start, Reload remains available.
A valid partly written or empty file may briefly display after settling; debounce cannot infer an external writer's intent. An existing session follows its original canonical target: reopen after retargeting a symlink. Replacement of the document's root directory is not automatically rebound (replacing a child image directory is supported).
- Unexpected behavior after a rebuild or replacement: quit all MDViewer copies, then reopen the intended bundle explicitly. An on-disk executable and a running image can differ. A previous refresh incident recovered after reopening, but its exact old internal failure was not established; it is not proof of a source bug.
- No automatic refresh in a symlinked parent directory: fixed for
/tmp(and analogous/var,/etcparents) on 2026-10-30. The parent watcher now resolves the physical directory withrealpathwhile keepingO_NOFOLLOWfor the final component. See the blocker plan. If an older build still misbehaves, rebuild, reinstall, or press Cmd-R. - Image placeholder: check the format, document-relative containment and resource budgets below. Broader directories and remote images have no opt-in.
- Stale warning: check existence, permissions, encoding and size, then retry with Cmd-R. A slow or stalled volume can delay all windows' queued reads.
- Content-process failure: recovery retries the shell/preview at most twice, then asks for Cmd-R. Coverage uses delegate injection, not a real OS process kill.
Markdown is untrusted input. Defense in depth includes raw HTML off, HTML-only DOMPurify string output with named-property isolation, exact native resource capabilities, bundle allowlists, CSP, deny-network content rules, and an ephemeral WebKit data store. No document text is logged or intentionally persisted in web storage. Production request diagnostics are off.
The native host is intentionally not App Sandbox-enabled. It has the user's ordinary filesystem permissions; containment is application-enforced, not an OS sandbox guarantee. There is no server, CDN, analytics, automatic updater, or runtime dependency download. Explicit safe link clicks can open external applications.
Image work is bounded to 25 MiB/file, 64 MiB bytes/batch, 256 unique file reads, 2,048 references, 16,384 px/axis, 16 MP/image, 64 MP/batch, and 32 frames/image. Descriptor type, size and containment checks precede capped reads; NUL and nonregular sources are rejected. Device/inode aliases share bytes/capabilities; rejected reads consume work budgets. Parsing/highlighting remain synchronous in WebKit; these bounds are not a general CPU/process-memory guarantee. Previously authorized decoded image memory can survive capability retirement.
All windows share a serial DocumentIO actor. Byte-capped synchronous reads run
off the main thread but cannot be interrupted mid-read; cancellation is checked
around them. Slow/stalled I/O can cause head-of-line blocking. Nonblocking/no-follow
watcher opens reject FIFOs and nonregular targets but do not bound metadata latency.
CSP tests and node-free builds are not disconnected-network or packet-level proof. True offline testing, online packet observation, older-macOS runtime, real WebKit process termination, human UI and full-app integration checks remain pending. See TEST_RESULTS.md for dated counts and the acceptance matrix; no historical count represents a fresh test run by this documentation cleanup.
Architecture explains modules, data flow and security boundaries; AGENTS.md holds contributor and coding-agent rules. The Development and evidence index covers check entrypoints, renderer regeneration and historical engineering records. The project keeps separate:
Package.swift: native Swift targets;Sources/andTests/contain native code.- Private
package.json/package-lock.json: development-only renderer tooling. web/: renderer inputs;Resources/: vendored runtime assets and full notices.Packaging/: bundle metadata inputs and the packaging guide..build/: generated apps and local evidence, not source to publish.
The specification and implementation plan retain the original contract; test results track implementation evidence and remaining gates. Keep dependency pins and asset/notices hashes together when changing the renderer. Do not equate packaging success with manual acceptance.
MDViewer's own code and authored documentation are licensed under the MIT License, copyright 2026 MDViewer contributors. Bundled dependencies retain their own terms: see THIRD_PARTY_NOTICES.md and Resources/Notices/. The project license does not replace or relicense those upstream texts.