Actualités et publications
Rédigez des articles chronologiques en Markdown ou MDX, avec auteurs partagés, images adaptatives et flux complets.
Sur cette page
Activez une publication dans ardo.config.ts. Conservez les articles de référence dans un répertoire local ; Ardo génère un index chronologique et une page statique par article publié.
import { defineArdoConfig } from "ardo/config"
export default defineArdoConfig({
title: "Example project",
siteUrl: "https://example.com",
publication: {
from: "posts",
to: "news", // Default: news
name: "News",
description: "Updates from the project.",
authors: {
alex: {
name: "Alex Morgan",
title: "Software engineer",
description: "Working on the project and writing about its design.",
avatar: "app/assets/alex.jpg", // Local paths are relative to the project root.
url: "https://example.com/team/alex",
links: [{ name: "Personal site", url: "https://alex.example.com" }],
did: "did:plc:example", // Optional; no AT account is needed.
},
},
},
})
L'url d'un auteur est une URL de profil absolue en http: ou https:. Ardo l'utilise pour le lien de l'auteur, l'élément <uri> d'Atom et l'url de la personne dans les données structurées de l'article. Une valeur qui n'est pas une URL absolue en http: ou https: produit un avertissement de build et est omise des données structurées ; le lien de l'auteur et le flux Atom s'affichent comme avant.
siteUrl est obligatoire, car les flux nécessitent des URL absolues pour les articles et les images. Le répertoire généré app/routes/news/ est géré par Ardo. Choisissez un répertoire to inutilisé ; Ardo refuse de remplacer des routes écrites à la main. Les fichiers et répertoires sources commençant par _ ou . sont exclus de l'inventaire des articles, ce qui permet de placer des fichiers auxiliaires à côté des articles.
Rédiger un article
Créez posts/a-readable-update.mdx :
---
id: 9c31001a-52ee-4e54-9197-2ff227388cce
title: A readable update
description: What changed, and why it matters.
publishedAt: 2026-10-20T09:00:00Z
authors: [alex]
tags: [Engineering]
coverImage:
src: ./landscape.jpg
alt: A person standing beside a mountain trail.
caption: A quiet moment along the trail.
---
The article starts here. Use ordinary Markdown, or MDX components when the story needs them.
## A useful detail

