bincio-wiki/docs/architecture/content-model.md

Content Model

Collections

Astro 6 content collections are defined in site/src/content.config.ts. All three load files from outside the site/ submodule — Vite is configured with server.fs.allow: ['..'] to allow this.

Collection	Source directory	URL pattern
entries	pages/*.md	/entries/{slug}/
blog	blog/*.md	/blog/{slug}/
index	config/*.md	internal only (wikibonsai tree)

entries — wiki pages

Plain Markdown with minimal frontmatter:

---
title: Nome della pagina
---

Contenuto in markdown...

Slugs are derived from the filename minus extension. Subdirectory slugs are supported: pages/bincio-tech/gps-e-ciclocomputer.md → slug bincio-tech/gps-e-ciclocomputer → URL /entries/bincio-tech/gps-e-ciclocomputer/.

A generateId override in content.config.ts strips the .md extension and preserves slashes, so Astro does not apply any githubSlug mangling.

blog — stories and posts

Blog frontmatter is richer:

---
title: Titolo del post
description: Breve descrizione
pubDate: 2024-05-01
heroImage: /assets/foto.jpg   # optional
---

index — wikibonsai semantic tree

config/i.bonsai.md defines the hierarchical semantic tree used by the wikibonsai integration. It is not rendered as a page; Astro reads it to resolve [[WikiLink]] relationships and generate forward/back reference data.

Sections

config/sections.json defines the top-level wiki sections (e.g. BincioTech, BincioOfficina) and their subsections. This file is imported by:

• The Astro pages/entries index to group and display pages
• The PageEditor.svelte component to populate the section picker when creating a new page

Current sections: bincio-tech, bincio-officina, bincio-tour, bincio-corsa, bincio-abbigliamento.

WikiLinks and wikibonsai

Pages can reference each other with [[WikiLink]] syntax. The remark pipeline resolves these at build time:

1. remark-caml parses CAML attribute syntax in frontmatter.
2. remark-wikirefs resolves [[target]] to /entries/{slug}/ links using resolveHtmlHref and resolveHtmlText from site/src/wikibonsai/wikirefs.ts.
3. generateForeRefsRemarkPlugin collects all forward references so they can be stored in the content store.
4. Back-references (pages that link to the current page) are computed at build time in site/src/wikibonsai/backrefs.ts and rendered by the BackRefs.astro component.

Invalid wikilinks (targets that don't exist) are rendered as dimmed grey text rather than broken links.

Assets

User-uploaded images live in assets/ at the repo root. This directory is:

• Gitignored — not versioned, not part of any git commit.
• Served by FastAPI's StaticFiles mount at /assets/{filename} (nginx proxies /assets/ to FastAPI in production).
• Uploaded via POST /api/assets (multipart, images only, max 10 MB). The editor inserts ![name](/assets/filename) into the Markdown on upload.

On the VPS, assets are separate from the git push/pull cycle and must be managed independently if ever migrated.

Delete behaviour

Deleting a page via the editor calls DELETE /pages/{slug} or DELETE /stories/{slug}. The sidecar:

1. Unlinks the file.
2. Commits the deletion with git rm.

In Astro dev mode, a contentDeleteWatcher Vite plugin watches pages/ and blog/ for unlink events. When a .md file is deleted it clears .astro/data-store.json and restarts the Astro dev server, forcing a full re-scan. Without this, Astro's persisted data store would keep serving the deleted entry.