# News and publications

Write chronological posts in Markdown or MDX, with shared authors, responsive images, and full-content feeds.

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

Enable a publication in `ardo.config.ts`. Keep canonical posts in a local directory; Ardo generates a chronological index and one static page per published post.

```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.
      },
    },
  },
})
```

An author's `url` is an absolute `http:` or `https:` profile URL. Ardo uses it for the author link, the Atom `<uri>`, and the person's `url` in the post's structured data. A value that is not an absolute `http:` or `https:` URL produces a build warning and is left out of the structured data; the author link and the Atom feed render as before.

`siteUrl` is required because feeds need absolute article and image URLs. The generated `app/routes/news/` directory belongs to Ardo. Choose an unused `to` directory; Ardo refuses to replace handwritten routes. Files and directories starting with `_` or `.` in the source directory are excluded from the post inventory, so helpers can live beside posts.

## Author a post

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

The URL is `/news/a-readable-update/`. A nested `posts/design/typography.mdx` becomes `/news/design/typography/`. Set `path: /news/a-permanent-address` to choose an address independently of the source filename. Custom paths must remain inside the publication subtree. The site-wide [`trailingSlash`](<https://ardo-docs.dev/v6/en/guide/configuration/#trailingslash>) setting decides whether these URLs end with a slash. It spells the `url` of the publication, its posts, and its tag archives, their canonical links, the sitemap, and the feed links alike. Without the setting, publication URLs keep the slash, while sitemap entries and the default canonical links of posts and tag archives do not, as in earlier versions.

Assign `id` once and preserve it when renaming the file, title, or URL. To create a UUID, run:

```sh
node -e "console.log(require('node:crypto').randomUUID())"
```

`publishedAt` determines chronological order. Set `updatedAt` for a later revision; editing a post does not move it to the top. Both timestamps require a time zone. `authors` references one or more shared profiles from the configuration. Authors can have names, portraits, professional titles, biographies, links, and optional AT DIDs.

Set `draft: true` to exclude a post from generated pages, JavaScript, feeds, search, and sitemaps. A future `publishedAt` also excludes the post. A build at or after that instant makes it eligible; an already deployed static site does not publish itself when the clock reaches that date. When [`buildTime`](<https://ardo-docs.dev/v6/en/guide/configuration/#buildtime>) is set, Ardo decides which scheduled posts are visible against that pinned moment instead of the current time. Drafts stay hidden regardless.

## Local images and framing

Ardo processes local cover images and Markdown images during the build. Put images beside the post and use relative paths, or reference a file in `public/` with a root-relative path. Relative MDX imports continue to resolve against the original source file.

Without framing metadata, generated resolutions retain the original composition. With a core area or preferred frame, Ardo generates two crop families: **16:10** and **4:3**. Each family contains several resolutions; the browser chooses one through `srcset` and `sizes`. Ardo preserves source files and avoids upscaling.

```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)** identifies a square that must remain visible. `x` and `y` are its center, each normalized from 0 to 1. `size` is a fraction of the oriented source's shorter side, so the region remains physically square on landscape and portrait images.
- **`frame` (B)** expresses the preferred composition. Its normalized `x`/`y` identify the top-left corner, and `width`/`height` are fractions of the respective source dimensions.
- With only A, Ardo frames tightly around it with the requested margin. With B, Ardo uses B as the framing preference while preserving A whenever it is present. B can be used alone.
- **`margin`** defaults to `0.15` per side, relative to the resulting crop. Ardo shifts the crop and reduces that margin when the source lacks enough surrounding content.

Source bounds, the target aspect ratio, and preservation of A are hard constraints. If a required crop cannot contain the complete core, the build fails with the image path and target ratio. Missing preferred margin alone does not fail the build. EXIF orientation is applied before interpreting coordinates.

For inline Markdown images, put framing metadata in the post's frontmatter, keyed by the exact authored image reference:

```yaml
images:
  ./detail.jpg:
    core: { x: 0.5, y: 0.5, size: 0.25 }
    preset: article
```

SVG and animated images pass through without resizing and cannot use framing metadata. Externally hosted HTTP images remain external; Ardo does not download or optimize them.

For shared configuration and optional URL delivery, see [Images](<https://ardo-docs.dev/v6/en/guide/images/>). The defaults below apply when no provider is configured.

## Output formats

Ardo generates **AVIF** for every resolution of each local still post image, preserving transparency. Each image also gets one **JPEG**, at most 1280 pixels wide, without upscaling. The JPEG uses the image preset's fallback composition, or the original composition for an unframed image. Transparent areas are flattened onto white in the JPEG only.

The `picture` element selects AVIF sources by media condition, with resolutions in each `srcset`. Its `img` element uses the single JPEG as a fallback, without a JPEG `srcset`. Feeds reuse that JPEG, and so does social metadata unless the post sets [`ogImage`](<https://ardo-docs.dev/v6/en/guide/publications#share-images>). Author portraits are served directly as AVIF.

Sharp/libvips handles cropping, resizing, AVIF, and JPEG during build or development preparation. No additional codec package or WebAssembly runtime is needed. SVG, animated images, and external images keep their existing pass-through behavior.

## Share images

Open Graph and Twitter tags use the cover image's JPEG. To share a prepared image instead, such as a 1200 × 630 card with the title on it, set `ogImage`:

```yaml
coverImage:
  src: ./landscape.jpg
  alt: A person standing beside a mountain trail.
ogImage: ./social.png
```

A relative `ogImage` names a JPEG or PNG beside the post. Ardo publishes it at its original size and format, without EXIF or other metadata. URLs and root-relative paths in `public/` stay as written. A post with neither image uses the site's [`metadata.image`](<https://ardo-docs.dev/v6/en/guide/configuration/#metadata>).

## Select a presentation preset

Framing describes the source. A preset describes an image's placement: which composition to use, ordered viewport media conditions, and the expected display width.

Ardo supplies replaceable `article` and `card` presets. The default article preset chooses 16:10 at viewport widths of at least `52rem` and otherwise uses 4:3; cards use 4:3. These rules apply to framed images. Unframed images retain their original composition.

```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` selects the first matching source. Each source's `srcset` contains resolutions of one composition. Media conditions evaluate the viewport and environment, rather than the containing card's width. Choose a preset that matches the placement instead of assuming one breakpoint policy fits every image.

## Full-content feeds and MDX

Ardo generates `/news/atom.xml` and `/news/rss.xml`, including the full portable article, authors, tags, and absolute image URLs. The index links both feeds and includes feed discovery metadata. Stable post IDs remain the feed identity when a URL changes. Both feeds declare the publication's locale, or the site's `lang`. Set `lang` on a single-language site, because it otherwise defaults to `en`.

An entry ID contains only the post ID by default. When several sites or publications share post IDs, for example a translated post on two single-language sites, set `feeds: { entryIds: "publication" }`. The ID then includes the publication's host and path, so feed readers keep both entries. Readers treat entries with new IDs as new posts, so choose the option before the first release, or accept one round of repeated entries.

Ordinary Markdown exports directly. When MDX contains components, expressions, module statements, or HTML that the static projection would omit, supply the complete portable article as Markdown in `feedContent`. The build reports missing replacements.

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

The default `Image` MDX component renders prepared image metadata, for example `<Image src="./detail.jpg" alt="The trail" />`. JSX components also need a portable representation in `feedContent`. Literal lowercase `<img>` elements use normal JSX behavior; use Markdown images or `Image` for automatic publication image handling.

## Documentation versions and locales

Publication URLs remain independent of documentation versions. When versioning is enabled, select complete documentation directories and keep the publication outside them:

```ts
versioning: {
  current: "v2",
  versions: [{ id: "v2", path: "/v2/" }, { id: "v1", path: "/v1/" }],
  directories: ["guide", "api-reference"],
}
```

This gives the site homepage `/`, posts `/news/...`, and guides `/v2/guide/...`. All URLs also respect a deployment `base`. Without `directories`, existing projects retain whole-site versioning. See [configuration](<https://ardo-docs.dev/v6/en/guide/configuration/#versioning>) for migration behavior.

With strict localization enabled, organize posts under `posts/<locale>/`. Ardo generates `/<locale>/news/` and its feeds for every configured locale. The existing complete-route-tree validation still applies; this feature does not introduce translation fallbacks. Pass translated UI labels through `ArdoRoot`'s `labels.publication`.

## Tag archives

Set `tags: true` to generate a page for each tag at `/news/tags/<key>`. The sitemap lists these pages. Tag keys must be lowercase slugs with hyphens, such as `release-notes`. The build fails when a key does not match, when a post lists a key twice, or when a post path falls under `/news/tags`. Feeds keep the key as category. With archives, the tags on a post link to their archive. Without archives, tags can be any text. With `i18n`, every locale needs the same tag keys, because each localized page must exist in every locale.

### Tag labels

A tag key is the tag's identity in URLs, the sitemap, and feeds, so it stays the same in every language. To show a readable or translated label instead, set `tagLabel` to a module whose default export maps a key to its label:

```ts
publication: {
  // from, authors, ...
  tags: true,
  tagLabel: "app/blog/tag-label.ts",
}
```

Ardo calls the function while it renders a page, inside the [server render context](<https://ardo-docs.dev/v6/en/guide/internationalization/#server-render-context>), so it can use the site's translations. With Palamedes, give each key a message, so that `i18n:extract` finds it:

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

The label appears in the heading and default title of the tag archive and in the tag list of a post. Your own components receive it as `label` or read it with `useArdoPublicationTags()` from `ardo/ui`. Only the generated publication pages import the module. Feeds keep the key, because Ardo builds them without an active locale. Without `tagLabel`, pages show the key.

## Own presentation and metadata

A site with its own design can render the generated pages with its own route modules. Paths are relative to the project root:

```ts
publication: {
  // from, authors, ...
  tags: true,
  components: {
    index: "app/blog/BlogIndex.tsx",
    post: "app/blog/BlogPost.tsx",
    tag: "app/blog/BlogTag.tsx",
  },
}
```

Each module default-exports a React component. `index` receives `{ publication }`, `post` receives `{ post, children }` and wraps the rendered article in place of `ArdoPost`, and `tag` receives `{ publication, tag, label, posts }`. A module can also export `meta`. Ardo calls it when it renders the route, like the `meta` export of any route, with the route's data and `defaults`, the descriptors Ardo would render without it. The returned list replaces the defaults, including the canonical link, Open Graph, Twitter, and JSON-LD tags, so spread `defaults` to keep them. Without a `meta` export, Ardo's metadata applies.

The `defaults` of a post contain a `BlogPosting` JSON-LD entry, `{ "script:ld+json": … }`, with the headline, description, canonical URL, language, dates, authors, the post's own image, and the site. Spreading `defaults` keeps it. A filter that drops descriptors must keep entries where `"script:ld+json" in entry`, as the example below does. `seo.jsonLd: false` turns the entry off. Its `mainEntityOfPage` points at Ardo's canonical URL, so a module that replaces the canonical link should also replace or drop the `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)]
}
```

The `meta` function runs during rendering, so it can translate like `label` does. The module types `PublicationIndexModule`, `PublicationPostModule`, and `PublicationTagModule` from `ardo/config` describe the exports. When an export does not match its type, the generated route fails the site's type check. Every page and module shares the publication data, so Ardo freezes it, and its lists are read-only: sort a copy, such as `[...publication.posts].sort(…)`. `defaults` is a new list for every call. The defaults of the index, posts, and tag archives all end with the publication's Atom and RSS discovery links. With a post module, the build fails when a post exports its own `meta`, because that would drop the canonical, Open Graph, and feed links of the post; vary the metadata in the module's `meta` instead. Without a post module, a post's own `meta` replaces Ardo's metadata, as on any page.

### Custom post fields

Frontmatter fields that Ardo does not read reach the post as `post.data`, for example `nextStep: /contact`. The post module receives them in its props and `meta`; check each value's type before use. They stay on the post's own page: the posts of listings and of `virtual:ardo/publication` have an empty `data`, so one post's fields do not ship with every other page. The root reads the same fields with `useArdoPage().frontmatter`.

Only the generated publication routes import these modules. The post frame is part of post pages and not of documentation or other pages. With `i18n`, Ardo still adds the locale alternate links of every page, and a canonical link when the returned metadata has none.

### Page data for the root

The index and the tag archives have no frontmatter of their own. Their modules can export `frontmatter` to give the root page data, such as a link to the same page in another language. Ardo calls it when it renders the page, like `meta`, with `{ publication }` for the index and `{ publication, tag, label, posts }` for each tag archive. The root reads the result with `useArdoPage().frontmatter`, on the server and during hydration, as it reads a post's fields. Without the export, these pages have no 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 writes no page data into the bundle. Each archive's route holds its own tag and posts and passes them to the function. Anything the module imports, such as a list of translated tags, ships with the module to every archive.

## Custom layouts and AT metadata

Import the publication data from `virtual:ardo/publication` to reuse it elsewhere. The default export is the default locale's publication; `publications` maps locale IDs (or `default` without localization) to their data. `ArdoPostList`, `ArdoPost`, `ArdoImage`, and `ardoImagePresets` are available from `ardo/ui`. The source of post content remains MDX; the public data export contains metadata and prepared image descriptors. With tag archives, `publication.tags` lists each tag's key, path, and URL; pass one as `tag` to `ArdoPostList` to list only its posts.

Use `ArdoPostNavigation` from `ardo/ui` for compact article navigation. Pass the current locale's publication to it through `ArdoHeader`'s `mobileMenuContent` prop to populate a news page's mobile menu. It shows the ten newest published articles by default, highlights the current page, and links to the complete publication index through "All articles". Set `limit` to change the recent list length. Translate `labels.publication.recentPosts` and `labels.publication.allPosts` alongside the other publication labels.

Metadata names follow [Standard.site's document lexicon](https://standard.site/docs/lexicons/document) where applicable: `title`, `description`, `publishedAt`, `updatedAt`, `tags`, `coverImage`, and `path`. Local author keys, source image paths, framing metadata, `id`, `draft`, and `feedContent` are Ardo authoring fields. A future AT publisher will translate them at the export boundary. Ordinary builds generate the static website and feeds; they do not publish to an AT account.
