kontra/docs/MEDIA-PLAN.md

Plan — Robust media: images co-located with articles, git-as-source-of-truth

Status: PROPOSED — awaiting your review, then I implement exactly this.

0. Problem statement (why we're here)

The S3/Garage + Decap-media path produced a fragile system: a wrong-signing SDK default, orphan attachments landing at repo root (aboutme.jpeg, webdevelopment.jpeg), a Decap media library that writes into git instead of S3, and no single robust place for images. We are dropping Garage S3 for Kontra media entirely. Images live as files in the content repo, co-located with their article — one source of truth, versioned, backed up, and served by the app.

1. Target layout (Option A — images with their article)

content/
└── subjects/
    └── world/
        ├── _subject.yaml
        ├── chinese-chips/
        │   ├── chinese-chips.md      ← article (same filename → same URL /articles/chinese-chips)
        │   ├── aboutme.jpeg          ← images beside their article
        │   └── hero.jpg
        ├── southern-harbor/
        │   ├── southern-harbor.md
        │   └── harbor.jpg
        └── river-border/
            └── river-border.md

• Slug is unchanged (from filename) — URLs /articles/<slug> stay identical.
• Obsidian's native setting ("attachments: same folder as current file") puts images beside the article automatically — no config drift, no stray files at repo root.
• Decap reads/writes the same git tree, so it sees the same folders (its image widget becomes a string {{media:...}}; no library files committed).
• App serves images at /media/<path> by reading the repo folder — a plain file server.

2. Why Option A over a top-level media/ folder

• Obsidian's default attachment behavior (same folder) needs zero configuration and cannot orphan files — the exact failure mode that created aboutme.jpeg at root.
• Each article is a self-contained folder (text + images): move/copy/archive in one step.
• Collisions impossible — filenames only clash within the same article.
• Serving complexity is identical to a central media folder (both are static file serving).

3. Changes required (minimal, mechanical)

1. Content repo
   • Migrate articles to folders: subjects/<s>/<slug>/<slug>.md (+ move their images in).
   • Move stray images (aboutme.jpeg, webdevelopment.jpeg) into their article folder.
   • Add content/.gitignore: nothing special (images are intentionally tracked now); but add .trash/ to gitignore so Obsidian's trash stops entering git.
   • Add /media-relevant note in _templates/article.md.
2. App loader (app/src/content.go)
   • Make article discovery recurse one level under each subject folder (currently non-recursive: *.md at subject root, _subject.yaml skipped). New rule:
     • subjects/<s>/<slug>.md (flat, existing) and subjects/<s>/<slug>/*.md (new).
     • Still skip _-prefixed files/dirs (config, templates).
   • Slug = filename without .md, unchanged.
3. App media route (app/src/main.go + handler)
   • Replace the Garage proxy: /media/{path...} → serve the file from <content>/subjects/<s>/<slug>/<path> or from the repo root media/ if any. Simplest robust: look up <content>/<path> in the content root (covers any location) with a safe-path guard (no ..), set Content-Type from extension.
   • Reference convention (DECIDED): full repo-relative path — {{media:chinese-chips/aboutme.jpeg}}. The app maps /media/{path...} → file relative to content root (safe-path guarded).
   • Remove /admin/media upload page + Garage upload endpoint + minio-go dependency (or keep minio-go for future — recommend removing to keep binary lean).
4. Front-matter/{{media:}}
   • {{media:chinese-chips/aboutme.jpeg}} → /media/chinese-chips/aboutme.jpeg → the app serves the file from the content root (safe-path guarded). Works for images in any folder (article folders, pages).
   • Obsidian/Decap reference images by the same repo-relative path: {{media:<slug>/<filename>}} for an image beside its article.
5. Cleanup
   • Delete real2.png (+ photonic-chips.png leftover) from bucket — irrelevant now (S3 dropped).
   • Remove the Garage bucket/key/kontra-day specific bits if unused elsewhere.
   • Update PLAN.md, DESIGN.md (media section), README.md, docs/OVERVIEW.md to the new model; remove S3/Decap-media claims.
6. Backups
   • Media now lives in the content git repo → backed up wherever the repo is: Gitea (.35) + production clone (.13) + the existing offsite/NAB backup chain.
   • No new backup config needed.

4. Migration steps (in order)

1. Commit a branch: move the 5 known articles into folders (+ images), update .gitignore.
2. Loosen the loader (change #2), build, verify all existing URLs return 200.
3. Swap the media route (change #3), build, verify {{media:...}} images serve from the repo.
4. Push → autosync pulls to .13 → rebuild container with new binary.
5. Remove the Decap media-library bits + S3 env from compose (or keep env unused).
6. Fix the test article's references; verify Obsidian + Decap + site all agree.
7. Update the docs (PLAN/DESIGN/README/OVERVIEW) and delete stale bucket artifacts.
8. Full end-to-end: edit image in Obsidian → push → live in ~30s; delete image → 404s.

5. Risks / notes

• The loader change (recurse one level) is the only behavioral change to content discovery; existing flat articles still work, so rollback is one revert.
• /media/<path> file serving must guard against path traversal (..) — handled in change #3.
• Obsidian trash: .trash/ is already in the repo (Obsidian's own folder) — gitignoring it stops it syncing to Gitea while keeping local trash.
• No secrets change; Gitea deploy token stays in .env (gitignored).

6. Out of scope (unless you ask)

• Reintroducing any S3/Garage for Kontra media.
• A browser-based media manager beyond the simple file page.
• Multi-editor auth beyond the existing Gitea/Obsidian workflow.