@monark_it/mch-create-blog

Scaffolder du blog Monark pour une application Next.js (App Router). Une commande écrit les fichiers du site, connect associe le site au Monark Content Hub, customize éjecte les composants à personnaliser. Toute la logique vit dans @monark_it/mch-blog : une mise à jour se fait par npm install.

1. Le blog en 30 secondes

• Hub → release → site. Vous publiez dans le Hub ; le site lit la release et sert /blog.
• Aucun contenu local : pas d'articles, pas d'images, pas de fichier de configuration produit.
• Le CLI écrit des fichiers, rien de plus : aucune commande git n'est exécutée. Committez les fichiers générés avant de déployer.
• Relançable sans risque : un fichier existant n'est jamais écrasé sans choix, et --dry-run prévisualise tout.

Ce qu'un site équipé contient :

| Élément | Fichier | Rôle | | ------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------- | | Wrappers (5) | app/blog/layout.tsx, page.tsx, [slug]/page.tsx, rss.xml/route.ts, app/sitemap.ts | rendu, SEO, RSS, sitemap — importent le package | | Route Hub | app/api/mch/[...path]/route.ts | hello, revalidate, well-known | | Registry | app/blog/_overrides/index.ts | composants personnalisés (slots) |

npm install @monark_it/mch-blog@latest met à jour le rendu, le SEO et la revalidation : les wrappers du site ne changent pas.

2. Démarrage (5 étapes)

Dans le dossier de l'application Next (celui qui contient package.json, souvent web/) :

# 1. wrappers, registry et variables du site, puis installer la dépendance
npx @monark_it/mch-create-blog
npm install

# 2. associer le site au Hub : approuver le code affiché dans le Hub, page /connect
npx @monark_it/mch-create-blog connect --url https://exemple.com

# 3. copier les 6 variables MCH_* listées par connect dans la plateforme d'hébergement
# 4. déployer
# 5. publier un article depuis le Hub, ouvrir /blog

Questions posées à l'initialisation :

| Question | Explication | Exemple | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | Site key | identifiant court et stable (minuscules, chiffres, tirets) ; sert de titre par défaut et de namespace, ne plus le changer après publication | journal | | Base URL | origine publique, pour liens absolus, RSS et canonicals | https://exemple.com | | Blog route | chemin public du blog, hors segment de locale | /blog | | Locale | locale du contenu (format court) | fr | | Enable RSS? | générer /blog/rss.xml | Y |

Mode non interactif (CI) :

npx @monark_it/mch-create-blog --yes \
  --site-key journal \
  --base-url https://exemple.com \
  --locale fr \
  --blog-route /blog

3. Commandes

3.1 mch-create-blog (init) — wrappers et variables du site

Écrit : app/blog/layout.tsx, page.tsx, [slug]/page.tsx, rss.xml/route.ts, app/sitemap.ts, le registry app/blog/_overrides/index.ts, .env.local et .env.example (4 variables du site), et la dépendance @monark_it/mch-blog dans package.json. Les sitemap et middleware next-intl existants sont patchés s'ils sont reconnaissables.

| Option | Défaut | Effet | | --------------------- | ------- | ------------------------ | | --site-key <key> | — | clé du site | | --base-url <url> | — | origine publique absolue | | --blog-route <path> | /blog | chemin public du blog | | --locale <locale> | fr | locale du contenu | | --rss / --no-rss | --rss | flux RSS | | --dry-run | false | affiche sans écrire | | --yes | false | non interactif (CI) | | --help, --version | — | aide, version |

3.2 connect — association au Hub

Écrit : package.json#mch (hubUrl, siteId, bindings), .env.local et .env.example (2 variables Hub), app/api/mch/[...path]/route.ts, la visibilité /.well-known/mch-release (rewrite next.config ou route dédiée), et le registry _overrides s'il manque (avec migration des wrappers historiques).

| Option | Défaut | Effet | | --------------------- | -------------------------------------- | ------------------------------------------------------ | | --hub-url <url> | interactif : https://hub.exemple.com | URL du Hub | | --url <url> | — | URL publique de production (binding) | | --preview-url <url> | — | URL de préversion (binding staging) | | --force | false | nouveau code d'association malgré un manifest existant | | --yes | false | non interactif | | --help | — | aide |

Le code d'association s'approuve dans le Hub, page /connect, par un administrateur du site. Le binding production est vérifié automatiquement après déploiement (première revalidation acceptée ou vérification de visibilité) : aucune commande à lancer après le déploiement.

3.3 customize (alias override) — composants personnalisés

