lashman/vesper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Polish README with modern layout, emojis, and tables

Browse Source
This commit is contained in:
Your Name
2026-02-14 12:04:51 +02:00
parent 99abaac097
commit b2a7cf11d4
1 changed files with 199 additions and 171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

370
README.md
View File

@@ -1,104 +1,129 @@
# Vesper
<div align="center">
<p align="center">
<img src="https://img.shields.io/badge/version-1.0.0-blue" alt="Version">
<img src="https://img.shields.io/badge/platform-Windows-blue" alt="Platform">
<img src="https://img.shields.io/badge/framework-Tauri 2.0-black" alt="Framework">
<img src="https://img.shields.io/badge/license-CC0-green" alt="License">
</p>
# ✦ 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
<br>
### Markdown Rendering
<img src="https://img.shields.io/badge/version-1.0.0-6B8AFF?style=flat-square&labelColor=282C33" alt="Version">
<img src="https://img.shields.io/badge/platform-Windows-6B8AFF?style=flat-square&labelColor=282C33" alt="Platform">
<img src="https://img.shields.io/badge/Tauri-v2-6B8AFF?style=flat-square&labelColor=282C33" alt="Tauri">
<img src="https://img.shields.io/badge/license-CC0-6B8AFF?style=flat-square&labelColor=282C33" alt="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
</div>
### Tabbed Interface
<br>
- 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
<br>
### 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
---
<br>
## 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`
<br>
### 🧭 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
<br>
### 👁️ 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 |
<br>
### 📂 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
<br>
### 🎨 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
<br>
## ⌨️ 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 |
---
<br>
## 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`
<br>
---
## 🔧 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
<br>
- `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
<br>
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
<br>
- [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 |
<br>
## 🗂️ 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
```
<br>
## 📜 License
This project is dedicated to the public domain under **CC0 1.0 Universal** — see the [LICENSE](LICENSE) file for details.
<br>
## 🙏 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