ui redesign, markdown fix + metadata and auth header

2026-05-09 05:09:07 +02:00
parent 7f8a66f360
commit bc6a34cf1f
42 changed files with 3093 additions and 517 deletions
@@ -0,0 +1,101 @@
+# Narlblog
+
+A single-author blog. Rust/Axum API backed by markdown files on disk; Astro/React frontend with a glass-effect Catppuccin theme. KaTeX math, GFM tables, server-side syntax highlighting, draft posts, RSS feed.
+
+```
+backend/   Rust + Axum API (filesystem-backed)
+frontend/  Astro + React, SSRs pages and proxies /api/*
+data/      Runtime data — posts, uploads, config.json (host volume)
+```
+
+## Quick start
+
+```sh
+cp .env.example .env
+# Generate a strong admin token:
+echo "ADMIN_TOKEN=$(openssl rand -hex 32)" >> .env
+
+docker compose up --build
+# → http://localhost:4321
+# → log in at /admin/login with the token from .env
+```
+
+Make sure the `data/` host directory is owned by UID 1000 (the backend container's app user):
+
+```sh
+sudo chown -R 1000:1000 data/
+```
+
+## Environment
+
+| Variable          | Required | Default           | Notes                                                                       |
+| ----------------- | -------- | ----------------- | --------------------------------------------------------------------------- |
+| `ADMIN_TOKEN`     | yes      | —                 | Long random string. Stored as an HttpOnly cookie after login.               |
+| `PORT`            | no       | `3000`            | Backend port.                                                               |
+| `DATA_DIR`        | no       | `/app/data`       | Where posts/uploads/config live.                                            |
+| `COOKIE_SECURE`   | no       | `true`            | Set `false` only for local HTTP development.                                |
+| `FRONTEND_ORIGIN` | no       | _empty_           | Set to your frontend's URL only if you expose the backend directly.         |
+| `RUST_LOG`        | no       | `info`            | tracing-subscriber filter.                                                  |
+| `PUBLIC_API_URL`  | no       | `http://backend:3000` | Backend URL the Astro proxy hits server-to-server.                       |
+
+## Local development
+
+Backend:
+
+```sh
+cd backend
+ADMIN_TOKEN=devtoken COOKIE_SECURE=false DATA_DIR=../data cargo run
+```
+
+Frontend (separate terminal, Node ≥ 22.12):
+
+```sh
+cd frontend
+npm install
+npm run dev
+# → http://localhost:4321 (proxies to PUBLIC_API_URL, default http://backend:3000)
+```
+
+For a fully local stack, set `PUBLIC_API_URL=http://localhost:3000` in `frontend/.env`.
+
+## Authoring posts
+
+Posts are markdown files at `data/posts/<slug>.md` with YAML frontmatter:
+
+```markdown
+---
+date: 2026-05-09
+summary: Optional summary; falls back to auto-extracted excerpt.
+tags:
+  - rust
+  - astro
+draft: false
+---
+# My post
+
+Body in **markdown**, with $LaTeX$ via `$…$` / `$$…$$`, GFM tables, and fenced code blocks (```rust, ```ts, …).
+```
+
+Posts with `draft: true` are hidden from the public list and 404 when accessed by anyone without an admin session. Posts are sorted by `date` descending on the frontpage.
+
+The web editor at `/admin/editor` writes the same format and updates atomically (write to `.tmp`, rename over target).
+
+## Uploads
+
+Allowlisted extensions: jpg, jpeg, png, webp, gif, avif, pdf, txt, md, mp3, wav, ogg, mp4, webm, mov. Magic bytes are checked against the extension. SVG and HTML are intentionally rejected — `/uploads/*` is served as-is, so any active content there would be XSS.
+
+Max upload size: 50 MB.
+
+## Backups
+
+The deployed `data/` directory is the entire blog. Back it up with whatever you trust — `rsync`, restic, borg, a sidecar container; nothing fancy is built in.
+
+```sh
+rsync -av data/ backup-host:/path/to/narlblog-data/
+```
+
+## Stack
+
+- **Backend**: axum 0.8, serde_yaml frontmatter, subtle constant-time auth, infer for upload sniffing
+- **Frontend**: Astro 6, React 19, Tailwind 4, marked + marked-katex-extension + marked-highlight + DOMPurify
+- **Editor**: CodeMirror 6 with vim mode and asset autocomplete