bincio-wiki/docs/content-location.md

title

title
Content location and structure

Content location and structure

Two open design questions about where wiki content lives and how it can be organised on disk.

---

Q1 — Content in site/ vs bincio_wiki/

The tension

Ideally wiki content (the .md files the community edits) would live in bincio_wiki/, the container repo. The Astro app is a reusable engine; content is wiki-specific. Mixing them means content commits go into the astro-bloomz submodule history, and updating the engine requires care not to disturb content.

Currently content is at site/src/content/entries/ (inside the submodule).

Why symlinks failed

Symlinking bincio_wiki/pages/ → site/src/content/entries/ was tried but 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.

Options

Option A — Astro glob base pointing outside site/

Change content.config.ts to use a relative or absolute path that escapes the site/ directory:

loader: glob({ pattern: '**/*.md', base: '../pages' })

../pages from the Astro project root (site/) resolves to bincio_wiki/pages/. No symlinks. Content stays in the container repo.

Risk: Vite (which Astro uses internally) may refuse to watch files outside the project root by default. This can be overridden with server.watch.ignored / server.fs.allow in astro.config.mjs, but needs testing. Build-time collection (no watch) is likely fine regardless.

Option B — Copy/sync at dev time

Keep content source at bincio_wiki/pages/ (source of truth). Add a step to dev.sh that watches pages/ and syncs changes to site/src/content/entries/ (gitignored there). Build step copies before astro build.

Edit server already reads WIKI_PAGES_DIR from the environment, so pointing it at bincio_wiki/pages/ is a one-line change. The sync is the only new piece.

Downside: a two-directory sync is extra moving parts; a crash or missed sync during dev means stale content in the browser.

Option C — Absorb Astro app into bincio_wiki

Remove the submodule entirely. Move Astro source into bincio_wiki/src/. Content and engine live together, content at src/content/entries/.

Cleanest at runtime, but loses astro-bloomz as a reusable starting point for other sites. Only worth it if we never intend to fork the engine again.

Recommendation

Try Option A first — it is a two-line change and, if Vite's file watcher cooperates, gives us exactly the right separation with minimal risk. If the watcher proves problematic in dev, fall back to Option B.

---

Q2 — Subdirectory support in the edit panel

Current state

The backend already handles subdirectory slugs fully:

• _SAFE_SLUG regex allows / in slugs
• Routes use {slug:path} so FastAPI preserves slashes
• _list() uses rglob("*.md") — nested files are already listed
• _save() calls path.parent.mkdir(parents=True, exist_ok=True)

The frontend edit panel, however, only offers flat slug input. Work needed:

• Allow the "new page" field to accept a slug with / (e.g. archivio/2024/festa)
• Show nested entries grouped by prefix in the page list
• Possibly add a folder picker or breadcrumb

Pictures

Not yet addressed. Open questions:

• Where are images stored? (options: site/public/img/, alongside content, or a dedicated bincio_wiki/assets/ tree)
• How does the edit panel upload/reference them?
• How are they referenced from markdown (/img/foo.jpg vs relative ./foo.jpg)?
• Are images versioned in git or stored out-of-band?