The desktop application wraps Markdown Viewer in Neutralinojs for users who want a lightweight local Markdown Editor and viewer window. It uses the same Editor, Preview, renderer, sharing, and export code as the web application, with native file dialogs and local desktop storage.
- Runs in a Neutralinojs desktop window.
- Uses the Markdown Viewer artwork for the desktop window and packaged Windows executable instead of the default Neutralino icon.
- Uses native open/save dialogs for Markdown and HTML.
- Can read a Markdown file path passed as a launch argument.
- Asks for confirmation before closing.
- Keeps small interface preferences in system-scoped Neutralino storage and documents in the durable Markdown Viewer Vault.
- Uses a restricted native API allowlist.
- Prepared builds load renderer libraries from local
/libs/...files instead of CDNs. - The default configuration does not expose
os.execCommand; Markdown preview cannot execute local shell commands through the standard desktop build.
Network features remain network features: managed media upload, GitHub import, stored Share Snapshot, Live Share, remote diagram rendering, external images, and external links can still contact remote services.
PlantUML and D2 contain an optional local-command code path, but it requires os.execCommand plus explicit opt-in. Because the default native allowlist omits that API, the standard desktop build uses the remote PlantUML/Kroki paths.
Linked Workspace keeps references to external Markdown files separate from independent Workspace (Vault) documents. Use the Explorer toolbar or Linked Workspace context menu and choose Link file or Link folder to link existing files/folders. The header's plus menu stays the same as the web app: New document, From files, and From GitHub. Workspace and folder icons turn blue when expanded, independently of the active document. Linking the same normalized source path reuses its existing document. Folder linking includes nested Markdown files.
Right-click a linked folder or subfolder to group existing links inside it. This sidebar organization does not move originals or change filesystem scan roots. Independently grouped links remain available if their parent source folder is removed or converted.
- Edits autosave recovery drafts under the separate Linked Workspace storage root, mirroring linked-folder subdirectories. They do not automatically overwrite originals.
- Save / Ctrl+S writes the selected linked original after preserving and verifying its recovery draft, without an ordinary confirmation prompt. Conflict/missing-source decisions remain explicit.
- Save As… creates a separate external file/link. Save As linked file… on a Vault
document keeps its Vault copy and activates the new link. Dialogs suggest the document
title and append
.mdwhen no extension is supplied. Ctrl+S recognizes keyboard layouts; Ctrl+Shift+S keeps its existing scroll-sync action. - Convert to Workspace copy preserves the current draft as an independent Vault document without changing its original. Files and linked-folder subtrees can also be dragged into the Vault using ordinary internal HTML dragging. Reverse linking by internal dragging is not supported.
- Folder conversion retains the source hierarchy. Save As linked folder… exports a Vault folder to a new external directory, preserves Vault documents and links the result.
- Removing linked files/folders removes application references, not originals. Automatic scans respect removed links; explicit Rescan or re-linking the same folder restores them. Removal and conversion exclusions apply to every covering linked root, including separately linked parent and child folders.
- External changes refresh unmodified drafts. Conflicts, missing sources and incomplete scans retain drafts and show distinct hover indicators rather than repeated alerts. Reload, overwrite and recreation decisions use application confirmations.
- A built-in editable quick-start guide opens in Split view and explains these workflows
with a step-by-step diagram, quick-start instructions, and action tables. Both welcome guides use
the
book-openicon; guide identity comes from metadata, not an arbitrary document's title. - Workspace backups include normal and linked recovery documents. Imported backups recover drafts but do not reconnect external paths or authorize writes to originals.
- Linked documents cannot move directly into Secret Workspace. Convert to a Vault copy first. Moving a Vault document into Secret saves its encrypted record before removing the active plaintext copy and its automatic history; a failed cleanup reports a failed move.
External HTML drops continue importing Vault copies. Native-path drop choice and single-instance handling are separate runtime-dependent proposals, not enabled by this workflow. Browser/Docker use hides native linking, filesystem and Save As linked controls; recovered documents remain ordinary usable drafts without external write authority.
Folder scans are bounded (20 MiB per Markdown source, 200 MiB staged content, 40,000 entries, 10,000 Markdown files, 2,000 directories and 32 directory levels, with a 60-second scan budget). A failed scan retains its previous drafts. Save/conversion/export operations verify recoverable data and report partial failures, but filesystem writes are not atomic transactions and cannot eliminate every race with another process. Keep independent backups of important originals.
The application integration uses standard desktop filesystem APIs. Release CI installs and launches the actual packages on Ubuntu 22.04/24.04 and Intel/Apple Silicon macOS 15/26, imports a Unicode-named Markdown file, verifies its bytes in the real Vault, and reopens the application. Older macOS/WebKit combinations and ARM Linux packages still need representative hardware acceptance.
desktop-app/
neutralino.config.json
package.json
setup-binaries.js
prepare.js
resources/
index.html
styles.css
js/
main.js
script.js
preview-worker.js
neutralino.js
libs/
assets/
prepare.js recreates the resource files from the root web app. Do not hand-edit generated resource copies unless you plan to rerun preparation.
cd desktop-app
npm install
npm run devnpm run dev runs setup first, then starts the Neutralino app through npx -y @neutralinojs/neu@11.7.0 run. Setup downloads the binaries and runs prepare.js.
npm run buildThe default developer build generates seven raw executables under
desktop-app/dist/markdown-viewer/, each with embedded resources. Releases add
platform installers: a macOS .dmg containing Markdown Viewer.app, Ubuntu/Debian
.deb packages with system dependencies and a menu launcher, and portable Linux
.tar.gz archives preserving permissions. Windows keeps the existing .exe.
Mac runtimes are rebuilt at their native dependency baselines: Intel 10.15 and
Apple Silicon 11. The upstream 6.5.0 binaries require 14.0.
See installer build and signing instructions.
The v3.10.6 publication gate requires the exact Windows, Mac, and Linux asset set,
rejects empty or unexpected files, writes SHA256SUMS.txt, verifies every checksum,
and republishes the already-tested assembly without rebuilding it. Native package
metadata identifies the product, publisher, license, website, support links, icon,
and stable application id; operating-system trust and store warnings remain separate.
The shared web/desktop application code includes slash commands, natural Explorer sorting, middle-click tab closing, pane-scoped Select All, rich Preview copying, smooth Page Up/Down navigation, and native fullscreen or Expanded view fallback behavior.
Important neutralino.config.json values:
| Setting | Current Value |
|---|---|
| Application id | com.markdownviewer.desktop |
| Document root | /resources/ |
| Default mode | window |
| Window size | 1280 x 720 |
| Minimum size | 400 x 200 |
| Native API | Enabled |
| Token security | One-time |
| Logging | Disabled |
Allowed native APIs:
app.exitos.showOpenDialogos.showSaveDialogos.showMessageBoxos.openos.setTrayfilesystem.readFilefilesystem.writeFilestorage.setDatastorage.getData
os.execCommand is intentionally absent from the default allowlist. A custom build that adds local command execution must treat document content as untrusted and use an explicit opt-in with fixed, narrowly scoped commands.
Browser/chrome modes block filesystem and OS APIs more tightly.
prepare.js:
- Copies the root app into
desktop-app/resources. - Copies assets.
- Moves runtime scripts to the desktop resource structure.
- Rewrites library URLs for Neutralino.
- Downloads required external libraries to
resources/libs. - Verifies SHA-384 integrity when SRI hashes are available.
- Bundles Bootstrap icon fonts.
- Strips web-only SEO/canonical/hreflang/schema metadata from the desktop HTML.
This is why the prepared desktop application can load core bundled renderer libraries without CDNs after setup.
See download choices and installation steps.
The v3.10.6 release contains the first packaged DMG and DEB application downloads plus organization-oriented identity, checksum, signing, compatibility, and managed-deployment guidance.
- Windows: download the x64
.exe. Unsigned builds may show SmartScreen. - Mac: choose
mac_x64.dmgfor Intel Macs or VMware on Intel/AMD Windows;mac_arm64.dmgfor Apple Silicon;mac_universal.dmgfor either. Open the DMG, drag the app to Applications, eject the image, and launch the installed app. Native builds target Intel macOS 10.15 and Apple Silicon macOS 11, with no upper-version cutoff. Install available Safari/WebKit updates; older OS versions require manual acceptance (CI tests macOS 15/26). Allow Documents access for the vault. - Mac signing: check
MACOS-SIGNING.txt. Ad-hoc test builds are not notarized; on Monterey, Control-click the app and choose Open, or use Security & Privacy → Open Anyway for a trusted download. Do not disable Gatekeeper globally. - Ubuntu/Debian: install the matching
.debwith Software Install, then launch from Applications. If no graphical installer is present, usesudo apt install ./markdown-viewer-linux_amd64.deb(Intel/AMD). The installer resolves WebKitGTK and other dependencies. Portable.tar.gzarchives need the same system libraries installed separately.
v3.10.5 raw Mac binaries are not suitable for Monterey: they lack app bundles and require macOS 14. Changing permissions alone cannot fix that release.
- Normal documents are ordinary
.mdfiles under the fixedDocuments/Markdown Viewer Vault/Workspacepath. - Vault metadata, up to 20 recent history copies per document, trash, recovery journals, settings, and opaque encrypted Secret Workspace records are kept under the same vault.
- Linked documents keep separate recovery drafts under the vault. After a recovered copy is saved successfully, only its matching captured journal is consumed; failed saves or a newer replacement journal remain recoverable instead of being deleted.
- Replacement binaries check the fixed vault path automatically. Use Storage and Backup to inspect, back up, import, or open it.
- Importing a ZIP backup replaces the current workspace. ZIP backups exclude vault history, trash, and recovery journals; copy the full vault separately when those records must also be retained.
- Native file access happens through explicit open/save actions or launch arguments.
- The app does not include analytics or telemetry.
- Sharing/import/remote-rendering features use the same network behavior as the web app.
- Private mode pauses new persistence for the current page session without deleting saved content and resets when the page reloads or exits. Reset workspace permanently deletes the vault content, folders, recovery data, and application preferences after confirmation.
Related pages: Installation, Configuration, Privacy and Security, and Troubleshooting.