@shaneholloman/vark

vark

Real-time markdown editor with voice transcription and URL-encoded content storage ➜ check it out

Installation

bun add @shaneholloman/vark

Or with npm:

npm install @shaneholloman/vark

Features

• URL-based storage - The buffer content is compressed and stored in the URL hash
• Voice transcription - Record audio and convert to text using OpenAI Whisper
• Real-time preview - Live markdown editing and preview
• Dark/light theme - Automatically adapts to your system preference
• Character limit tracking - Visual indicator of URL length usage

Development

This project uses bun for package management.

Setup

bun install

Available Commands

bun run dev      # Start development server
bun run build    # Build for production
bun run preview  # Preview production build
bun run test     # Run tests in watch mode
bun run test:run # Run tests once

Deployment

Vark works locally for development and testing, but it's best deployed as a public web application. Since the content is stored entirely in the URL hash, there's no backend required - just static file hosting.

GitHub Pages is an easy and free way to deploy Vark. Fork the repository, enable GitHub Pages, and you'll have your own instance running in minutes.

GitHub Pages Troubleshooting

If you encounter a blank white page when deploying to GitHub Pages, ensure your Pages source is configured correctly:

• Go to your repository's Settings > Pages
• Under "Source", select "Deploy from a branch"
• Choose gh-pages branch and / (root) folder

Alternatively, use the GitHub CLI:

gh api --method PUT repos/username/repo-name/pages --input - <<< '{"source":{"branch":"gh-pages","path":"/"}}'

This ensures GitHub Pages serves the built files from the gh-pages branch (where the deployment workflow publishes them) rather than the source files from the main branch.

Testing

This project uses Vitest with React Testing Library for a fast, modern testing experience.

Testing Stack

• Vitest: Fast unit test framework built on Vite
• @testing-library/react: React component testing utilities
• @testing-library/jest-dom: Custom DOM matchers
• @testing-library/user-event: User interaction simulation
• jsdom: Browser environment simulation

Test Suite Purpose

Important: This test suite is NOT for validating that code works correctly. It serves as guardrails to prevent regressions when modifying existing features or adding new ones. The tests ensure that critical functionality like compression, storage, and provider interfaces don't break during refactoring or updates.

Project Structure

src/
├── components/
│   ├── editor.tsx           # Main markdown editor with URL storage, live preview, and virtual keyboard handling
│   ├── recorder.tsx         # Voice recording component with multi-provider transcription support
│   ├── icon.tsx             # SVG app icon (file-volume symbol)
│   └── ui/                  # UI components (Base UI)
│       ├── input.tsx        # Form input component
│       ├── label.tsx        # Form label component
│       └── select.tsx       # Dropdown selection component
├── providers/               # Speech-to-text provider abstraction layer
│   ├── index.ts             # Provider factory and registry system
│   ├── types.ts             # Common interfaces for transcription providers
│   ├── openai.ts            # OpenAI Whisper provider implementation
│   └── google.ts            # Google Speech-to-Text provider implementation
├── shared/                  # Cross-platform utilities and core logic
│   ├── compression.ts       # URL-based content storage with gzip compression
│   ├── storage.ts           # Universal storage layer (browser localStorage + planned CLI file storage)
│   └── types.ts             # Shared TypeScript definitions
├── lib/                     # Utility libraries
│   └── utils.ts             # Tailwind CSS class merging utility
├── test/                    # Test suite
│   ├── setup.ts             # Minimal test setup
│   ├── compression.test.ts  # Real compression tests using Node.js zlib
│   ├── providers.test.ts    # Provider factory and interface tests
│   ├── storage.test.ts      # Storage logic tests
│   └── utils.test.ts        # Utility function tests
├── main.tsx                 # React application entry point
├── index.css                # Tailwind CSS directives and base styles
├── style.css                # Custom CSS overrides for markdown editor
└── vite-env.d.ts            # TypeScript definitions for Vite environment

Keyboard Shortcuts

• Cmd + Enter: Start/stop recording
• Cmd + e: Toggle editor/split/view mode
• for md shortcuts, see react-md-editor