Skip to content
⌘K

News and publications

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

On this page

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.

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:

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

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

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:

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

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.

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.

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.

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

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

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, so it can use the site's translations. With Palamedes, give each key a message, so that i18n:extract finds it:

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

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.

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

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.

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

Edit this page on GitHubLast updated: November 13, 2026