markdown-web/README.md

A modern, browser-based markdown editor that you can run in any directory. Edit .md files with live preview, auto-save, and a VS Code-inspired interface.

# Markdown Web Editor

[![npm version](https://badge.fury.io/js/markdown-web.svg)](https://badge.fury.io/js/markdown-web)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)

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)
```bash
npx markdown-web
```

### Or install globally
```bash
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`)

```bash
# 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:

```bash
# 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](CONTRIBUTING.md) for detailed guidelines.

## 📄 License

MIT — see [LICENSE](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