brutsalvadi
103 lines
3.6 KiB
Markdown
103 lines
3.6 KiB
Markdown
---
|
|
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?
|