vesper/README.md

Vesper

A beautiful, distraction-free markdown reader for Windows. Vesper renders your markdown files with premium editorial typography and a refined dark aesthetic, giving you the ultimate reading experience.

---

Features

Markdown Rendering

• Full CommonMark support via markdown-it with extensions:
  • Syntax highlighting for 190+ languages (highlight.js)
  • Task lists (checkboxes)
  • Superscript and subscript (^text^, ~text~)
  • ==Highlighted text== via mark
  • Smart quotes, em-dashes, and ellipses (typographer)
  • Line break preservation
  • Auto-linking of URLs
  • HTML passthrough
• Premium dark-mode typography tuned for long-form reading:
  • Inter Variable at 17px with 1.7 line-height
  • ~65 character measure (680px max-width) for optimal readability
  • Progressive heading color cascade (H1 near-white through H6 muted)
  • Accent-colored list markers
  • Gradient-fade horizontal rules
  • Subtle persistent link underlines that intensify on hover
  • Refined blockquote, table, and code block styling
  • JetBrains Mono Variable for code at 14px with ligature support

Tabbed Interface

• Open multiple documents in tabs
• Duplicate detection: re-opening an already-open file switches to its existing tab instead of creating a duplicate
• Animated tab enter/exit with layout transitions
• Scroll arrows appear when tabs overflow the bar, with hold-to-scroll
• Mouse wheel scrolling over the tab bar
• New tabs automatically scroll into view
• Close individual tabs with the X button or Ctrl+W

Navigation

• Table of Contents sidebar auto-generated from document headings (H1-H6), with indentation by level
• Click any heading in the sidebar to smooth-scroll to that section
• Sidebar opens even when a document has no headings (shows "No headings" message)
• Resizable sidebar via drag handle
• Full-text search (Ctrl+F) with real-time DOM highlighting, match counter, and Enter to cycle through matches

Reading Experience

• Focus Mode (F11) hides the title bar and menu bar for immersive reading
• Content zoom via Ctrl+Scroll (50%--200%)
• Content width adjustment via Shift+Scroll (400px--1200px)
• UI scale (50%--200%) with a spinner in the View menu, persisted across sessions via localStorage
• Kinetic scrolling on right-mouse-button drag with iOS-style rubber band overscroll and damped spring snapback
• Custom scrollbars via OverlayScrollbars -- thin, auto-hiding after 800ms, accent-colored on hover
• Window state (size, position, maximized) remembered between sessions

File Handling

• Open files via the File menu, Ctrl+O dialog, or drag-and-drop from Explorer
• Supports .md, .markdown, and .txt files
• Native Tauri drag-and-drop integration (receives real file system paths)

UI Details

• Custom frameless title bar with minimize, maximize/restore, and close buttons
• Draggable title area for window repositioning
• Menu bar with File, View, and Help menus
• Right-click context menu with: Copy (when text is selected), Open File, Toggle Search, Toggle Sidebar, Focus Mode, Keyboard Shortcuts, About, Exit
• Text selection preserved visually on right-click via overlay rendering
• Context menu stays within window bounds and respects UI zoom
• All panels, modals, tabs, and menus animate with Framer Motion (slide, fade, scale)
• Subtle noise texture overlay on the app background
• Keyboard shortcuts modal listing all bindings

---

Keyboard Shortcuts

Shortcut	Action
Ctrl+O	Open file
Ctrl+W	Close current tab
Ctrl+Q	Exit application
Ctrl+F	Toggle search
Ctrl+Shift+S	Toggle sidebar
F11	Toggle focus mode
Escape	Close search / sidebar
Ctrl+Scroll	Zoom content in / out
Shift+Scroll	Adjust content width

---

Installation

Prerequisites

• Windows 10 or later
• WebView2 Runtime (pre-installed on Windows 10/11)

Download

Download the latest vesper.exe from the Releases page. No installation required -- Vesper is fully portable.

Build from Source

Prerequisites:

• Node.js v18+
• Rust (stable toolchain)
• Tauri v2 prerequisites

# Clone the repository
git clone https://github.com/yourusername/vesper.git
cd vesper

# Install dependencies
npm install

# Run in development mode (hot-reload on localhost:1420)
npm run tauri dev

# Build for production
npm run tauri build

Build output: src-tauri/target/release/vesper.exe

---

Technology Stack

Layer	Technology
Runtime	Tauri v2 (Rust + WebView2)
Frontend	React 19, TypeScript, Vite 7
Styling	Tailwind CSS 4, DaisyUI 5, custom CSS
Markdown	markdown-it with plugins (task-lists, sup, sub, mark)
Syntax Highlighting	highlight.js
Animation	Framer Motion
Fonts	Inter Variable, JetBrains Mono Variable
Icons	Lucide React
Scrollbars	OverlayScrollbars

Tauri Plugins

• tauri-plugin-dialog -- native file open dialog
• tauri-plugin-fs -- file system read access
• tauri-plugin-opener -- system default app launcher

---

Portable

Vesper is fully portable. It stores all data in a data/ folder next to the executable:

• data/window-state.json -- window position, size, and maximized state
• data/EBWebView/ -- WebView2 data including localStorage (UI zoom preference)

Nothing is written to AppData, the registry, or any other system location. To move Vesper to another machine, just copy the exe (and optionally the data/ folder to preserve settings).

---

Design Philosophy

1. Content First -- the reader is the primary focus; all UI chrome can be hidden
2. Typography Matters -- Inter Variable at 17px, 1.7 line-height, ~65 character measure, generous whitespace
3. Dark by Default -- deep onyx base color (#282C33) reduces eye strain
4. Keyboard Driven -- every feature accessible via keyboard shortcuts
5. Minimalist Chrome -- the interface gets out of your way

---

Color Palette

Color	Hex	Usage
Base	#282C33	Main window background
Surface	#252A31	Title bar, sidebar
Elevated	#2D333C	Active tab, modals
Overlay	#333942	Dropdowns, context menu
Text Primary	#E4E6EB	Main content
Text Secondary	#ABB0B8	UI labels, muted text
Text Tertiary	#6B7280	Placeholders, hints
Accent	#6B8AFF	Interactive elements, highlights
Link	#7CA9F7	Hyperlinks

---

Project Structure

md-reader/
  src/
    App.tsx            # Main application component (all UI logic)
    main.tsx           # React entry point
    styles.css         # All styles -- variables, UI components, markdown typography
  src-tauri/
    src/
      main.rs          # Rust entry point
      lib.rs           # Tauri builder and plugin registration
    tauri.conf.json    # Tauri window, bundle, and build configuration
    Cargo.toml         # Rust dependencies
    icons/             # App icons (ICO, PNG, ICNS)
  index.html
  package.json
  vite.config.ts
  tsconfig.json

---

License

This project is dedicated to the public domain under the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication -- see the LICENSE file for details.

---

Acknowledgments

• iA Writer for design inspiration
• Tauri for the excellent desktop framework
• markdown-it for robust markdown parsing
• highlight.js for syntax highlighting