L'URL est /news/a-readable-update/. Un fichier imbriqué posts/design/typography.mdx devient /news/design/typography/. Définissez path: /news/a-permanent-address pour choisir une adresse indépendamment du nom du fichier source. Les chemins personnalisés doivent rester dans la sous-arborescence de publication. Le réglage trailingSlash, commun à tout le site, décide si ces URL se terminent par une barre oblique. Il applique la même graphie à la propriété url de la publication, de ses articles et de ses archives par étiquette, à leurs liens canoniques, au sitemap et aux liens des flux. Sans ce réglage, les URL de publication gardent la barre oblique, tandis que les entrées du sitemap et les liens canoniques par défaut des articles et des archives par étiquette ne l'ont pas, comme dans les versions précédentes.
Attribuez id une seule fois et conservez-le lorsque vous renommez le fichier, le titre ou l'URL. Pour créer un UUID, exécutez :
node -e "console.log(require('node:crypto').randomUUID())"
publishedAt détermine l'ordre chronologique. Définissez updatedAt pour une révision ultérieure ; modifier un article ne le fait pas remonter en tête. Les deux horodatages exigent un fuseau horaire. authors référence un ou plusieurs profils partagés de la configuration. Les auteurs peuvent avoir un nom, un portrait, un titre professionnel, une biographie, des liens et des DID AT facultatifs.
Définissez draft: true pour exclure un article des pages générées, du JavaScript, des flux, de la recherche et des sitemaps. Une valeur future de publishedAt l'exclut également. Un build à cette date ou après le rend publiable ; un site statique déjà déployé ne se publie pas automatiquement à l'heure prévue. Lorsque buildTime est défini, Ardo décide, selon ce moment figé plutôt que selon l'heure actuelle, quels articles planifiés sont visibles. Les brouillons restent masqués dans tous les cas.
Images locales et cadrage
Ardo traite les images de couverture locales et les images Markdown lors du build. Placez les images à côté de l'article avec des chemins relatifs, ou référencez un fichier de public/ par un chemin relatif à la racine. Les imports MDX relatifs continuent d'être résolus depuis le fichier source d'origine.
Sans métadonnées de cadrage, les résolutions générées conservent la composition d'origine. Avec un noyau ou un cadre préféré, Ardo génère deux familles de recadrages : 16:10 et 4:3. Chacune contient plusieurs résolutions ; le navigateur choisit via srcset et sizes. Ardo préserve les fichiers sources et évite l'agrandissement.
coverImage:
src: ./portrait.jpg
alt: Alex beside a window.
core: { x: 0.65, y: 0.45, size: 0.3 }
margin: 0.15
frame: { x: 0.3, y: 0.1, width: 0.6, height: 0.8 }
core(A) désigne un carré qui doit rester visible.xetysont les coordonnées de son centre, normalisées de 0 à 1.sizeest une fraction du côté le plus court de la source orientée ; la zone reste donc physiquement carrée en paysage comme en portrait.frame(B) exprime la composition souhaitée. Ses coordonnées normaliséesx/yindiquent le coin supérieur gauche, etwidth/heightsont des fractions des dimensions correspondantes de la source.- Avec A seul, Ardo cadre étroitement autour de cette zone avec la marge demandée. Avec B, Ardo utilise B comme composition préférée tout en préservant A s'il est défini. B peut être utilisé seul.
marginvaut par défaut0.15par côté, relativement au recadrage obtenu. Ardo déplace le recadrage et réduit cette marge lorsque la source ne contient pas assez de matière autour du sujet.
Les limites de la source, le ratio cible et la conservation intégrale de A sont des contraintes strictes. Si un recadrage requis ne peut pas contenir tout le noyau, le build échoue avec le chemin de l'image et le ratio cible. Une marge souhaitée insuffisante ne provoque pas à elle seule un échec. L'orientation EXIF est appliquée avant l'interprétation des coordonnées.
Pour les images Markdown intégrées, placez les métadonnées de cadrage dans le frontmatter de l'article, avec la référence exacte de l'image comme clé :
images:
./detail.jpg:
core: { x: 0.5, y: 0.5, size: 0.25 }
preset: article
Les SVG et images animées sont transmis sans redimensionnement et ne peuvent pas utiliser de métadonnées de cadrage. Les images HTTP hébergées ailleurs restent externes ; Ardo ne les télécharge ni ne les optimise.
Consulte Images pour la configuration commune et la diffusion facultative par URL. Les valeurs par défaut ci-dessous s’appliquent sans fournisseur configuré.
Formats de sortie
Ardo génère de l’AVIF pour chaque résolution de chaque image fixe locale d’un article, en préservant la transparence. Chaque image reçoit également un JPEG d’au plus 1280 pixels de large, sans agrandissement. Le JPEG utilise le cadrage de repli du préréglage de l’image, ou la composition d’origine pour une image sans recadrage. Les zones transparentes sont aplaties sur fond blanc dans le JPEG uniquement.
L’élément picture sélectionne les sources AVIF selon les conditions média, avec les résolutions dans chaque srcset. Son élément img utilise l’unique JPEG comme solution de repli, sans srcset JPEG. Les flux réutilisent ce JPEG, tout comme les métadonnées sociales, sauf si l'article définit ogImage. Les portraits des auteurs sont servis directement en AVIF.
Sharp/libvips gère le recadrage, le redimensionnement, l’AVIF et le JPEG lors du build ou de la préparation en développement. Aucun paquet de codec supplémentaire ni environnement d’exécution WebAssembly n’est nécessaire. Les SVG, les images animées et les images externes conservent leur traitement sans modification.
Images de partage
Les balises Open Graph et Twitter utilisent le JPEG de l'image de couverture. Pour partager plutôt une image préparée, comme une carte de 1200 × 630 portant le titre, définissez ogImage:
coverImage:
src: ./landscape.jpg
alt: A person standing beside a mountain trail.
ogImage: ./social.png
Un ogImage relatif désigne un JPEG ou un PNG à côté de l'article. Ardo le publie dans sa taille et son format d'origine, sans EXIF ni autres métadonnées. Les URL et les chemins relatifs à la racine dans public/ restent tels quels. Un article sans aucune de ces images utilise le metadata.image du site.
Choisir un préréglage de présentation
Le cadrage décrit la source. Un préréglage décrit l'emplacement de l'image : la composition à utiliser, les conditions média ordonnées du viewport et la largeur d'affichage attendue.
Ardo fournit des préréglages remplaçables article et card. Le préréglage d'article par défaut choisit 16:10 à partir d'une largeur de viewport de 52rem et 4:3 en dessous ; les cartes utilisent 4:3. Ces règles concernent les images cadrées. Les images sans cadrage conservent leur composition d'origine.
publication: {
// from, authors, ...
images: {
widths: [384, 640, 960, 1280, 1920],
presets: {
article: {
fallback: "4:3",
sizes: "(min-width: 64rem) 48rem, 100vw",
sources: [{ media: "(min-width: 64rem)", composition: "16:10" }],
},
card: { fallback: "4:3", sizes: "(min-width: 48rem) 20rem, 100vw" },
},
},
}
picture sélectionne la première source correspondante. Le srcset de chaque source contient les résolutions d'une seule composition. Les conditions média s'appliquent au viewport et à l'environnement, pas à la largeur de la carte englobante. Choisissez un préréglage adapté à l'emplacement au lieu de supposer qu'une même règle de points de rupture convient à toutes les images.
Flux complets et MDX
Ardo génère /news/atom.xml et /news/rss.xml avec l'article portable complet, les auteurs, les étiquettes et les URL absolues des images. L'index contient les liens vers les deux flux et les métadonnées de découverte. Les identifiants stables des articles restent leur identité dans les flux lorsqu'une URL change. Les deux flux indiquent la langue de la publication : son identifiant de langue, ou le lang du site. Définissez lang sur un site monolingue, car sa valeur par défaut est en.
Par défaut, un identifiant d'entrée ne contient que l'identifiant de l'article. Lorsque plusieurs sites ou publications partagent des identifiants d'articles, par exemple un article traduit sur deux sites monolingues, définissez feeds: { entryIds: "publication" }. L'identifiant inclut alors l'hôte et le chemin de la publication, de sorte que les lecteurs de flux conservent les deux entrées. Les lecteurs traitent les entrées dotées de nouveaux identifiants comme de nouveaux articles : choisissez donc l'option avant la première publication, ou acceptez une série d'entrées répétées.
Le Markdown ordinaire s'exporte directement. Si le MDX contient des composants, expressions, instructions de module ou du HTML que la projection statique omettrait, fournissez l'article portable complet en Markdown dans feedContent. Le build signale les représentations manquantes.
---
id: c4977b7e-b283-4da3-83f0-071f978a1e25
title: An interactive example
publishedAt: 2026-10-20T09:00:00Z
authors: [alex]
feedContent: |
The website contains an interactive counter. It starts at zero;
pressing the button adds one. This text explains the complete example.
---
import { Counter } from "./_Counter"
The website contains an interactive counter.
<Counter />
Le composant MDX Image par défaut affiche les métadonnées d'image préparées, par exemple <Image src="./detail.jpg" alt="The trail" />. Les composants JSX nécessitent aussi une représentation portable dans feedContent. Les éléments littéraux <img> en minuscules suivent le comportement JSX normal ; utilisez des images Markdown ou Image pour le traitement automatique des images de publication.
Versions de documentation et langues
Les URL de publication restent indépendantes des versions de documentation. Si le versionnement est activé, sélectionnez des répertoires documentaires complets et conservez la publication en dehors :
versioning: {
current: "v2",
versions: [{ id: "v2", path: "/v2/" }, { id: "v1", path: "/v1/" }],
directories: ["guide", "api-reference"],
}
L'accueil du site se trouve alors à /, les articles à /news/... et les guides à /v2/guide/.... Toutes les URL respectent aussi la base du déploiement. Sans directories, les projets existants conservent le versionnement de tout le site. Consultez la configuration pour le comportement de migration.
Avec la localisation stricte activée, organisez les articles sous posts/<locale>/. Ardo génère /<locale>/news/ et ses flux pour chaque langue configurée. La validation existante de l'arbre complet de routes reste applicable ; cette fonctionnalité n'ajoute aucun repli de traduction. Transmettez les libellés d'interface traduits via labels.publication de ArdoRoot.
Archives par étiquette
Définissez tags: true pour générer une page par étiquette sous /news/tags/<key>. Le sitemap répertorie ces pages. Les clés d'étiquette doivent être des slugs en minuscules avec des traits d'union, comme release-notes. Le build échoue si une clé ne correspond pas, si un article cite une clé deux fois ou si le chemin d'un article se trouve sous /news/tags. Les flux conservent la clé comme catégorie. Avec les archives, les étiquettes d'un article renvoient à leur archive. Sans archives, les étiquettes peuvent contenir n'importe quel texte. Avec i18n, chaque langue doit avoir les mêmes clés d'étiquette, car chaque page localisée doit exister dans toutes les langues.
Libellés d'étiquette
Une clé d'étiquette est l'identité de l'étiquette dans les URL, le sitemap et les flux ; elle reste donc la même dans toutes les langues. Pour afficher à la place un libellé lisible ou traduit, définissez tagLabel sur un module dont l'export par défaut associe une clé à son libellé :
publication: {
// from, authors, ...
tags: true,
tagLabel: "app/blog/tag-label.ts",
}
Ardo appelle la fonction pendant le rendu d'une page, dans le contexte de rendu serveur, afin qu'elle puisse utiliser les traductions du site. Avec Palamedes, donnez à chaque clé un message, pour que i18n:extract le trouve :
// app/blog/tag-label.ts
import { t } from "@palamedes/core/macro"
import type { PublicationTagLabel } from "ardo/config"
const tagLabel: PublicationTagLabel = (key) => {
switch (key) {
case "design":
return t`Design`
case "release-notes":
return t`Release notes`
default:
return key
}
}
export default tagLabel
Le libellé apparaît dans le titre et le titre par défaut de l'archive par étiquette, ainsi que dans la liste des étiquettes d'un article. Vos propres composants le reçoivent comme label ou le lisent avec useArdoPublicationTags() de ardo/ui. Seules les pages de publication générées importent le module. Les flux conservent la clé, car Ardo les construit sans langue active. Sans tagLabel, les pages affichent la clé.
Présentation et métadonnées propres
Un site doté de son propre design peut rendre les pages générées avec ses propres modules de route. Les chemins sont relatifs à la racine du projet :
publication: {
// from, authors, ...
tags: true,
components: {
index: "app/blog/BlogIndex.tsx",
post: "app/blog/BlogPost.tsx",
tag: "app/blog/BlogTag.tsx",
},
}
Chaque module exporte par défaut un composant React. index reçoit { publication }, post reçoit { post, children } et enveloppe l'article rendu à la place de ArdoPost, et tag reçoit { publication, tag, label, posts }. Un module peut aussi exporter meta. Ardo l'appelle lors du rendu de la route, comme l'export meta de toute route, avec les données de la route et defaults, les descripteurs qu'Ardo rendrait sans lui. La liste renvoyée remplace les valeurs par défaut, y compris le lien canonique et les balises Open Graph, Twitter et JSON-LD ; étalez defaults pour les conserver. Sans export meta, les métadonnées d'Ardo s'appliquent.
Les defaults d'un article contiennent une entrée JSON-LD BlogPosting, { "script:ld+json": … }, avec le titre, la description, l'URL canonique, la langue, les dates, les auteurs, l'image propre à l'article et le site. Si vous étalez defaults, elle est conservée. Un filtre qui retire des descripteurs doit conserver les entrées pour lesquelles "script:ld+json" in entry est vrai, comme dans l'exemple ci-dessous. seo.jsonLd: false désactive l'entrée. Son mainEntityOfPage pointe vers l'URL canonique d'Ardo ; un module qui remplace le lien canonique devrait donc aussi remplacer ou supprimer le BlogPosting.
// app/blog/BlogPost.tsx
import type { PublicationPostMetaArgs, PublicationPostProps } from "ardo/config"
import type { ArdoMetaDescriptor } from "ardo/runtime"
export default function BlogPost({ post, children }: PublicationPostProps) {
return (
<article>
<h1>{post.title}</h1>
{children}
</article>
)
}
// Link descriptors can have a `title` attribute; keep them.
// The JSON-LD entry has no `title`, so the last check keeps it already;
// `"script:ld+json" in entry` keeps it even if that title check changes.
const keep = (entry: ArdoMetaDescriptor) =>
"tagName" in entry || "script:ld+json" in entry || !("title" in entry)
export function meta({ post, publication, defaults }: PublicationPostMetaArgs) {
return [{ title: `${post.title} – ${publication.name}` }, ...defaults.filter(keep)]
}
// app/blog/BlogTag.tsx
import { t } from "@palamedes/core/macro"
import type { PublicationTagMetaArgs, PublicationTagProps } from "ardo/config"
import type { ArdoMetaDescriptor } from "ardo/runtime"
export default function BlogTag({ label, posts }: PublicationTagProps) {
return (
<main>
<h1>{label}</h1>
<ul>
{posts.map((post) => (
<li key={post.id}>
<a href={post.url}>{post.title}</a>
</li>
))}
</ul>
</main>
)
}
const notTitle = (descriptor: ArdoMetaDescriptor) =>
"tagName" in descriptor || !("title" in descriptor)
export function meta({ label, defaults }: PublicationTagMetaArgs) {
return [{ title: t`Posts about ${label}` }, ...defaults.filter(notTitle)]
}
La fonction meta s'exécute pendant le rendu ; elle peut donc traduire comme label. Les types de module PublicationIndexModule, PublicationPostModule et PublicationTagModule de ardo/config décrivent les exports. Lorsqu'un export ne correspond pas à son type, la route générée fait échouer la vérification de types du site. Toutes les pages et tous les modules partagent les données de publication ; Ardo les gèle donc, et leurs listes sont en lecture seule : triez une copie, comme [...publication.posts].sort(…). defaults est une nouvelle liste à chaque appel. Les valeurs par défaut de l'index, des articles et des archives par étiquette se terminent toutes par les liens de découverte Atom et RSS de la publication. Avec un module d'article, le build échoue lorsqu'un article exporte son propre meta, car cela supprimerait les liens canonique, Open Graph et de flux de l'article ; faites plutôt varier les métadonnées dans le meta du module. Sans module d'article, le meta propre à un article remplace les métadonnées d'Ardo, comme sur toute page.
Champs d'article personnalisés
Les champs de frontmatter qu'Ardo ne lit pas parviennent à l'article sous la forme post.data, par exemple nextStep: /contact. Le module d'article les reçoit dans ses props et dans meta ; vérifiez le type de chaque valeur avant de l'utiliser. Ils restent sur la page propre à l'article : les articles des listes et de virtual:ardo/publication ont un data vide, afin que les champs d'un article ne soient pas livrés avec toutes les autres pages. La racine lit les mêmes champs avec useArdoPage().frontmatter.
Seules les routes de publication générées importent ces modules. Le cadre d'article fait partie des pages d'article, et non de la documentation ni des autres pages. Avec i18n, Ardo ajoute toujours les liens alternatifs de langue de chaque page, et un lien canonique lorsque les métadonnées renvoyées n'en contiennent pas.
Données de page pour la racine
L’index et les archives par étiquette n’ont pas de frontmatter propre. Leurs modules peuvent exporter frontmatter pour donner à la racine des données de page, comme un lien vers la même page dans une autre langue. Ardo l’appelle quand il rend la page, comme meta, avec { publication } pour l’index et { publication, tag, label, posts } pour chaque archive par étiquette. La racine lit le résultat avec useArdoPage().frontmatter, sur le serveur et pendant l’hydratation, comme elle lit les champs d’un article. Sans l’export, ces pages n’ont pas de frontmatter.
// app/blog/BlogTag.tsx
import type { PublicationTagFrontmatterArgs } from "ardo/config"
export function frontmatter({ tag }: PublicationTagFrontmatterArgs) {
return { counterpart: `https://de.example.com/blog/tags/${tag.key}/` }
}
// app/root.tsx
const counterpart = useArdoPage().frontmatter?.counterpart
Ardo n’écrit aucune donnée de page dans le bundle. La route de chaque archive contient sa propre étiquette et ses articles et les transmet à la fonction. Tout ce que le module importe, comme une liste d’étiquettes traduites, est livré avec le module à chaque archive.
Mises en page personnalisées et métadonnées AT
Importez les données de publication depuis virtual:ardo/publication pour les réutiliser ailleurs. L'export par défaut est la publication de la langue par défaut ; publications associe les identifiants de langue (ou default sans localisation) à leurs données. ArdoPostList, ArdoPost, ArdoImage et ardoImagePresets sont disponibles depuis ardo/ui. Le contenu source des articles reste en MDX ; l'export public contient les métadonnées et les descripteurs d'images préparés. Avec les archives par étiquette, publication.tags répertorie la clé, le chemin et l'URL de chaque étiquette ; passez-en une comme tag à ArdoPostList pour ne lister que ses articles.
Utilisez ArdoPostNavigation depuis ardo/ui pour une navigation compacte entre les articles. Transmettez la publication de la langue courante via la prop mobileMenuContent de ArdoHeader pour remplir le menu mobile d’une page d’actualités. Le composant affiche les dix derniers articles publiés par défaut, met la page courante en évidence et propose « Tous les articles » pour accéder à l’index complet de la publication. Définissez limit pour modifier la longueur de la liste. Traduisez labels.publication.recentPosts et labels.publication.allPosts avec les autres libellés de publication.
Les noms des métadonnées suivent, lorsque c'est pertinent, le lexique de documents de Standard.site : title, description, publishedAt, updatedAt, tags, coverImage et path. Les clés d'auteurs locales, les chemins des images sources, les métadonnées de cadrage, id, draft et feedContent sont des champs de rédaction Ardo. Un futur module de publication AT les traduira à l'export. Les builds ordinaires génèrent le site statique et les flux ; ils ne publient rien sur un compte AT.