Desktop App

Desktop Application Guide

This page describes the architecture, development setup, build options, and platform installation procedures for the desktop version of Markdown Viewer (v3.7.4), powered by the Neutralinojs runtime framework.

---

Table of Contents

• Overview
• Workspace Directory Structure
• Prerequisites
• Local Development Setup
• Running in Hot-Reload Dev Mode
• Building the Application
• Build Output Configurations
• Building with Docker Containerization
• Platform-Specific Installation Guidelines
  • Windows
  • Linux
  • macOS

---

Overview

The desktop version of Markdown Viewer wraps the core web application (HTML, CSS, JS) inside a lightweight native OS webview container using the Neutralinojs framework.

Why Neutralinojs?

• Minimal Footprint: Unlike Electron, which bundles a full Chromium browser and Node.js instance, Neutralinojs uses the system's built-in webview. This results in an executable size of less than 15 MB (compared to 150+ MB for Electron).
• Low Resource Usage: Idle memory usage is typically under 50 MB.
• Shared Codebase: The desktop app uses the exact same core files (script.js, styles.css, assets/) as the web application.

---

Workspace Directory Structure

The desktop-app directory contains the configuration files and build scripts for the desktop version:

desktop-app/
├── package.json              # Contains npm build scripts
├── neutralino.config.json    # Configures Neutralino window size, titles, and API permissions
├── setup-binaries.js         # Script to download Neutralino binaries for target platforms
├── prepare.js                # Copies core files from the root folder into the resources folder
└── resources/                # Assets packaged into the desktop application
    ├── index.html            # Compiled template page
    ├── styles.css            # Stylesheet copied from the root folder
    ├── js/
    │   ├── main.js           # Handles desktop lifecycle events and tray menus
    │   ├── script.js         # Copied from the root folder
    │   └── neutralino.js     # Neutralino client API library
    └── assets/               # Image assets copied from the root folder

---

Prerequisites

To compile the desktop application from source, you will need:

• Node.js (v16.0.0 or later) and npm (installed automatically with Node).
• An active internet connection (only required during the initial setup to download Neutralino runtimes).

---

Local Development Setup

To set up the desktop project directory locally:

1. Open your terminal and navigate to the desktop-app folder:

   cd Markdown-Viewer/desktop-app

2. Install dependencies:

   npm install

3. Download the required Neutralino framework binaries for Windows, Linux, and macOS:

   node setup-binaries.js

4. Copy the latest frontend code from the repository root into the desktop build resources folder:

   node prepare.js

---

Running in Hot-Reload Dev Mode

To run the application locally in development mode:

npm run dev

This starts the desktop application in a new window. It enables a development server with hot-reload: edits to files in the resources/ folder will immediately update the running application without requiring a manual rebuild.

---

Building the Application

You can package the application in three ways:

1. Embedded Binary (Recommended for Windows)

This builds a single, self-contained Windows executable file that has all application resources embedded inside the binary:

npm run build

2. Portable Distribution

This builds the application with the binary and a separate resources.neu file. This is standard for multi-platform distributions:

npm run build:portable

3. Build All Formats

This compiles both the portable distribution ZIP file and the embedded Windows executable:

npm run build:all

---

Build Output Configurations

Compiled files are placed in the desktop-app/dist/ directory:

dist/
├── markdown-viewer/                         # Contains portable binaries
├── markdown-viewer-release.zip              # Compressed portable distribution
└── windows-embedded/
    └── markdown-viewer/
        └── markdown-viewer-win_x64.exe      # Single-file Windows binary

---

Building with Docker Containerization

To package the application without installing Node.js locally, use the provided Docker Compose configuration to compile the binaries inside a container:

# Run from the desktop-app folder
docker compose up --build

The container downloads the required binaries, runs the build scripts, and saves the output to the host system's dist/ directory using a volume mount.

---

Platform-Specific Installation Guidelines

Windows

• Installation: No installer is needed. Run markdown-viewer-win_x64.exe directly.
• SmartScreen Warning: Because the executable is unsigned, Windows SmartScreen may display a warning on first launch. Click More info, then select Run anyway to launch the application.

Linux

Make the binary executable before running it:

chmod +x markdown-viewer-linux_x64
./markdown-viewer-linux_x64

macOS

macOS blocks unsigned binaries by default. To run the app, clear the quarantine flag and make the file executable:

# Remove the macOS quarantine flag
xattr -d com.apple.quarantine markdown-viewer-mac_universal

# Grant execution permissions
chmod +x markdown-viewer-mac_universal

# Run the app
./markdown-viewer-mac_universal

Alternatively, right-click the app binary in Finder, click Open, and select Open in the confirmation dialog.