Créer un site EmDash

EmDash est un CMS construit sur Astro. Il stocke le schéma dans la base de données (pas dans le code), sert le contenu via des collections de contenu en direct, et fournit une interface admin complète à /_emdash/admin. Les sites sont des projets Astro standard avec l'intégration emdash.

Pièges courants

Ce sont les choses qui cassent silencieusement les sites. Connaissez-les avant de commencer.

1. Les champs image sont des objets, pas des chaînes. post.data.featured_image est { id, src, alt }. Écrire <img src={post.data.featured_image} /> affiche [object Object]. Utilisez <Image image={post.data.featured_image} /> depuis "emdash/ui".

2. entry.id vs entry.data.id sont deux choses différentes. entry.id est le slug (utilisé dans les URLs). entry.data.id est l'ULID de la base de données (utilisé pour getEntryTerms, Comments, et d'autres appels API qui nécessitent l'ID réel). Les confondre provoque des résultats vides silencieux.

3. Les noms de taxonomie doivent correspondre exactement à la seed. Si votre seed définit "name": "category", vous devez interroger getTerm("category", slug) -- pas "categories". Mauvais nom = résultats vides, pas d'erreur.

4. Toujours passer cacheHint à Astro.cache.set(). Chaque requête renvoie un cacheHint. Appelez Astro.cache.set(cacheHint) sur chaque page qui interroge le contenu, sinon l'invalidation du cache ne fonctionnera pas quand les éditeurs publient des modifications.

5. Pas de getStaticPaths pour le contenu CMS. Le contenu EmDash est dynamique. Les pages doivent être server-rendered (output: "server" dans astro.config.mjs).

Structure des fichiers

Chaque site EmDash a ces fichiers clés :

my-site/
├── astro.config.mjs          # Config Astro avec intégration emdash()
├── src/
│   ├── live.config.ts         # Enregistrement du loader EmDash (boilerplate)
│   ├── pages/                 # Pages Astro (toutes server-rendered)
│   ├── layouts/               # Composants de mise en page
│   └── components/            # Composants réutilisables
├── seed/
│   └── seed.json              # Schéma + contenu de démo
├── emdash-env.d.ts          # Types générés (depuis `emdash types`)
└── package.json

Flux de travail

1. Configurer le projet

Lisez references/configuration.md pour astro.config.mjs, live.config.ts, les cibles de déploiement (Node vs Cloudflare), et la génération de types.

2. Concevoir le schéma

Lisez references/schema-and-seed.md pour les définitions de collection, les types de champs, les taxonomies, les menus, les zones de widgets, les sections, les bylines, et le format complet du fichier seed.

3. Construire les pages

Lisez references/querying-and-rendering.md pour les requêtes de contenu, le rendu Portable Text, le composant Image, les attributs de visual editing, la mise en cache, et les motifs de page courants (liste, détail, archive de taxonomie, RSS, recherche, 404).

4. Intégrer les fonctionnalités du site

Lisez references/site-features.md pour les paramètres du site, les menus de navigation, les taxonomies, les zones de widgets, la recherche, les métas SEO, les commentaires, et les contributions de page.

5. Créer le fichier seed

Écrivez seed/seed.json avec les collections, les champs, les taxonomies, les menus, les widgets, et le contenu exemple.

6. Lancer et vérifier

npx emdash dev          # Démarrer le serveur de dev (exécute les migrations + seeds, et génère les types)

L'interface admin est à http://localhost:4321/_emdash/admin.

Aide-mémoire API rapide

// Contenu (les entries ont .data.byline et .data.bylines chargées avec impatience)
import { getEmDashCollection, getEmDashEntry } from "emdash";
const { entries, nextCursor, cacheHint } = await getEmDashCollection("posts", {
    limit: 10,
    cursor,
    orderBy: { published_at: "desc" },
});
const { entry: post, cacheHint } = await getEmDashEntry("posts", slug);

// Fonctionnalités du site
import {
    getSiteSettings,
    getMenu,
    getTaxonomyTerms,
    getTerm,
    getEntryTerms,
    getEntriesByTerm,
    getWidgetArea,
    search,
    getSection,
    getSeoMeta,
} from "emdash";

// Bylines (requêtes autonomes -- généralement inutiles car les entries ont les bylines attachées)
import { getByline, getBylineBySlug } from "emdash";

// Composants UI
import {
    PortableText,
    Image,
    Comments,
    CommentForm,
    WidgetArea,
    EmDashHead,
    EmDashBodyStart,
    EmDashBodyEnd,
} from "emdash/ui";
import LiveSearch from "emdash/ui/search";

// Contexte de page (pour les contributions de plugin)
import { createPublicPageContext } from "emdash/page";

Plugins

EmDash supporte les plugins pour étendre le CMS avec des hooks, du stockage, des paramètres, l'interface admin, les routes API, et les types de blocs Portable Text personnalisés. Envisagez un plugin quand vous avez besoin de :

• Réagir aux événements du cycle de vie du contenu (par ex., envoyer une notification à la publication, synchroniser vers un service externe)
• Ajouter des pages admin personnalisées ou des widgets de tableau de bord
• Ajouter des types de blocs personnalisés à l'éditeur Portable Text (par ex., cartes embarquées, playgrounds de code, CTAs)
• Fournir un service réutilisable (par ex., analytics, formulaires, commentaires via un fournisseur tiers)

Les plugins sont enregistrés dans astro.config.mjs :

emdash({
    database: sqlite({ url: "file:./data.db" }),
    storage: local({ directory: "./uploads", baseUrl: "/_emdash/api/media/file" }),
    plugins: [myPlugin()],
}),

Pour construire un plugin, chargez la skill creating-plugins (dans .agents/skills/creating-plugins/). Elle couvre l'anatomie des plugins, les hooks, le stockage, l'interface admin, les routes API, les blocs Portable Text, les capacités, et l'API complète definePlugin().

Documents de référence