Discover Lisible
Architecture
The architecture strictly separates shared behavior from visual expression. This rule prevents SEO, i18n or editorial fixes from being repeated six times.
Directory tree
lisible/├─ lisible.config.json├─ package.json├─ scripts/├─ tests/├─ e2e/├─ packages/│ ├─ lisible/│ └─ create-lisible/├─ shared/│ ├─ config.ts│ ├─ site.config.ts│ ├─ features.ts│ ├─ variants.ts│ ├─ assets/│ ├─ components/│ ├─ content/│ ├─ integrations/│ ├─ lib/│ ├─ markdown/│ ├─ preview/│ ├─ routes/│ ├─ scripts/│ ├─ print.css│ └─ public/└─ versions/ ├─ _core/ ├─ motion-primitives/ ├─ cult-ui/ ├─ aceternity/ ├─ reactbits/ ├─ organique/ └─ h4x0r/Responsibilities
| Surface | Owner | Examples |
|---|---|---|
| Configuration | lisible.config.json | variant, identity, flags, integrations |
| Content | shared/content/ | posts, schema, images |
| Identity | shared/site.config.ts | values derived from the configuration |
| Capabilities | shared/features.ts | flags derived from the configuration |
| Shared UI | shared/components/ | appearance, preview bridge, profile hero, file tree |
| Browser runtime | shared/scripts/ | locale, cards, diagram full screen |
| Preview contract | shared/preview/ | build base, settings protocol, frame navigation |
| Shared routes | shared/routes/ | home, blog, tags, RSS |
| Content pipeline | shared/lib/ | post queries, formatting, RSS, llms.txt, Open Graph |
| Build integrations | shared/integrations/ | self-hosted KaTeX assets |
shared/print.css | paper rendering and PDF export | |
| Design | versions/*/src/ | layouts, components, animation |
| Orchestration | scripts/ | init, global preview, checks |
| Tests | tests/, e2e/ | unit tests, Playwright end-to-end suite |
| Scaffolding | packages/ | the lisible and create-lisible npm CLIs |
Post flow
sequenceDiagram participant M as Markdown participant C as Content collection participant L as Variant layout participant B as Astro build participant P as Pagefind M->>C: frontmatter + body C->>L: typed entry L->>B: HTML + metadata B->>P: static pages P-->>B: search index
The role of _core
versions/_core is the functional reference. The six public variants may use different components, but they must preserve the shared route baseline, data, error states and accessibility requirements.
A variant may add a showcase route when it stays additive and ships a complete FR/EN pair. Organique’s Certifications and Friends pages follow that rule: they do not replace Home, Blog, Tags, Archives, Series or About.
Preview boundary
PreviewBridge.astro and shared/preview/ are inert in a normal Lisible build. The documentation builder enables them with LISIBLE_PREVIEW=1, assigns each variant an isolated /_previews/<variant>/ base and exchanges validated settings and navigation messages with the parent previewer. This keeps preview-only noindex metadata, content switches and URL rewriting out of deployed reader sites.
Initial configuration describes shared surfaces and Themes and variants formalizes the presentation contract.
Imports and aliases
Astro source uses two aliases and only two: @/* points to src/* and @shared/* to shared/*. Shared MDX components therefore use imports such as @shared/components/ui/file-tree, and source modules never navigate upward with ../.
Modules loaded directly by astro.config.ts are the exception: configuration is evaluated before aliases are available, so they use relative paths. That covers the remark and rehype plugins, the language badge and the dictionaries the configuration imports.
The repository is a Bun workspace covering shared, versions/* and packages/*. The shared core is the @lisible/shared package; every variant depends on it with workspace:*, and a single root bun install links all of them. Each package declares the dependencies it actually uses in its own package.json instead of relying on accidental root resolution.