snow-editor

small markdown and org-mode editor
Log | Files | Refs | README

README.md (2907B)

      1 # Snow Editor
      2 
      3 Markdown and Org-mode editor with live preview. Local drafts in `localStorage`. Shared docs via link + SQLite backend.
      4 
      5 Pablo Murad — pablomurad@pm.me
      6 
      7 ## Requirements
      8 
      9 - Node.js 22.5+
     10 - Docker + Compose (optional)
     11 
     12 ## Quick start
     13 
     14 ```bash
     15 cp .env.example .env
     16 docker compose up -d --build
     17 ```
     18 
     19 - Frontend: http://localhost:41737
     20 - API: http://localhost:41738/api/health
     21 - DB file: `./data/snow.db`
     22 
     23 ## Local dev
     24 
     25 Terminal 1:
     26 
     27 ```bash
     28 npm install
     29 npm run dev
     30 ```
     31 
     32 Terminal 2:
     33 
     34 ```bash
     35 cd backend && npm install && npm run dev
     36 ```
     37 
     38 Vite proxies `/api` to port 41738.
     39 
     40 ```bash
     41 npm run build
     42 npm run preview
     43 ```
     44 
     45 ## Tests
     46 
     47 ```bash
     48 cd backend && npm test
     49 npm test
     50 ```
     51 
     52 ## Config
     53 
     54 See `.env.example`. Main vars:
     55 
     56 - `SHARE_ALLOWED_ORIGINS` — who may `POST /api/documents` (default includes localhost:41737)
     57 - `VITE_PUBLIC_ORIGIN` — base URL for share links
     58 - `VITE_ALLOW_SEARCH_INDEXING` — `true`/`false` (rebuild after change)
     59 - `DATABASE_PATH` — SQLite path
     60 
     61 ## Routes
     62 
     63 - `/` — local editor
     64 - `/v/:token` — read-only shared view
     65 - `/e/:token` — shared edit (lock required to save)
     66 
     67 Share from `/`: pick title and expiry, get view + edit URLs.
     68 
     69 `POST /api/documents` needs a browser `Origin` on the allowlist. No origin → 403.
     70 
     71 Edit lock: one editor per doc, 2 min TTL, refreshed every 30s while tab is open.
     72 
     73 ## API
     74 
     75 ```
     76 GET    /api/health
     77 POST   /api/documents
     78 GET    /api/documents/view/:token
     79 GET    /api/documents/edit/:token
     80 POST   /api/documents/edit/:token/lock
     81 POST   /api/documents/edit/:token/lock/refresh
     82 DELETE /api/documents/edit/:token/lock
     83 PUT    /api/documents/edit/:token
     84 GET    /api/documents/edit/:token/versions?clientId=&lockToken=
     85 POST   /api/documents/edit/:token/versions/:versionId/restore
     86 ```
     87 
     88 Limits: 60 req/min per IP on `/api`, 10 req/min on `POST /api/documents`, 1 MB max body.
     89 
     90 Health returns `{ ok, db, uptime, version }`. DB down → 503.
     91 
     92 ## Stack
     93 
     94 React, Vite, Express, SQLite (`node:sqlite`), marked, Orga, CodeMirror 6, DOMPurify.
     95 
     96 ## Org-mode
     97 
     98 Parser: Orga. Editor: CodeMirror (highlight, fold, checklist toggle, outline on wide screens).
     99 
    100 Works: headings, lists, tables, TODO keywords, SRC/QUOTE blocks, basic inline markup, `#+TITLE`.
    101 
    102 Does not work: babel, agenda, LaTeX, full Emacs export. Not a replacement for Emacs.
    103 
    104 ## Backup
    105 
    106 Manual only. Stop backend first if copying live.
    107 
    108 ```bash
    109 ./scripts/backup-db.sh          # or backup-db.ps1
    110 docker compose stop backend
    111 ./scripts/restore-db.sh <file>  # or restore-db.ps1 -Backup <file>
    112 docker compose start backend
    113 ```
    114 
    115 Or copy `data/snow.db` yourself.
    116 
    117 ## Notes
    118 
    119 - No accounts. Edit links are capability tokens — anyone with the link can edit when unlocked.
    120 - No realtime collab.
    121 - Preview HTML is sanitized.
    122 - Monitor production with `GET /api/health`.
    123 - Rebuild Docker after changing `VITE_*` or `SHARE_ALLOWED_ORIGINS`.
    124 
    125 ## License
    126 
    127 Use freely for personal projects and learning.