Marginalia

Marginalia is a focused, web-based markdown editor designed for fiction writing with integrated Git/GitHub version control.

🚀 Live Running Instance: Try Marginalia hosted live at http://64-181-248-211.nip.io

Features

• Focus-Oriented Writing: Distraction-free mode to collapse the file sidebar and preview panels.
• Live Markdown Preview: Real-time side-by-side rendering of your document text.
• Word & Page Count Estimators: Word counters with estimation formulas for paperback or hardback pages.
• Workspace Manager:
  • GitHub Repositories Browser: Direct integration to list all of your public and private GitHub repositories with instant search filtering.
  • One-Click Clone & Open: Clones public or private repositories into automatically derived user storage directories without requiring manual local folder pathing or host SSH setup.
  • Sandboxed Hosted Mode: Enforces user storage isolation when running in hosted mode, restricting arbitrary server filesystem browsing.
• Git & GitHub Version Control: Commit, push, and pull directly from the header toolbar with remote sync statuses.
• Git Auto-Identity Configurator: Automatically configures local Git user.name and user.email properties on commit if they are unset, pulling from active GitHub accounts in Hosted Mode and local OS profiles in Local Mode.
• Interactive AI Editor Panel: Developmental, Line, Copy, Proofreader, or Write With Me (conversational inline guide) personas using Gemini. Supports multi-turn follow-up chats.
• Context Selector Tree: Select individual chapters or check entire directory folders (which recursively parses nested markdown files) to use as AI prompt context.
• Apply Suggestion Diff Cards: Inline comparison cards for proposed text changes with red/green highlights and click-to-apply patches.
• SQLite-Backed AI Cache: Chat history and applied checkbox states are persisted per-chapter/persona across page refreshes.
• OSS Markdown Linter & Formatting: Integrated David Anson's markdownlint library on the backend to flag structural issues (heading jumps, missing image alt text, trailing whitespace) with a dedicated "Format" document button in the header.
• Spelling & Grammar Check Cache: Employs MD5-hashed paragraph caching for LanguageTool spelling and grammar checks in SQLite, speeding up checks and avoiding API throttling.
• Spelling Context Menus: Right-click context menus with custom dictionaries, spell suggestions, and "Replace All" actions.
• Prose-First Gemini Model Selector: Dynamically queries model selection list, filtering out legacy models, image/video generators (Imagen, Veo), and utility models while retaining active releases and experimental previews.
• 🎭 Parlando Neural Speech & Audiobooks: Integrated multi-voice prose speech synthesis engine with character dialogue attribution, punctuation prosody, zero-crossing DSP, and gapless continuous playback.
  • 🔊 Play Sample MP3 (1.48 min) • 🌐 Open Web Player

Setup & Running

1. Ensure you have Node.js (v22+) installed.
2. Run the startup script from the root directory:

   ./run.sh

3. Open your browser and navigate to: http://localhost:5173

Cloud VM Deployment

To deploy Marginalia on an Oracle Cloud VM or Linux server:

./scripts/setup_vm.sh

Architecture

• Frontend: React + TypeScript + Vite.
• Backend: Express + Node's built-in SQLite database (node:sqlite).
• VCS: Local git CLI wrappers with SimpleGit & GitHub REST API v3.

Hosting & Deployment

The easiest way to host Marginalia is using Docker and Docker Compose, which packages the Node runtime, Git CLI client, and compiled static assets into a single container.

1. Self-Hosting via Docker Compose

Build and run the application locally or on a VPS (DigitalOcean, GCE, etc.):

docker-compose up -d --build

This will:

• Spin up the Express server on port 3000 (accessible at http://localhost:3000).
• Mount a persistent docker volume marginalia_data at /root/.marginalia to persist your SQLite database and cloned git repositories.
• Mount your local SSH configs (~/.ssh) in read-only mode so Git operations in Marginalia can authenticate with GitHub using your host machine's SSH keys.

2. Deploying to PaaS (Railway, Render, Fly.io)

You can link your repository directly to a PaaS:

1. Configure Nixpacks/Buildpacks: Ensure the platform installs the git system package.
2. Mount Persistent Volume: Attach a persistent disk volume (e.g. 1GB) and mount it to /root/.marginalia.
3. Environment Variables:
   • Set DB_DIR=/root/.marginalia.
   • Set PORT=3000.
   • Set SESSION_SECRET to a long random secret key.
   • (Optional) Set GEMINI_API_KEY to pre-seed the LLM key.

3. Deploying to Oracle Cloud "Always Free" VM

You can run Marginalia 24/7 for free on an Oracle Cloud Compute VM (Ubuntu):

1. Create a VM Instance on the Oracle Cloud console (Ubuntu 22.04 / 24.04 image, assign a public IPv4, and download the SSH key).
2. Add Ingress Security Rules in OCI console (Network Security List):
   • Add Ingress Rule: Source 0.0.0.0/0, TCP Protocol, Destination Port 80.
3. SSH into your VM and run our automated setup script:

   curl -fsSL https://raw.githubusercontent.com/plbogen2/marginalia/main/scripts/setup_vm.sh -o setup_vm.sh
   chmod +x setup_vm.sh
   ./setup_vm.sh

   This script automatically updates the system, installs Docker & Compose, configures local iptables firewalls, clones the repo, and runs the application bound to standard port 80.
4. Open marginalia/.env on the server to add your GEMINI_API_KEY and restart the container (docker-compose restart).
5. Automate Deployments with GitHub Actions: To automatically redeploy the application on every git push to main:
   • Go to your GitHub repository -> Settings -> Secrets and variables -> Actions.
   • Create the following Repository Secrets:
     • SSH_HOST: Your VM's public IPv4 address.
     • SSH_USERNAME: The login username (ubuntu).
     • SSH_KEY: The full content of your private SSH key downloaded from OCI (begins with -----BEGIN OPENSSH PRIVATE KEY-----).
   • On your next push, GitHub Actions will SSH into the VM, pull the latest code, and rebuild the containers automatically.