Markdown Web Editor

A modern, browser‑based Markdown editor you can run in any directory. Edit .md files with live preview, autosave, Git integration, and an optional AI assistant powered by OpenAI or Anthropic.

✨ Features

• 📁 File Explorer: Browse, create, rename, delete, and drag‑and‑drop files/folders
• 🖱️ Context Menus: Right‑click actions; mobile double‑tap to open the menu
• 🔀 Git Integration: Repo detection, color‑coded status, stage/add, commit (with message), push, and clone
• ✨ AI Assistant: Ask/Adjust modes; selection‑aware; OpenAI and Anthropic models; per‑file cost tracking
• 🔍 Selection Highlight: Keeps the selected range highlighted while the AI modal is open
• 👁️ Live Preview: Toggle or split view; GFM + syntax highlighting
• 💾 Autosave: Saves after you pause typing; manual save with Ctrl/Cmd+S
• 📊 Status Bar: Words, lines, characters, and cumulative AI cost per file
• 🧭 Deep Links: Direct URL to any file (#/path/to/file.md) with browser back/forward support
• 📤 Export: Download Markdown or export to PDF (styled by your theme)
• 🎨 Themes: VS Code‑inspired dark theme; pluggable theme system
• 📱 Responsive UI: Mobile‑friendly header icons and status layout
• 🌐 ngrok Support: Optional public URL via reserved domain when flags are provided

🚀 Quick Start

Run with npx (no installation required)

npx markdown-web

Or install globally

npm install -g markdown-web
markdown-web

CLI Options

• --no-open: Do not open the browser automatically
• --disable-auth: Disable password protection (not recommended)
• --auth <password>: Use a specific password instead of a random one
• --openai-key <key>: Provide an OpenAI API key via CLI (alternative to Settings)
• --ngrok-auth-token <token>: ngrok Authtoken (enables public tunnel when used with domain)
• --ngrok-domain <domain>: Reserved ngrok domain (e.g. yourname.ngrok.app)

# Do not auto-open browser
npx markdown-web --no-open

# Provide your own strong password
npx markdown-web --auth "S3cure-Long-Password!"

# Disable auth entirely (local trusted environments only)
npx markdown-web --disable-auth

# Start with a public ngrok URL (requires reserved domain)
npx markdown-web \
  --ngrok-auth-token YOUR_TOKEN \
  --ngrok-domain yourname.ngrok.app

📖 Usage

1. Navigate to any directory containing markdown files
2. Run npx markdown-web
3. Your browser will open to http://localhost:3001
4. Enter the password shown in your terminal (one is generated by default)
5. Start editing! Files are auto-saved as you type

Authentication

• By default, the server starts with password protection enabled.
  • A strong random password is generated and printed in your terminal when the server starts.
  • You can supply your own with --auth <password>, or disable auth with --disable-auth.
• Sessions are stored in a secure, HttpOnly cookie and last 24 hours.
• For best security, use HTTPS in untrusted networks (see below) or run behind an ngrok reserved domain.

Settings

• Open Settings from the gear icon in the sidebar footer.
• Settings persist to ~/.markdown-web/settings.json and include:
  • selectedTheme, previewLayout (full/split), sidebarMode (overlay/inline)
  • openAiKey, anthropicKey (store keys locally on your machine)
  • defaultModel, defaultModelProvider (OpenAI or Anthropic)
• You can also pass --openai-key to the CLI, or set env vars OPENAI_KEY/ANTHROPIC_API_KEY.

URL Navigation

• Direct file links: http://localhost:3001/#/path/to/file.md
• Bookmark specific files
• Browser back/forward works
• Refreshing preserves current file

Keyboard Shortcuts

• Ctrl+S / Cmd+S - Save immediately
• Toggle preview with header button
• Use hamburger menu to hide/show sidebar

🤖 AI Assistant

• Modes:
  • Adjust: Apply requested edits to the document (or just the selected text)
  • Ask: Ask questions about the current document; answer is read‑only (rendered Markdown)
• Selection‑aware: If text is selected, both Ask/Adjust operate only on that selection
• Selection highlight: Your selection stays highlighted while the AI modal is open
• Models in dropdown (only shown if you added the relevant key):
  • OpenAI: GPT‑5, GPT‑5 Mini, GPT‑5 Nano
  • Anthropic: Claude Sonnet 4 (claude-sonnet-4-0), Claude Opus 4.1 (claude-opus-4-1)
• Costs: Token costs are computed per request and accumulated per file; the Status Bar shows totals

Pricing (per 1K tokens; override via env if desired):

• OpenAI: GPT‑5 $0.00125 in / $0.01000 out; GPT‑5 Mini $0.00025 in / $0.00200 out; GPT‑5 Nano $0.00005 in / $0.00040 out
• Anthropic: Claude Opus 4.1 $15 in / $75 out; Claude Sonnet 4 $3 in / $15 out

Implementation notes:

• OpenAI via the openai SDK; Anthropic via @anthropic-ai/sdk
• Per‑file cost logs are stored at ~/.markdown-web/logs/<file>/ai.json

🧩 Git Integration

• Repos are auto‑detected; repo folders show a Git badge
• Colors: repo red (unstaged), yellow (staged); files green (untracked), yellow (modified), red (deleted)
• Right‑click (desktop) / double‑tap (mobile) context menus:
  • File: Add to Git / Stage changes; Rename; Delete
  • Repo folder: Commit… (title + message), Push; New File/Folder; Rename; Delete
• Clone repositories: Right‑click root or a folder → Clone Repository…
• Drag‑and‑drop: Move files/folders; target folders auto‑expand on hover
• Expanded folders persist when closing the overlay sidebar

🛠️ Development

To work on this project:

# Clone the repository
git clone https://github.com/vultuk/markdown-web.git
cd markdown-web

# Install dependencies
npm install

# Run in development mode (with hot reload)
npm run dev

# Build for production
npm run build

# Run production build
npm start

# Type check
npm run typecheck

🔒 Security

• Only allows access to files within the launch directory
• Automatically filters for .md files only
• Prevents directory traversal attacks
• No external network access required
• Password authentication is enabled by default; disable with --disable-auth or set with --auth <password>
• Browser sessions are protected with HttpOnly, SameSite=Strict cookies
• Use HTTPS to protect credentials in transit (see SSL_SETUP.md and scripts under scripts/)
• Be cautious when exposing publicly (e.g. with ngrok) — enable auth and prefer HTTPS

🏗️ Tech Stack

• Frontend: React 18, TypeScript, Vite
• Markdown: react‑markdown + remark‑gfm; syntax highlighting
• Backend: Node.js + Express
• AI: openai SDK and @anthropic-ai/sdk
• Tunnel: @ngrok/ngrok (optional)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

See CONTRIBUTING.md for detailed guidelines.

📄 License

MIT — see LICENSE

📊 Project Status

• ✅ Stable and production‑ready
• 🔄 Actively maintained
• 🐛 Bug reports welcome
• 💡 Feature requests encouraged

🙏 Acknowledgments

• Inspired by VS Code's interface design
• Built with modern web technologies
• Thanks to the React and Node.js communities