Add MkDocs documentation: architecture, deployment, development, decisions

2026-05-08 10:07:20 +02:00
parent fd2d81328f
commit ccec23c3a3
10 changed files with 591 additions and 102 deletions
@@ -0,0 +1,42 @@
+# Content Location (resolved)
+
+!!! success "Resolved"
+    Option A was implemented. Content lives in `pages/` and `blog/` at the container repo root. Astro loads them via glob loaders with `base: '../pages'` and `base: '../blog'`. Vite is configured with `server.fs.allow: ['..']`.
+
+---
+
+This document records the design question that was open during early development and the options considered.
+
+## The question
+
+Where should wiki content (the `.md` files the community edits) live, and how should Astro load them?
+
+The constraint: Astro's rendering engine lives in the `site/` submodule (`brutsalvadi/astro-bloomz`). Content is wiki-specific and should not be committed to the engine's history.
+
+## Why symlinks failed
+
+Symlinking `bincio_wiki/pages/` → `site/src/content/entries/` was tried and abandoned. macOS's `fsevents` (used by Vite's file watcher) does not follow symlinks reliably, causing Astro's hot-reload and content layer to miss changes or crash in dev mode.
+
+## Options considered
+
+**Option A — Astro glob `base` pointing outside `site/`** ✓ *chosen*
+
+```ts
+loader: glob({ pattern: '**/*.md', base: '../pages' })
+```
+
+`../pages` relative to `site/` resolves to `bincio_wiki/pages/`. No symlinks. Content stays in the container repo. Vite's `server.fs.allow: ['..']` is required to permit serving files outside the project root in dev.
+
+**Option B — Copy/sync at dev time**
+
+Keep source at `bincio_wiki/pages/`. Add a watcher step to `dev.sh` that syncs changes to `site/src/content/entries/` (gitignored there). Edit server already uses `WIKI_PAGES_DIR`.
+
+Downside: two-directory sync is extra moving parts; a crash means stale content.
+
+**Option C — Absorb Astro into `bincio_wiki`**
+
+Remove the submodule. Move Astro source into `bincio_wiki/src/`. Cleanest at runtime but loses the reusable engine submodule.
+
+## Outcome
+
+Option A works correctly. Both Vite's file watcher and Astro's content layer see changes to `pages/` and `blog/` in dev. The `contentDeleteWatcher` plugin handles the edge case of deleted files (which require clearing the data store to prevent stale entries).