# Actualités et publications

Rédigez des articles chronologiques en Markdown ou MDX, avec auteurs partagés, images adaptatives et flux complets.

Source: https://ardo-docs.dev/v6/fr/guide/publications

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é.

```ts
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 {#author-a-post}

Créez `posts/a-readable-update.mdx` :

```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

![A closer view of the trail](./detail.jpg)
```

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`](<https://ardo-docs.dev/v6/fr/guide/configuration/#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 :

```sh
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`](<https://ardo-docs.dev/v6/fr/guide/configuration/#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 {#local-images-and-framing}

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.

```yaml
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. `x` et `y` sont les coordonnées de son centre, normalisées de 0 à 1. `size` est 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ées `x`/`y` indiquent le coin supérieur gauche, et `width`/`height` sont 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.
- **`margin`** vaut par défaut `0.15` par 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é :

```yaml
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](<https://ardo-docs.dev/v6/fr/guide/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 {#output-formats}

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`](<https://ardo-docs.dev/v6/fr/guide/publications#share-images>). 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 {#share-images}

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`:

```yaml
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`](<https://ardo-docs.dev/v6/fr/guide/configuration/#metadata>) du site.

## Choisir un préréglage de présentation {#select-a-presentation-preset}

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.

```ts
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 {#full-content-feeds-and-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.

```mdx
---
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 {#documentation-versions-and-locales}

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 :

```ts
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](<https://ardo-docs.dev/v6/fr/guide/configuration/#versioning>) 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 {#tag-archives}

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 {#tag-labels}

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é :

```ts
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](<https://ardo-docs.dev/v6/fr/guide/internationalization/#server-render-context>), afin qu'elle puisse utiliser les traductions du site. Avec Palamedes, donnez à chaque clé un message, pour que `i18n:extract` le trouve :

```ts
// 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 {#own-presentation-and-metadata}

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 :

```ts
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`.

```tsx
// 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)]
}
```

```tsx
// 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 {#custom-post-fields}

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 {#page-data-for-the-root}

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.

```tsx
// 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}/` }
}
```

```tsx
// 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 {#custom-layouts-and-at-metadata}

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](https://standard.site/docs/lexicons/document) : `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.
