Complete reference

This page gathers Lisible’s public contract. Previous chapters explain the decisions; this reference lists expected values.

Post frontmatter

Field	Type	Default	Purpose
`title`	`string` ≤ 70	required	title, SEO and lists
`description`	`string` ≤ 160	required	summary and metadata
`pubDate`	date	required	sorting and publication
`updatedDate`	date	absent	latest update
`tags`	`string[]`	`[]`	filters and related posts
`draft`	`boolean`	`false`	production exclusion
`cover`	path or URL	absent	cover image
`coverAlt`	`string`	absent	cover alternative
`featured`	`boolean`	`false`	home pinning
`series`	`string`	absent	series identifier
`seriesOrder`	`number`	absent	order in series
`bluesky`	`at://` URI	absent	per-post discussion

lisible.config.json

The whole user configuration lives in lisible.config.json at the repository root, validated by shared/config.ts and documented by the JSON schema in docs/lisible.config.schema.json. Every field except variant is optional.

Field	Type	Purpose
`$schema`	`string`	schema path powering editor autocompletion
`variant`	`string`, required	active variant among the six public ids
`site.title`	`string`	site name in headers, feeds and metadata
`site.url`	`string`	canonical URL with protocol
`site.author`	`string`	author credited in metadata and JSON-LD
`site.accent`	`string`	default accent color, hex
`site.postsPerPage`	`number`	pagination size for lists
`site.featuredCount`	`number`	featured posts on the home page
`site.coverPosition`	`string`	default cover crop position
`social.*`	`string`	`github`, `bluesky`, `mastodon`, `linkedin`, `email` profiles
`features.*`	booleans and objects	the flags listed below
`integrations.webmentions.domain`	`string`	webmention.io domain
`integrations.comments.provider`	`string`	`giscus` or `bluesky`
`integrations.comments.giscus`	object	`repo`, `repoId`, `category`, `categoryId`, `mapping`
`integrations.comments.bluesky`	object	default `postUri`
`repo.url`, `repo.branch`	`string`	repository behind edit links

Feature flags

Flags live in the features object of lisible.config.json. A disabled feature leaves no trace in the built output.

Flag	Main effect
`callouts`	note/tip/warning/caution/important directives
`mdxComponents`	Tabs, Steps and Spoiler
`imageZoom`	full-screen image viewer
`headingAnchors`	copyable h2 to h4 anchors
`relatedPosts`	recommendations by tag similarity
`math`	remark-math and KaTeX
`mermaid`	interactive diagrams with zoom, pan and full screen
`drawio`	draw.io viewer with zoom, pan and full screen
`ogPerPost`	OG image per post and locale
`llmsTxt`	index, corpus and exported Markdown
`aiButtons`	copy Markdown and open AI-assisted reading actions
`socialShare`	sharing intents
`styledRss`	feed XSL stylesheet
`webmentions`	webmention.io reactions
`comments`	Giscus or Bluesky
`demoPlaceholders`	local preview of comments, social profiles and webmentions
`newPostCli`	post scaffolder
`linkCheck`	link validation
`covers`	cover display
`pinned`	raise `featured` posts
`pagination`	paginated routes and `pageSize`
`archives`	publication timeline
`series`	series pages and navigation
`commandPalette`	search and Ctrl/Cmd+K actions
`portfolio`	`enabled`, `certifications` and `friends` showcase toggles

The shared Tree component is imported directly from @shared/components/ui/file-tree and has no separate feature flag.

French and English routes

French	English
`/`	`/en/`
`/about`	`/en/about`
`/blog`	`/en/blog`
`/blog/<page>`	`/en/blog/<page>`
`/blog/<slug>`	`/en/blog/<slug>`
`/blog/<slug>.md`	`/en/blog/<slug>.md`
`/tags`	`/en/tags`
`/tags/<tag>`	`/en/tags/<tag>`
`/tags/<tag>/<page>`	`/en/tags/<tag>/<page>`
`/archives`	`/en/archives`
`/archives/<page>`	`/en/archives/<page>`
`/series`	`/en/series`
`/series/<slug>`	`/en/series/<slug>`
`/rss.xml`	`/en/rss.xml`

Global routes: /sitemap-index.xml, /robots.txt, /llms.txt, /llms-full.txt, /og/... and /pagefind/....

Organique showcase routes

French	English	Scope
`/certifications`	`/en/certifications`	fictional badges and the shared three-post certification series
`/friends`	`/en/friends`	local demo blogroll

These two pairs are additive Organique demonstrations, not shared baseline routes. They must remain bilingual and must not be assumed available after switching to another variant.

Root commands

init            guided setup
dev             active variant server
build           active variant build
preview         active build preview
variant         print the variant
preview:all     install, build and serve all six variants
new-post        create MDX by default, or Markdown on request
check-links     validate content links
check-assets    apply asset budgets
check-variants  full validation of the named variants
check:all       style, conformance, typecheck, build and output checks, all seven variants
typecheck       astro check across the seven variants
test            unit tests for the shared helpers
test:e2e        Playwright suite against built variants
lint            Biome lint and format check
format          apply Biome formatting
check-style     no long dashes, no emoji in documentation
check-drift     compare built HTML with the saved baseline
sync-og-assets  regenerate the shared Open Graph assets
check-og-assets verify the Open Graph assets are in sync
check-og-output validate the generated Open Graph images