From b2a7cf11d47c61f78e1d3951bb2d312c78984a11 Mon Sep 17 00:00:00 2001 From: Your Name Date: Sat, 14 Feb 2026 12:04:51 +0200 Subject: [PATCH] Polish README with modern layout, emojis, and tables --- README.md | 370 +++++++++++++++++++++++++++++------------------------- 1 file changed, 199 insertions(+), 171 deletions(-) diff --git a/README.md b/README.md index e8119dc..dff8d9c 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,129 @@ -# Vesper +
-

- Version - Platform - Framework - License -

+# โœฆ 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. +**A beautiful, distraction-free markdown reader for Windows** ---- +Premium editorial typography ยท Refined dark aesthetic ยท Fully portable -## Features +
-### Markdown Rendering +Version +Platform +Tauri +License -- 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` +## ๐Ÿ“– Overview -### Navigation +Vesper renders your markdown with carefully tuned typography and a refined dark interface, giving you the ultimate reading experience. No installation, no AppData, no registry โ€” just drop the exe and go. -- **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 +## โœจ Features -- **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 +### ๐Ÿ”ค Markdown Rendering -### File Handling +Full CommonMark support via **markdown-it** with extensions: -- 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) +| Extension | Description | +|:--|:--| +| ๐ŸŽจ Syntax Highlighting | 190+ languages via highlight.js with a curated dark palette | +| โ˜‘๏ธ Task Lists | Interactive checkboxes in lists | +| แดฌแต‡ Superscript / Subscript | `^text^` and `~text~` notation | +| ๐Ÿ–๏ธ Highlight | `==marked text==` rendered with accent background | +| ๐Ÿ’ฌ Typographer | Smart quotes, em-dashes, and ellipses | +| ๐Ÿ”— Linkify | Bare URLs auto-converted to clickable links | +| ๐Ÿ“„ HTML | Inline HTML passthrough | +| โ†ต Breaks | Newlines preserved as line breaks | -### UI Details +**Premium dark-mode typography** tuned for long-form reading: -- 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 +> - **Inter Variable** at 17px with 1.7 line-height +> - ~65 character measure for optimal readability +> - Progressive heading color cascade โ€” H1 near-white through H6 muted +> - Accent-colored list markers on both ordered and unordered lists +> - Gradient-fade horizontal rules +> - Subtle persistent link underlines that intensify on hover +> - **JetBrains Mono Variable** for code at 14px with ligature support ---- +
-## Keyboard Shortcuts +### ๐Ÿ“‘ Tabbed Interface + +- Open **multiple documents** simultaneously in tabs +- ๐Ÿ” **Duplicate detection** โ€” re-opening an already-open file switches to its tab +- โœจ Animated tab enter/exit with layout transitions +- โ—€ โ–ถ **Scroll arrows** appear on overflow with hold-to-scroll +- ๐Ÿ–ฑ๏ธ **Mouse wheel** scrolling over the tab bar +- ๐Ÿ“Œ New tabs **auto-scroll** into view +- โœ• Close tabs with the button or `Ctrl+W` + +
+ +### ๐Ÿงญ Navigation + +- ๐Ÿ“‹ **Table of Contents** sidebar auto-generated from headings (H1โ€“H6) with indentation +- Click any heading to **smooth-scroll** to that section +- Sidebar opens even with no headings (shows "No headings" message) +- โ†”๏ธ **Resizable** sidebar via drag handle +- ๐Ÿ” **Full-text search** with real-time highlighting, match counter, and `Enter` to cycle + +
+ +### ๐Ÿ‘๏ธ Reading Experience + +| Feature | Details | +|:--|:--| +| ๐Ÿ–ฅ๏ธ Focus Mode | `F11` hides title bar and menu for immersive reading | +| ๐Ÿ”Ž Content Zoom | `Ctrl+Scroll` โ€” 50% to 200% | +| โ†”๏ธ Content Width | `Shift+Scroll` โ€” 400px to 1200px | +| ๐Ÿ”ฒ UI Scale | 50%โ€“200% via View menu spinner, persisted across sessions | +| ๐Ÿ€ Kinetic Scroll | Right-mouse drag with iOS-style rubber band overscroll | +| ๐Ÿ“œ Custom Scrollbars | Thin, auto-hiding, accent-colored on hover | +| ๐Ÿ’พ Window Memory | Position, size, and maximized state remembered between sessions | + +
+ +### ๐Ÿ“‚ File Handling + +- Open via **File menu**, **`Ctrl+O`**, or **drag-and-drop** from Explorer +- Supports `.md` ยท `.markdown` ยท `.txt` +- Native Tauri drag-and-drop integration with real file system paths + +
+ +### ๐ŸŽจ UI Details + +- Custom **frameless title bar** with minimize, maximize/restore, and close +- **Right-click context menu** โ€” Copy, 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 bounds** and respects UI zoom +- All panels, modals, tabs, and menus **animate** with Framer Motion +- Subtle **noise texture overlay** on the app background + +
+ +## โŒจ๏ธ 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 | +|:--|:--| +| `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 +## ๐Ÿ“ฆ Installation ### Prerequisites @@ -107,125 +132,128 @@ A beautiful, distraction-free markdown reader for Windows. Vesper renders your m ### Download -Download the latest `vesper.exe` from the [Releases](https://github.com/yourusername/vesper/releases) page. No installation required -- Vesper is fully portable. +Download the latest **`vesper.exe`** from the [Releases](https://github.com/yourusername/vesper/releases) page. +No installation required โ€” Vesper is fully portable. ### Build from Source -**Prerequisites:** -- [Node.js](https://nodejs.org/) v18+ -- [Rust](https://www.rust-lang.org/tools/install) (stable toolchain) -- [Tauri v2 prerequisites](https://v2.tauri.app/start/prerequisites/) +> **Requires:** [Node.js](https://nodejs.org/) v18+ ยท [Rust](https://www.rust-lang.org/tools/install) stable ยท [Tauri v2 prerequisites](https://v2.tauri.app/start/prerequisites/) ```bash -# 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) +```bash +# Development (hot-reload on localhost:1420) npm run tauri dev -# Build for production +# Production build npm run tauri build +# โ†’ src-tauri/target/release/vesper.exe ``` -Build output: `src-tauri/target/release/vesper.exe` +
---- +## ๐Ÿ”ง Technology Stack -## Technology Stack +| | Layer | Technology | +|:--|:--|:--| +| โš™๏ธ | Runtime | [Tauri v2](https://tauri.app/) โ€” Rust + WebView2 | +| โš›๏ธ | Frontend | React 19 ยท TypeScript ยท Vite 7 | +| ๐ŸŽจ | Styling | Tailwind CSS 4 ยท DaisyUI 5 ยท Custom CSS | +| ๐Ÿ“ | Markdown | [markdown-it](https://github.com/markdown-it/markdown-it) + plugins | +| ๐ŸŒˆ | Syntax | [highlight.js](https://highlightjs.org/) | +| ๐ŸŽฌ | Animation | [Framer Motion](https://www.framer.com/motion/) | +| ๐Ÿ”ค | Fonts | [Inter Variable](https://rsms.me/inter/) ยท [JetBrains Mono](https://www.jetbrains.com/lp/mono/) | +| ๐Ÿ–ผ๏ธ | Icons | [Lucide React](https://lucide.dev/) | +| ๐Ÿ“œ | Scrollbars | [OverlayScrollbars](https://kingsora.github.io/OverlayScrollbars/) | -| Layer | Technology | -|---|---| -| Runtime | [Tauri v2](https://tauri.app/) (Rust + WebView2) | -| Frontend | React 19, TypeScript, Vite 7 | -| Styling | Tailwind CSS 4, DaisyUI 5, custom CSS | -| Markdown | [markdown-it](https://github.com/markdown-it/markdown-it) with plugins (task-lists, sup, sub, mark) | -| Syntax Highlighting | [highlight.js](https://highlightjs.org/) | -| Animation | [Framer Motion](https://www.framer.com/motion/) | -| Fonts | [Inter Variable](https://rsms.me/inter/), [JetBrains Mono Variable](https://www.jetbrains.com/lp/mono/) | -| Icons | [Lucide React](https://lucide.dev/) | -| Scrollbars | [OverlayScrollbars](https://kingsora.github.io/OverlayScrollbars/) | +**Tauri Plugins:** `dialog` ยท `fs` ยท `opener` -### 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** โ€” zero installation, zero system footprint. -## 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 +All data lives in a `data/` folder next to the executable: ``` -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 +vesper.exe +data/ + โ”œโ”€โ”€ window-state.json โ† window position, size, maximized + โ””โ”€โ”€ EBWebView/ โ† WebView2 data (localStorage, cache) ``` ---- +> Nothing is written to AppData, the registry, or any other system location. +> To move Vesper, just copy the exe and optionally the `data/` folder. -## License +
-This project is dedicated to the public domain under the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication -- see the [LICENSE](LICENSE) file for details. +## ๐Ÿง  Design Philosophy ---- +| | Principle | +|:--|:--| +| ๐Ÿ“– | **Content First** โ€” all UI chrome can be hidden; the reader is the focus | +| ๐Ÿ”ค | **Typography Matters** โ€” Inter at 17px, 1.7 line-height, ~65 char measure | +| ๐ŸŒ™ | **Dark by Default** โ€” deep onyx base `#282C33` reduces eye strain | +| โŒจ๏ธ | **Keyboard Driven** โ€” every feature accessible via shortcuts | +| โœจ | **Minimalist Chrome** โ€” the interface gets out of your way | -## Acknowledgments +
-- [iA Writer](https://ia.net/writer) for design inspiration -- [Tauri](https://tauri.app/) for the excellent desktop framework -- [markdown-it](https://github.com/markdown-it/markdown-it) for robust markdown parsing -- [highlight.js](https://highlightjs.org/) for syntax highlighting +## ๐ŸŽจ Color Palette + +| Swatch | Name | Hex | Usage | +|:--|:--|:--|:--| +| ๐ŸŸซ | Base | `#282C33` | 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 | +| ๐Ÿฉถ | Text Tertiary | `#6B7280` | Placeholders, hints | +| ๐Ÿ”ต | Accent | `#6B8AFF` | Interactive elements | +| ๐Ÿ”ท | Link | `#7CA9F7` | Hyperlinks | + +
+ +## ๐Ÿ—‚๏ธ Project Structure + +``` +vesper/ +โ”œโ”€โ”€ src/ +โ”‚ โ”œโ”€โ”€ App.tsx Main application component +โ”‚ โ”œโ”€โ”€ main.tsx React entry point +โ”‚ โ””โ”€โ”€ styles.css Variables, UI, markdown typography +โ”œโ”€โ”€ src-tauri/ +โ”‚ โ”œโ”€โ”€ src/ +โ”‚ โ”‚ โ”œโ”€โ”€ main.rs Rust entry point +โ”‚ โ”‚ โ””โ”€โ”€ lib.rs Tauri builder, portable data, window state +โ”‚ โ”œโ”€โ”€ capabilities/ +โ”‚ โ”‚ โ””โ”€โ”€ default.json Permission declarations +โ”‚ โ”œโ”€โ”€ tauri.conf.json Window, bundle, and build config +โ”‚ โ”œโ”€โ”€ 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 **CC0 1.0 Universal** โ€” see the [LICENSE](LICENSE) file for details. + +
+ +## ๐Ÿ™ Acknowledgments + +- [iA Writer](https://ia.net/writer) โ€” design inspiration +- [Tauri](https://tauri.app/) โ€” desktop framework +- [markdown-it](https://github.com/markdown-it/markdown-it) โ€” markdown parsing +- [highlight.js](https://highlightjs.org/) โ€” syntax highlighting