Initial configuration

The whole user configuration lives in one file: lisible.config.json at the repository root. Every field except variant is optional; whatever is absent falls back to a sensible default, so a fresh checkout builds unchanged.

The JSON schema referenced by $schema documents every field and powers editor autocompletion:

1
{
2
  "$schema": "./docs/lisible.config.schema.json",
3
  "variant": "organique",
4
  "site": {
5
    "title": "My blog",
6
    "url": "https://blog.example.com",
7
    "author": "Ada Lovelace",
8
    "accent": "#22C55E"
9
  },
10
  "social": { "github": "https://github.com/you" },
11
  "features": { "comments": false, "portfolio": { "friends": false } },
12
  "repo": { "url": "https://github.com/you/your-blog" }
13
}

The setup assistant writes this file for you; editing it by hand is equally supported.

Active variant

variant is the single required choice:

1
{
2
  "variant": "organique"
3
}

Public values: motion-primitives, cult-ui, aceternity, reactbits, organique, h4x0r. Deployment platforms can override it without touching the file through the LISIBLE_VARIANT environment variable.

Site identity

The site object defines the title, canonical URL, author, accent color, list sizes (postsPerPage, featuredCount) and default cover position. The social object holds the public profiles shown in the footer, and repo points edit links at your repository and branch.

Feature flags

The features object enables common capabilities. A flag controls more than presentation: it may gate routes, Markdown plugins and client assets, and a disabled feature leaves no trace in the built output. The complete reference lists every flag with its effect.

1
{
2
  "features": {
3
    "imageZoom": true,
4
    "mermaid": true,
5
    "ogPerPost": true,
6
    "pagination": { "enabled": true, "pageSize": 6 },
7
    "comments": false,
8
    "webmentions": false,
9
    "demoPlaceholders": true
10
  }
11
}

Integrations with secrets

Giscus, Bluesky or webmention.io identifiers belong in the integrations object. Never commit a private key. Public configuration values may stay in the repository, while secrets should come from environment variables. Enabling comments or webmentions without their configuration fails the build with a clear error.

A fresh clone displays fully local example comments and webmentions. Replace the profiles in social, fill the live integration, enable its flag, then set demoPlaceholders to false. This keeps third-party scripts and invalid network calls out of the development server.

Derived shared surfaces

shared/config.ts reads and validates lisible.config.json at build time; shared/site.config.ts and shared/features.ts only re-export values derived from it. You should never need to edit files under shared/ to configure a site: if a value seems missing, it belongs in the JSON file or in the schema, not in a shared module.

Final check

bun run variant
bun run build

The build is the reference validation: it traverses every route, the content schema, images, Markdown pipeline and Pagefind index.