99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
## Project Overview
|
|
|
|
`datascape` is a minimal personal wiki where **the folder structure is the wiki**.
|
|
No database, no CMS, no abstraction layer — every folder is a page, and `index.md`
|
|
in a folder is that page's content.
|
|
|
|
## Build & Deploy
|
|
|
|
```bash
|
|
# Local build (host architecture)
|
|
go build .
|
|
|
|
# Deploy to NAS
|
|
make deploy
|
|
```
|
|
|
|
## HTTP API Surface
|
|
|
|
| Method | Path | Behaviour |
|
|
|--------|------|-----------|
|
|
| GET | `/{path}/` | If folder exists: render `index.md` + list contents. If not: show empty create prompt. |
|
|
| GET | `/{path}/?edit` | Mobile-friendly editor with `index.md` content in a textarea |
|
|
| POST | `/{path}` | Write `index.md` to disk; creates the folder if it does not exist yet |
|
|
|
|
Non-existent paths without a trailing slash redirect to the slash form (GET only — POSTs
|
|
are not redirected because `path.Clean` strips the trailing slash from `PostURL` and the
|
|
content would be lost).
|
|
|
|
Do not add new endpoints without a concrete stated need.
|
|
|
|
## Code Structure
|
|
|
|
When adding a new special folder type, create a new `.go` file. Do not add type-specific logic to `main.go` or `render.go`.
|
|
|
|
Prefer separate, human-readable `.html` files over inlined HTML strings in Go. Embed them via `embed.FS` if needed.
|
|
|
|
|
|
## Architecture Rules
|
|
|
|
- **Single binary** — no installer, no runtime dependencies, no Docker
|
|
- **Go stdlib `net/http`** only — no web framework
|
|
- **`goldmark`** for Markdown rendering — no other Markdown libraries
|
|
- **`embed.FS`** for all assets — no external serving, no CDN
|
|
- **No database** of any kind
|
|
- **No indexing or caching** unless explicitly requested and justified
|
|
- Keep dependencies to an absolute minimum; if stdlib can do it, use stdlib
|
|
|
|
## Frontend Rules
|
|
|
|
- Vanilla JS only — no frameworks, no build pipeline
|
|
- Each feature gets its own JS file; global behaviour goes in `global-shortcuts.js`
|
|
- Do not inline JS in templates or merge unrelated features into one file
|
|
- `ALT+SHIFT` is the modifier for all keyboard shortcuts — do not introduce others
|
|
- Editor toolbar buttons use `data-action` + `data-key`; adding `data-key` auto-registers the shortcut
|
|
|
|
### CSS / HTML — Pico CSS
|
|
|
|
[Pico CSS](https://picocss.com) is the styling framework. Strictly stay within it.
|
|
|
|
- Do not add other CSS frameworks, utility libraries, or icon fonts.
|
|
- Prefer pico's **class-less semantic HTML**: `<button>`, `<section>`, `<hgroup>`, `<header>`, `<nav><ul></ul></nav>`, `<details>`, etc. — let the element itself carry the styling.
|
|
- Use `<section>` for thematic blocks. Do **not** use `<article>` (project convention — always reach for `<section>` instead).
|
|
- Buttons: native `<button>` or `<a role="button">`. For variants use pico's modifiers (`.secondary`, `.contrast`, `.outline`) — do not invent new button classes. For button groups use `role="group"`.
|
|
- Layout: wrap top-level blocks in `.container` for the centered viewport. Use pico's `.grid` when a simple responsive grid is needed.
|
|
- Forms: rely on pico's default `<input>`/`<textarea>`/`<select>` styling; use `aria-invalid` for validation states.
|
|
- Custom CSS belongs in `style.css` and must only cover what pico does not provide. Reference pico's CSS custom properties (`var(--pico-border-color)`, `var(--pico-muted-color)`, `var(--pico-spacing)`, `var(--pico-card-background-color)`, etc.) — never hardcode colors or spacing.
|
|
- Prefer generic descriptive class names (`muted`, `danger`, `listing`, `diary-section`) over element-specific ones. Re-use existing classes before creating new ones.
|
|
- `pico.min.css` is the served stylesheet; keep `pico.css` around only as the unminified reference.
|
|
|
|
## Development Priorities
|
|
|
|
When building features, apply this order:
|
|
1. Correctness on the filesystem — never corrupt or lose files
|
|
2. Mobile usability (primary editing device is Android over Wireguard VPN)
|
|
3. Simplicity of implementation, adhere to KISS
|
|
4. Performance
|
|
|
|
## Date Formatting
|
|
|
|
- General UI dates (file listings, metadata): ISO `YYYY-MM-DD`
|
|
- Diary long-form dates: German locale, e.g. `Mittwoch, 1. April 2026` — use `formatGermanDate` in `diary.go`; Go's `time.Format` is English-only so locale names are kept in maps keyed by `time.Weekday` / `time.Month`
|
|
|
|
## What to Avoid
|
|
|
|
- Any parallel folder structure (e.g. a separate `media/` tree mirroring `pages/`)
|
|
- Over-engineering auth — Basic auth is sufficient for a personal VPN tool
|
|
- Heavy payloads or expensive rendering (target CPU: ARMv7 32-bit NAS)
|
|
- Suggesting Docker (plain binary is preferred)
|
|
|
|
## Out of Scope (do not implement unless explicitly asked)
|
|
|
|
- Full-text search
|
|
- Browser-based file upload
|
|
- Version history / git integration
|
|
- Multi-user support
|
|
- Tagging or metadata beyond `index.md` content
|