From c0724e8537701454e7b95314bd9eb37c1d5cd2a9 Mon Sep 17 00:00:00 2001 From: kayjaydee Date: Tue, 21 Apr 2026 11:22:39 +0200 Subject: [PATCH] docs(05): capture phase context --- .../05-CONTEXT.md | 95 +++++++++++++++++++ .../05-DISCUSSION-LOG.md | 71 ++++++++++++++ 2 files changed, 166 insertions(+) create mode 100644 .planning/phases/05-nuxt-content-setup-renderer/05-CONTEXT.md create mode 100644 .planning/phases/05-nuxt-content-setup-renderer/05-DISCUSSION-LOG.md diff --git a/.planning/phases/05-nuxt-content-setup-renderer/05-CONTEXT.md b/.planning/phases/05-nuxt-content-setup-renderer/05-CONTEXT.md new file mode 100644 index 0000000..1a1fd99 --- /dev/null +++ b/.planning/phases/05-nuxt-content-setup-renderer/05-CONTEXT.md @@ -0,0 +1,95 @@ +# Phase 5: @nuxt/content Setup & Renderer - Context + +**Gathered:** 2026-04-21 +**Status:** Ready for planning + + +## Phase Boundary + +Installer et configurer `@nuxt/content` pour que le markdown rende fidèlement du contenu technique : blocs de code colorés, images optimisées, tableaux, callouts/alerts — sans configuration supplémentaire dans les phases suivantes. + +Cette phase ne crée pas encore les pages blog (Phase 6) ni les articles réels (Phase 8). Elle pose l'infrastructure de rendu. + + + + +## Implementation Decisions + +### Style du rendu markdown +- **D-01:** Utiliser `@tailwindcss/typography` (plugin officiel). Classe `prose dark:prose-invert` sur le wrapper `
`. Compatible Tailwind v4, support dark mode natif synchronisé avec `colorMode` existant. + +### Callouts / Alerts +- **D-02:** Implémenter via la syntaxe MDC de `@nuxt/content` — `::alert{type="warning"}` dans le markdown appelle un composant Vue dédié (`components/content/Alert.vue`). Aucun HTML brut dans les fichiers markdown. + +### Structure content/ +- **D-03:** Dossiers par langue : `content/fr/blog/` et `content/en/blog/`. Un fichier markdown par article par langue, avec le même slug. Aligné avec `@nuxtjs/i18n` strategy `prefix_except_default`. + +### Syntax highlighting +- **D-04:** Shiki intégré à `@nuxt/content` v3 (zéro dépendance supplémentaire). Langages à déclarer dans `nuxt.config.ts` : Kotlin, Java, TypeScript, Shell. Thème dark/light synchronisé avec `colorMode` du site. + +### Claude's Discretion +- Choix du thème Shiki exact (ex: `github-dark` / `github-light` ou variante) — cohérence avec la charte dark/light du site. +- Nombre et types de callouts MDC à créer au minimum (au moins : info, warning, tip). +- Frontmatter schema exact des articles (title, description, date, tags, image...) — à définir mais pas bloquant pour cette phase. + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Requirements +- `.planning/REQUIREMENTS.md` §BLOG-01, BLOG-04, BLOG-05 — exigences exactes de cette phase + +### Stack existant +- `nuxt.config.ts` — configuration actuelle (modules, i18n, colorMode, image) à étendre, ne pas réécrire +- `assets/css/main.css` — styles globaux existants, vérifier compatibilité avec prose Tailwind + +### Documentation externe (à consulter) +- `@nuxt/content` v3 docs : https://content.nuxt.com — installation, MDC syntax, ContentRenderer +- `@tailwindcss/typography` : https://tailwindcss.com/docs/typography-plugin — configuration prose + + + + +## Existing Code Insights + +### Reusable Assets +- `@nuxt/image` déjà installé et configuré → `` disponible pour les images dans les articles via MDC ou ContentRenderer +- `colorMode` configuré avec cookie (SSR-safe) → le thème Shiki doit répondre à `useColorMode().value` + +### Established Patterns +- Modules Nuxt déclarés dans `nuxt.config.ts` → ajouter `@nuxt/content` dans le tableau `modules` +- Composants auto-importés depuis `~/components` avec `pathPrefix: false` → les composants MDC dans `components/content/` seront auto-importés + +### Integration Points +- `nuxt.config.ts` → ajouter `@nuxt/content` dans `modules` + config `content: {}` + `shiki` langages +- `assets/css/main.css` → importer `@tailwindcss/typography` si nécessaire +- `components/content/` → dossier à créer pour les composants MDC (Alert, etc.) +- `content/fr/blog/` et `content/en/blog/` → à créer avec au moins 1 article de test Kotlin + + + + +## Specific Ideas + +- L'article de test (critère de succès) doit contenir un bloc Kotlin coloré, une image, un tableau et un callout — couvre les 4 success criteria de la phase. +- Le callout minimum pour valider : `::alert{type="info"}` rendant un composant stylisé Nuxt UI ou Tailwind. + + + + +## Deferred Ideas + +- Pages /blog et /blog/[slug] — Phase 6 +- SEO par article (useSeoMeta, JSON-LD Article) — Phase 7 +- Articles seed Hytale réels — Phase 8 +- Frontmatter complet avec og:image par article — Phase 7 + + + +--- + +*Phase: 05-nuxt-content-setup-renderer* +*Context gathered: 2026-04-21* diff --git a/.planning/phases/05-nuxt-content-setup-renderer/05-DISCUSSION-LOG.md b/.planning/phases/05-nuxt-content-setup-renderer/05-DISCUSSION-LOG.md new file mode 100644 index 0000000..2f30f43 --- /dev/null +++ b/.planning/phases/05-nuxt-content-setup-renderer/05-DISCUSSION-LOG.md @@ -0,0 +1,71 @@ +# Phase 5: @nuxt/content Setup & Renderer - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-04-21 +**Phase:** 05-nuxt-content-setup-renderer +**Areas discussed:** Style du rendu markdown, Callouts / Alerts, Structure content/, Syntax highlighting + +--- + +## Style du rendu markdown + +| Option | Description | Selected | +|--------|-------------|----------| +| @tailwindcss/typography | Plugin officiel Tailwind — classe `prose dark:prose-invert`, dark mode natif | ✓ | +| Nuxt UI prose styles | Via `UProse`, cohérent avec le design system existant | | +| CSS custom à la main | Tout écrire dans assets/css/ — contrôle total, effort élevé | | + +**User's choice:** @tailwindcss/typography +**Notes:** — + +--- + +## Callouts / Alerts + +| Option | Description | Selected | +|--------|-------------|----------| +| MDC Components | Syntaxe `::alert{type}` dans le markdown, composant Vue dédié | ✓ | +| HTML dans le markdown | `
` directement dans les .md | | + +**User's choice:** MDC Components +**Notes:** — + +--- + +## Structure content/ + +| Option | Description | Selected | +|--------|-------------|----------| +| content/fr/ + content/en/ | Un dossier par langue, aligné avec @nuxtjs/i18n | ✓ | +| content/blog/ avec champ locale | Fichiers `.fr.md` / `.en.md` dans un seul dossier | | + +**User's choice:** content/fr/ + content/en/ +**Notes:** — + +--- + +## Syntax highlighting + +| Option | Description | Selected | +|--------|-------------|----------| +| Shiki intégré | Zéro config, langues déclarées dans nuxt.config.ts, thème dark/light | ✓ | +| Prism | Alternative plus ancienne, moins performante | | + +**User's choice:** Shiki intégré +**Notes:** Langages prioritaires : Kotlin, Java, TypeScript, Shell + +--- + +## Claude's Discretion + +- Thème Shiki exact (dark/light) +- Types de callouts MDC à créer (minimum : info, warning, tip) +- Frontmatter schema des articles + +## Deferred Ideas + +- Pages /blog et /blog/[slug] → Phase 6 +- SEO par article → Phase 7 +- Articles Hytale réels → Phase 8