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 via tauri-plugin-window-state

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 installer from the Releases page:

• NSIS installer (.exe) -- recommended, includes uninstaller
• MSI installer (.msi) -- alternative for enterprise/group policy deployment
• Portable exe -- standalone vesper.exe with no installation required

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 outputs:

• src-tauri/target/release/vesper.exe -- portable executable
• src-tauri/target/release/bundle/msi/Vesper_1.0.0_x64_en-US.msi -- MSI installer
• src-tauri/target/release/bundle/nsis/Vesper_1.0.0_x64-setup.exe -- NSIS installer

---

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-window-state -- persist and restore window size, position, and maximized state
• tauri-plugin-opener -- system default app launcher

---

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