MD Float

A frameless floating Electron window for reading Markdown, code, logs, and data files. Stays on top while you work. Reads your documents aloud using Kokoro TTS with an LLM rewrite pass for natural speech.

What it does

• Opens .md, .txt, .log, .json, .csv, .yaml, .yml, .toml, .xml and 20+ code file types
• Renders Markdown with full GitHub Flavored Markdown (GFM) support and syntax-highlighted code blocks
• Syntax-highlights source code files via highlight.js for JS, TS, Python, Go, Rust, Shell, SQL, and more
• Pretty-prints and highlights JSON automatically
• Watches open files for disk changes and live-reloads without losing scroll position
• Reads documents aloud: strips markdown structure, rewrites via GLM-4.5-air for natural speech, then synthesizes with Kokoro TTS (af_bella voice at localhost:8880)
• Tabs for multiple open files, pinnable always-on-top, zoom controls, recent files list
• 8 built-in color themes plus auto-detection of your GNOME Terminal colors

Quick start

git clone https://github.com/sanchez314c/md-float.git
cd md-float
npm install
./run-source-linux.sh

Open a file with drag-and-drop, Ctrl+O, or pass paths directly:

./run-source-linux.sh README.md notes.txt

Keyboard shortcuts

Key	Action
Ctrl+O	Open file dialog
Ctrl+R	Toggle raw / rendered
Ctrl+Shift+P	Start / stop TTS read-aloud
Ctrl+W	Close active tab
Ctrl+C	Copy file content
Ctrl+= / Ctrl+- / Ctrl+0	Zoom in / out / reset
Ctrl+Tab / Ctrl+Shift+Tab	Cycle tabs forward / backward

TTS read-aloud

Requires Kokoro TTS running at localhost:8880. The pipeline is:

1. Markdown structure stripped and pause tokens injected
2. Text chunked at ~3000 chars and rewritten by GLM-4.5-air via api.z.ai for spoken delivery
3. Each chunk sub-divided at 4000 chars and synthesized by Kokoro
4. Audio chunks decoded from base64 and played sequentially through the Web Audio API

Set ZAI_API_KEY in your environment to override the default key.

Themes

Built-in presets: GitHub Dark, Dracula, Nord, Monokai, One Dark, Solarized Dark, Catppuccin Mocha, Auto.

Auto mode reads your GNOME Terminal profile colors via dconf and derives a matching palette. The result is cached at ~/.md-float/detected-colors.json.

Config files

All state is stored in ~/.md-float/:

File	Contents
window-state.json	Position, size, always-on-top flag
theme.json	Selected theme preset
recent.json	Last 20 opened file paths
detected-colors.json	Cached GNOME Terminal colors

Build

npm run build        # produces .deb in dist/
npm run build-dir    # unpacked directory in dist/linux-unpacked/

See docs/BUILD_COMPILE.md for full build instructions.

Requirements

• Node.js 18+
• Electron 33
• Linux (tested on Ubuntu with GNOME Terminal)
• Kokoro TTS at localhost:8880 (optional, only needed for read-aloud)
• Z.AI API access (optional, only needed for LLM speech rewrite)

License

MIT — see LICENSE