Configuration initiale

Toute la configuration utilisateur vit dans un seul fichier : lisible.config.json à la racine du dépôt. Chaque champ sauf variant est facultatif ; toute valeur absente retombe sur un défaut raisonnable, donc un clone frais se construit tel quel.

Le schéma JSON référencé par $schema documente chaque champ et alimente l’autocomplétion de l’éditeur :

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

L’assistant d’installation écrit ce fichier pour vous ; l’éditer à la main est tout aussi supporté.

Variante active

variant est le seul choix obligatoire :

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

Valeurs publiques : motion-primitives, cult-ui, aceternity, reactbits, organique, h4x0r. Les plateformes de déploiement peuvent la surcharger sans toucher au fichier via la variable d’environnement LISIBLE_VARIANT.

Identité du site

L’objet site définit le titre, l’URL canonique, l’auteur, la couleur d’accent, les tailles de listes (postsPerPage, featuredCount) et la position de couverture par défaut. L’objet social regroupe les profils publics affichés dans le pied de page, et repo pointe les liens d’édition vers votre dépôt et votre branche.

Fonctionnalités

L’objet features active les capacités communes. Un flag ne change pas seulement l’affichage : il peut contrôler des routes, des plugins Markdown et des assets client, et une fonctionnalité désactivée ne laisse aucune trace dans le site construit. La référence complète liste chaque flag avec son effet.

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
}

Intégrations à secrets

Les identifiants Giscus, Bluesky ou webmention.io se placent dans l’objet integrations. Ne commitez jamais une clé privée. Les valeurs publiques de configuration peuvent rester dans le dépôt, mais les secrets doivent venir de variables d’environnement. Activer comments ou webmentions sans leur configuration fait échouer le build avec une erreur claire.

Le clone neuf affiche des commentaires et webmentions d’exemple entièrement locaux. Remplacez les profils de social, renseignez l’intégration réelle, activez son flag, puis passez demoPlaceholders à false. Ainsi, aucun script tiers ni appel réseau invalide ne pollue le serveur de développement.

Surfaces partagées dérivées

shared/config.ts lit et valide lisible.config.json au build ; shared/site.config.ts et shared/features.ts ne font que réexporter des valeurs qui en dérivent. Vous ne devriez jamais avoir à éditer un fichier de shared/ pour configurer un site : si une valeur semble manquer, sa place est dans le fichier JSON ou dans le schéma, pas dans un module partagé.

Contrôle final

bun run variant
bun run build

Le build est la validation de référence : il parcourt toutes les routes, le schéma de contenu, les images, le pipeline Markdown et l’index Pagefind.