---
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:

```ts
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?