Écrit : les fichiers éjectés dans app/blog/_overrides/<Slot>/ et la mise à jour du registry app/blog/_overrides/index.ts. Détail des 7 emplacements et recettes : README de @monark_it/mch-blog, §4.2.

| Option | Effet | | ------------- | ------------------------------------------------------------ | | --list | liste les emplacements, sans écrire | | --slot <id> | éjecte un emplacement (répétable ou séparé par des virgules) | | --force | réécrit un composant déjà éjecté (sans confirmation) | | --dry-run | affiche sans écrire | | --help | aide |

4. Personnalisation

Tout se règle sans toucher aux pages.

1. Design — dans le Hub, onglet Design : couleurs, typographie, cartes, liste, largeur, mode sombre, Markdown. Aperçu live, contrastes AA vérifiés.
2. Composants — npx @monark_it/mch-create-blog customize éjecte un composant, le registry le branche, vos modifications sont prises en compte. Le Hub est prévenu automatiquement (bandeau « Composants personnalisés » dans Design) : rien à déclarer à la main.
3. Page headless — pour une page 100 % custom, resolveBlogContent donne le contenu et le design.

Guide complet et recettes : README de @monark_it/mch-blog, §4.

5. Variables d'environnement

| Variable | Écrite par | Rôle | | ----------------- | ---------- | ------------------------------------------ | | MCH_SITE_KEY | init | identifiant du site, titre par défaut | | MCH_BASE_URL | init | origine publique (canonical, RSS, JSON-LD) | | MCH_BLOG_PATH | init | chemin public du blog | | MCH_LOCALE | init | locale des dates | | MCH_HUB_URL | connect | Hub qui publie la release | | MCH_HUB_SITE_ID | connect | identifiant du site dans le Hub |

• Local : .env.local (écrit par le CLI), et .env.example pour la référence.
• Production : copiez les 6 variables dans la plateforme d'hébergement (connect les liste).
• Serveur uniquement : jamais de préfixe NEXT_PUBLIC_. Modifier une valeur exige un rebuild.
• Préversion : ajoutez MCH_HUB_ENV=staging au déploiement de staging.

6. Comprendre le rendu

• Les wrappers sont statiquement analysables par Next : metadata, generateMetadata et generateStaticParams sont déclarés localement, jamais des ré-exports.
• La route API unique sert hello (vérification), revalidate (webhook signé) et well-known (visibilité de la release et composants personnalisés).
• Les images viennent du Hub en URLs absolues : aucune route locale n'est nécessaire.
• Entrées du package : @monark_it/mch-blog/next (serveur, pages et routes), @monark_it/mch-blog/ui (navigateur, composants et thème), styles.css (styles mch-*).
• Patchs automatiques et idempotents : exclusion de la route blog du middleware next-intl (sinon redirection 404 vers /<locale>/blog), intégration du sitemap, nettoyage des artefacts d'anciennes générations. Un patch impossible est signalé avec le snippet à coller.

Référence complète : README de @monark_it/mch-blog, §6.

7. Dépannage

| Symptôme | Cause | Action | | ----------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- | | package.json introuvable | lancé hors du dossier de l'app Next | se placer dans le dossier de l'app Next (celui qui contient package.json, souvent web/) | | APP_ROUTER_NOT_FOUND | pas d'app/ (ou src/app/) avec layout racine | créer l'App Router avant de relancer | | Code d'association expiré ou refusé | approbation trop tardive | relancer connect pour obtenir un nouveau code | | Le binding production a changé | l'URL enregistrée diffère | relancer connect --force --url <url> | | /blog vide | variables absentes ou aucune release publiée | vérifier les 6 MCH_*, publier depuis le Hub | | Article pas à jour | webhook non reçu, cache ou rebuild manquant | vérifier le binding dans le Hub ; rebuild après un changement de variable | | Image manquante | média non publié ou variables Hub absentes | republier le média ; définir MCH_HUB_URL et MCH_HUB_SITE_ID | | Composant éjecté absent du bandeau Design | le Hub n'a pas encore échangé avec le site | attendre le prochain échange ; route ancienne : relancer init/connect |

8. Migration (anciens sites)

Pour un site d'une génération précédente (config fichier, scope @barry_monarkit, dossier images/blog), relancez :

npx @monark_it/mch-create-blog
npx @monark_it/mch-create-blog connect --url https://exemple.com

Les wrappers historiques sont migrés vers le registry _overrides, les artefacts des générations précédentes sont nettoyés, et vos composants modifiés sont conservés.