Mosaic

The folder
IS the website.

A folder format for structured content. Three rules. Any conforming reader turns the folder into a site.

Explore the matrix Read the spec

content/

mosaic.json

pages/

about.json

blog/

hello.md

hello.json

team/

ada.json

example.com/about

Switch readers — content stays.

The spec

Three rules. Nothing more.

RULE 01

A file is a record.

.json files hold structure. .md, .pdf, .png are opaque payloads. Metadata goes in a same-named .json sidecar.

# structured about.json → record # opaque + sidecar hello.md hello.json → sidecar

RULE 02

A folder is a collection.

Any directory is a collection. Folders nest freely. index.json inside a folder is that folder's record.

# team/ is a collection team/ index.json → team ada.json → team/ada grace.md grace.json → team/grace

RULE 03

The filename is the contract.

Names follow name[.modifier]*.ext. File form and folder form are the same identity — no rename, no broken refs.

# same identity: about about.json about/index.json → identical # locale modifier about.fr.md → locale fr

Why Mosaic

Three things you get from day one.

OWN IT

Your content is plain files.

Git tracks them. cat reads them. No proprietary database, no export script, no vendor. Move the folder — the site moves with it.

SWITCH FREELY

Frameworks are interchangeable.

Today Astro. Tomorrow Next. Next year a Rust thing not invented yet. Same folder, different reader — the content stays.

FOUND BY MACHINES

SEO + AI ready, built in.

JSON-LD via @type. OpenGraph + Twitter via meta:. Crawlers and LLMs read the same JSON your renderer does. No plugin layer.

Adopt

Four lines into Astro.

Same shape in Next via @ssolu/mosaic-next. Same shape in any future adapter.

// astro content.config.ts import { defineCollection } from 'astro:content'; import { mosaicLoader } from '@ssolu/mosaic-astro'; export const collections = { pages: defineCollection({ loader: mosaicLoader({ root: './content' }) }), };

Walks your folder, resolves sidecars + refs + cascade, hands Astro a Content Layer collection. Zero runtime deps.

Validate

Drop a folder. Get the verdict.

Runs @ssolu/mosaic-validator-web right here in the page — same §§5–9 rules as the Node CLI and the Python validator. Nothing leaves the browser.

Don't have a folder handy? Clone the repo and drop any of spec/examples/{A,B,C,D,E}/content/.

Explore

Pick a path.

Live

See it run

Six deployed sites — three content shapes (single, blog, full) crossed with two adapters (Astro, Next).

Open the matrix →

Spec

Read the rules

Format, references, cascade, profiles. Small and frozen.

Open spec →