docs(05): add detailed pattern map for @nuxt/content setup and renderer
- Introduced a new document outlining the configuration and component patterns for integrating @nuxt/content. - Included mappings for `nuxt.config.ts`, `content.config.ts`, and new components `ProseImg.vue` and `Alert.vue`. - Added example markdown content for testing syntax highlighting and layout. - Documented critical patterns and anti-patterns to follow during implementation.
This commit is contained in:
@@ -0,0 +1,372 @@
|
|||||||
|
# Phase 5: @nuxt/content Setup & Renderer — Pattern Map
|
||||||
|
|
||||||
|
**Mapped:** 2026-04-21
|
||||||
|
**Files analyzed:** 7 (2 modifications + 5 créations)
|
||||||
|
**Analogs found:** 5 / 7
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Classification
|
||||||
|
|
||||||
|
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| `nuxt.config.ts` | config | — | `nuxt.config.ts` (lui-même, existant) | exact — extension |
|
||||||
|
| `content.config.ts` | config | CRUD | `nuxt.config.ts` (structure `defineNuxtConfig`) | role-match |
|
||||||
|
| `app/assets/css/main.css` | config | — | `app/assets/css/main.css` (lui-même, existant) | exact — extension |
|
||||||
|
| `app/components/content/ProseImg.vue` | component | request-response | `app/components/ProjectCard.vue` (NuxtImg + Props interface) | role-match |
|
||||||
|
| `app/components/content/Alert.vue` | component | request-response | `app/components/TechBadge.vue` (withDefaults + UBadge + computed map) | role-match |
|
||||||
|
| `content/fr/blog/test-kotlin-syntax.md` | content | — | aucun | no-analog |
|
||||||
|
| `content/en/blog/test-kotlin-syntax.md` | content | — | aucun | no-analog |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pattern Assignments
|
||||||
|
|
||||||
|
### `nuxt.config.ts` (config — extension)
|
||||||
|
|
||||||
|
**Analog:** `nuxt.config.ts` lui-même (ligne 1–65)
|
||||||
|
|
||||||
|
**État actuel** (lignes 7–14) :
|
||||||
|
```typescript
|
||||||
|
modules: [
|
||||||
|
'@nuxt/ui',
|
||||||
|
'@nuxtjs/i18n',
|
||||||
|
'@nuxt/eslint',
|
||||||
|
'@nuxtjs/sitemap',
|
||||||
|
'nuxt-gtag',
|
||||||
|
'@nuxt/image'
|
||||||
|
],
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pattern à ajouter — ajout dans `modules`** :
|
||||||
|
```typescript
|
||||||
|
modules: [
|
||||||
|
'@nuxt/ui',
|
||||||
|
'@nuxtjs/i18n',
|
||||||
|
'@nuxt/eslint',
|
||||||
|
'@nuxtjs/sitemap',
|
||||||
|
'nuxt-gtag',
|
||||||
|
'@nuxt/image',
|
||||||
|
'@nuxt/content' // ← ajouter ici
|
||||||
|
],
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pattern à ajouter — bloc `content` après les modules existants** :
|
||||||
|
```typescript
|
||||||
|
content: {
|
||||||
|
build: {
|
||||||
|
markdown: {
|
||||||
|
highlight: {
|
||||||
|
theme: {
|
||||||
|
default: 'github-light',
|
||||||
|
dark: 'github-dark'
|
||||||
|
},
|
||||||
|
langs: ['kotlin', 'java', 'typescript', 'shell', 'bash', 'json', 'vue', 'html', 'css']
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
experimental: {
|
||||||
|
sqliteConnector: 'native' // Node 22+ — pas de better-sqlite3
|
||||||
|
}
|
||||||
|
},
|
||||||
|
```
|
||||||
|
|
||||||
|
**Contexte critique :** `colorMode.classSuffix: ''` est déjà configuré ligne 29 — Shiki dual-theme fonctionne via `html.dark`, donc compatible sans modification.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `content.config.ts` (config — création, racine du projet)
|
||||||
|
|
||||||
|
**Analog:** Structure `nuxt.config.ts` (pattern `defineNuxtConfig` → `defineContentConfig`)
|
||||||
|
|
||||||
|
**Pattern complet** (source: RESEARCH.md Pattern 2) :
|
||||||
|
```typescript
|
||||||
|
import { defineContentConfig, defineCollection, z } from '@nuxt/content'
|
||||||
|
|
||||||
|
const blogSchema = z.object({
|
||||||
|
title: z.string(),
|
||||||
|
description: z.string(),
|
||||||
|
date: z.string(),
|
||||||
|
tags: z.array(z.string()).optional(),
|
||||||
|
image: z.string().optional(),
|
||||||
|
})
|
||||||
|
|
||||||
|
export default defineContentConfig({
|
||||||
|
collections: {
|
||||||
|
blog_fr: defineCollection({
|
||||||
|
type: 'page',
|
||||||
|
source: { include: 'fr/blog/**/*.md', prefix: '/blog' },
|
||||||
|
schema: blogSchema,
|
||||||
|
}),
|
||||||
|
blog_en: defineCollection({
|
||||||
|
type: 'page',
|
||||||
|
source: { include: 'en/blog/**/*.md', prefix: '/en/blog' },
|
||||||
|
schema: blogSchema,
|
||||||
|
}),
|
||||||
|
},
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note sur le prefix :** `i18n.strategy: 'prefix_except_default'` avec `defaultLocale: 'fr'` → les articles FR sont sous `/blog/slug`, les EN sous `/en/blog/slug`. (Assumption A3 de RESEARCH.md — valider avec l'article de test.)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `app/assets/css/main.css` (config — extension)
|
||||||
|
|
||||||
|
**Analog:** `app/assets/css/main.css` lui-même (lignes 1–3, existant)
|
||||||
|
|
||||||
|
**État actuel** (lignes 1–3) :
|
||||||
|
```css
|
||||||
|
@import "tailwindcss";
|
||||||
|
@import "@nuxt/ui";
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pattern à ajouter — une ligne après `@import "@nuxt/ui"`** :
|
||||||
|
```css
|
||||||
|
@import "tailwindcss";
|
||||||
|
@import "@nuxt/ui";
|
||||||
|
@plugin "@tailwindcss/typography"; /* ← ajouter ici — syntaxe Tailwind v4 obligatoire */
|
||||||
|
```
|
||||||
|
|
||||||
|
**Anti-pattern à éviter :** Ne pas utiliser `plugins: [require('@tailwindcss/typography')]` dans `tailwind.config.js` — ignoré en Tailwind v4.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `app/components/content/ProseImg.vue` (component, request-response)
|
||||||
|
|
||||||
|
**Analog:** `app/components/ProjectCard.vue` — utilisation de `NuxtImg` avec Props interface (lignes 1–16, 25–35)
|
||||||
|
|
||||||
|
**Imports pattern** (depuis ProjectCard.vue, lignes 1–3) :
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
// Pas d'import externe — NuxtImg est auto-importé par @nuxt/image
|
||||||
|
```
|
||||||
|
|
||||||
|
**Props pattern** (depuis ProjectCard.vue, lignes 4–8) :
|
||||||
|
```typescript
|
||||||
|
interface Props {
|
||||||
|
project: Project
|
||||||
|
}
|
||||||
|
const props = defineProps<Props>()
|
||||||
|
```
|
||||||
|
|
||||||
|
**NuxtImg pattern** (depuis ProjectCard.vue, lignes 26–35) :
|
||||||
|
```vue
|
||||||
|
<NuxtImg
|
||||||
|
:src="project.image"
|
||||||
|
:alt="`...`"
|
||||||
|
loading="lazy"
|
||||||
|
format="webp"
|
||||||
|
width="400"
|
||||||
|
height="300"
|
||||||
|
class="w-full h-52 object-cover"
|
||||||
|
/>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pattern cible pour ProseImg.vue** (adapté avec `withDefaults` — depuis TechBadge.vue ligne 11) :
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
interface Props {
|
||||||
|
src: string
|
||||||
|
alt?: string
|
||||||
|
title?: string
|
||||||
|
width?: string | number
|
||||||
|
height?: string | number
|
||||||
|
}
|
||||||
|
const props = withDefaults(defineProps<Props>(), {
|
||||||
|
alt: '',
|
||||||
|
})
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<NuxtImg
|
||||||
|
:src="props.src"
|
||||||
|
:alt="props.alt"
|
||||||
|
:title="props.title"
|
||||||
|
:width="props.width"
|
||||||
|
:height="props.height"
|
||||||
|
class="rounded-lg w-full"
|
||||||
|
sizes="sm:600px md:800px lg:1000px"
|
||||||
|
/>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `app/components/content/Alert.vue` (component, request-response)
|
||||||
|
|
||||||
|
**Analog:** `app/components/TechBadge.vue` — `withDefaults` + computed map de valeurs + composant Nuxt UI (`UBadge`) (lignes 1–57)
|
||||||
|
|
||||||
|
**withDefaults pattern** (depuis TechBadge.vue, lignes 11–13) :
|
||||||
|
```typescript
|
||||||
|
const props = withDefaults(defineProps<Props>(), {
|
||||||
|
showLevel: true,
|
||||||
|
showImage: true,
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
**Computed map pattern** (depuis TechBadge.vue, lignes 44–56) :
|
||||||
|
```typescript
|
||||||
|
const levelColor = computed(() => {
|
||||||
|
switch (techData.value.level) {
|
||||||
|
case 'Advanced': return 'success' as const
|
||||||
|
case 'Intermediate': return 'primary' as const
|
||||||
|
default: return 'neutral' as const
|
||||||
|
}
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pattern cible pour Alert.vue** (adapté avec `UAlert` Nuxt UI + `ContentSlot` MDC) :
|
||||||
|
```vue
|
||||||
|
<script setup lang="ts">
|
||||||
|
interface Props {
|
||||||
|
type?: 'info' | 'warning' | 'tip' | 'danger'
|
||||||
|
}
|
||||||
|
const props = withDefaults(defineProps<Props>(), {
|
||||||
|
type: 'info',
|
||||||
|
})
|
||||||
|
|
||||||
|
const iconMap = {
|
||||||
|
info: 'i-heroicons-information-circle',
|
||||||
|
warning: 'i-heroicons-exclamation-triangle',
|
||||||
|
tip: 'i-heroicons-light-bulb',
|
||||||
|
danger: 'i-heroicons-x-circle',
|
||||||
|
}
|
||||||
|
const colorMap = {
|
||||||
|
info: 'info',
|
||||||
|
warning: 'warning',
|
||||||
|
tip: 'success',
|
||||||
|
danger: 'error',
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<UAlert
|
||||||
|
:icon="iconMap[props.type]"
|
||||||
|
:color="colorMap[props.type] as any"
|
||||||
|
variant="soft"
|
||||||
|
class="my-4"
|
||||||
|
>
|
||||||
|
<template #description>
|
||||||
|
<ContentSlot :use="$slots.default" unwrap="p" />
|
||||||
|
</template>
|
||||||
|
</UAlert>
|
||||||
|
</template>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Point critique :** `<ContentSlot :use="$slots.default" unwrap="p" />` est obligatoire — sans lui le contenu entre `::alert` et `::` n'est pas rendu (Pitfall 4 RESEARCH.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `content/fr/blog/test-kotlin-syntax.md` (content — création)
|
||||||
|
|
||||||
|
**Analog:** aucun (pas de fichiers markdown dans le projet actuellement)
|
||||||
|
|
||||||
|
**Pattern depuis RESEARCH.md (Code Examples)** :
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Test Kotlin Syntax Highlighting"
|
||||||
|
description: "Article de test pour valider le renderer"
|
||||||
|
date: "2026-04-21"
|
||||||
|
tags: ["kotlin", "hytale", "test"]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bloc de code Kotlin
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
fun main() {
|
||||||
|
println("Hello, Hytale!")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Image optimisée
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Tableau
|
||||||
|
|
||||||
|
| Colonne A | Colonne B |
|
||||||
|
|-----------|-----------|
|
||||||
|
| Valeur 1 | Valeur 2 |
|
||||||
|
|
||||||
|
## Callout
|
||||||
|
|
||||||
|
::alert{type="info"}
|
||||||
|
Ceci est un callout d'information.
|
||||||
|
::
|
||||||
|
```
|
||||||
|
|
||||||
|
**Critère de validation :** Ce fichier doit couvrir les 4 success criteria : bloc Kotlin coloré (BLOG-04), image via ProseImg (BLOG-05), tableau, callout (BLOG-01).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `content/en/blog/test-kotlin-syntax.md` (content — création)
|
||||||
|
|
||||||
|
**Analog:** même structure que la version FR, même slug, contenu traduit en anglais.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Shared Patterns
|
||||||
|
|
||||||
|
### Props avec valeurs par défaut (withDefaults)
|
||||||
|
**Source:** `app/components/TechBadge.vue` lignes 11–14
|
||||||
|
**Apply to:** `ProseImg.vue`, `Alert.vue`
|
||||||
|
```typescript
|
||||||
|
const props = withDefaults(defineProps<Props>(), {
|
||||||
|
// valeurs par défaut pour props optionnelles
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### NuxtImg usage
|
||||||
|
**Source:** `app/components/ProjectCard.vue` lignes 26–35, `app/components/TechBadge.vue` lignes 65–74
|
||||||
|
**Apply to:** `ProseImg.vue`
|
||||||
|
- Toujours utiliser `:src`, `:alt`, `loading="lazy"` au minimum
|
||||||
|
- `format="webp"` si format fixe, sinon laisser @nuxt/image décider
|
||||||
|
- `sizes` pour responsive
|
||||||
|
|
||||||
|
### Composants Nuxt UI (UAlert, UBadge)
|
||||||
|
**Source:** `app/components/TechBadge.vue` ligne 76, `app/components/FAQSection.vue` ligne 33
|
||||||
|
**Apply to:** `Alert.vue`
|
||||||
|
- Nuxt UI est auto-importé — pas d'import explicite nécessaire
|
||||||
|
- Utiliser `color` + `variant` pour le style
|
||||||
|
- `as any` acceptable pour les types union non-exhaustifs de Nuxt UI
|
||||||
|
|
||||||
|
### Convention import types
|
||||||
|
**Source:** `app/components/ProjectCard.vue` ligne 2
|
||||||
|
**Apply to:** `content.config.ts`
|
||||||
|
```typescript
|
||||||
|
import type { ... } from '~~/shared/types' // types partagés
|
||||||
|
import { ... } from '@nuxt/content' // imports de librairie
|
||||||
|
```
|
||||||
|
|
||||||
|
### Auto-import composants
|
||||||
|
**Source:** `nuxt.config.ts` lignes 15–19
|
||||||
|
**Apply to:** `ProseImg.vue`, `Alert.vue`
|
||||||
|
```typescript
|
||||||
|
components: [
|
||||||
|
{
|
||||||
|
path: '~/components',
|
||||||
|
pathPrefix: false, // → components/content/Alert.vue est auto-importé
|
||||||
|
},
|
||||||
|
],
|
||||||
|
```
|
||||||
|
Les composants dans `components/content/` sont auto-importés par Nuxt ET reconnus par `@nuxt/content` comme Prose overrides / composants MDC.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## No Analog Found
|
||||||
|
|
||||||
|
| File | Role | Data Flow | Reason |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `content/fr/blog/test-kotlin-syntax.md` | content | — | Pas de fichiers markdown dans le projet — nouveau format |
|
||||||
|
| `content/en/blog/test-kotlin-syntax.md` | content | — | Pas de fichiers markdown dans le projet — nouveau format |
|
||||||
|
|
||||||
|
Le planner doit utiliser le pattern RESEARCH.md "Code Examples" pour ces deux fichiers.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Metadata
|
||||||
|
|
||||||
|
**Analog search scope:** `app/components/`, `app/assets/css/`, `nuxt.config.ts`
|
||||||
|
**Files scanned:** 6 (nuxt.config.ts, main.css, ProjectCard.vue, TechBadge.vue, FAQSection.vue, app.vue partiel)
|
||||||
|
**Pattern extraction date:** 2026-04-21
|
||||||
Reference in New Issue
Block a user