Saltar al contenido
⌘K

Noticias y publicaciones

Escribe entradas cronológicas en Markdown o MDX, con autores compartidos, imágenes adaptables y feeds completos.

Ver como Markdown
En esta página

Activa una publicación en ardo.config.ts. Guarda las entradas canónicas en un directorio local; Ardo genera un índice cronológico y una página estática por entrada publicada.

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

La url de un autor es una URL de perfil absoluta con http: o https:. Ardo la usa para el enlace del autor, el <uri> de Atom y la url de la persona en los datos estructurados de la entrada. Un valor que no sea una URL absoluta con http: o https: genera una advertencia de compilación y se omite de los datos estructurados; el enlace del autor y el feed Atom se muestran como antes.

siteUrl es obligatorio porque los feeds necesitan URL absolutas de artículos e imágenes. El directorio generado app/routes/news/ pertenece a Ardo. Elige un directorio to sin usar; Ardo se niega a sustituir rutas escritas a mano. Los archivos y directorios del origen que empiezan por _ o . se excluyen del inventario de entradas, por lo que los archivos auxiliares pueden estar junto a ellas.

Escribir una entrada

Crea 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)

La URL es /news/a-readable-update/. Un archivo anidado posts/design/typography.mdx se convierte en /news/design/typography/. Define path: /news/a-permanent-address para elegir una dirección independiente del nombre del archivo fuente. Las rutas personalizadas deben permanecer dentro del subárbol de publicación. El ajuste trailingSlash, común a todo el sitio, decide si estas URL terminan con una barra. Aplica la misma forma a la propiedad url de la publicación, de sus entradas y de sus archivos de etiquetas, a sus enlaces canónicos, al sitemap y a los enlaces de los feeds. Sin el ajuste, las URL de publicación conservan la barra, mientras que las entradas del sitemap y los enlaces canónicos predeterminados de las entradas y de los archivos de etiquetas no la tienen, como en versiones anteriores.

Asigna id una sola vez y consérvalo al cambiar el nombre del archivo, el título o la URL. Para crear un UUID, ejecuta:

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

publishedAt determina el orden cronológico. Define updatedAt para una revisión posterior; editar una entrada no la devuelve al principio. Ambas marcas de tiempo requieren una zona horaria. authors hace referencia a uno o varios perfiles compartidos de la configuración. Los autores pueden tener nombre, retrato, cargo profesional, biografía, enlaces y DID de AT opcionales.

Define draft: true para excluir una entrada de las páginas generadas, JavaScript, feeds, búsqueda y sitemaps. Un valor futuro de publishedAt también la excluye. Un build en ese momento o después la hace publicable; un sitio estático ya desplegado no se publica automáticamente al llegar esa fecha. Cuando buildTime está definido, Ardo decide qué entradas programadas son visibles según ese momento fijado en lugar de la hora actual. Los borradores permanecen ocultos en cualquier caso.

Imágenes locales y encuadre

Ardo procesa las imágenes de portada locales y las imágenes Markdown durante el build. Coloca las imágenes junto a la entrada con rutas relativas, o haz referencia a un archivo de public/ con una ruta relativa a la raíz. Las importaciones MDX relativas siguen resolviéndose desde el archivo fuente original.

Sin metadatos de encuadre, las resoluciones generadas conservan la composición original. Con un núcleo o un marco preferido, Ardo genera dos familias de recortes: 16:10 y 4:3. Cada una contiene varias resoluciones; el navegador elige mediante srcset y sizes. Ardo conserva los archivos fuente y evita ampliarlos.

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) identifica un cuadrado que debe permanecer visible. x y y son las coordenadas de su centro, normalizadas de 0 a 1. size es una fracción del lado más corto del origen orientado, por lo que la zona sigue siendo físicamente cuadrada en imágenes horizontales y verticales.
  • frame (B) expresa la composición preferida. Sus valores normalizados x/y indican la esquina superior izquierda, y width/height son fracciones de las respectivas dimensiones del origen.
  • Con solo A, Ardo recorta alrededor de esa zona con el margen solicitado. Con B, Ardo usa B como composición preferida y conserva A siempre que esté definido. B también puede usarse solo.
  • margin tiene un valor predeterminado de 0.15 por lado, relativo al recorte resultante. Ardo desplaza el recorte y reduce ese margen cuando el origen no ofrece suficiente contenido alrededor.

Los límites del origen, la relación de aspecto objetivo y la conservación íntegra de A son restricciones obligatorias. Si un recorte requerido no puede contener todo el núcleo, el build falla con la ruta de la imagen y la relación objetivo. Un margen preferido insuficiente no provoca por sí solo un fallo. La orientación EXIF se aplica antes de interpretar las coordenadas.

Para imágenes Markdown insertadas, coloca los metadatos de encuadre en el frontmatter de la entrada, usando la referencia exacta de la imagen como clave:

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

Los SVG y las imágenes animadas pasan sin cambiar de tamaño y no admiten metadatos de encuadre. Las imágenes HTTP alojadas externamente siguen siendo externas; Ardo no las descarga ni las optimiza.

Consulta Imágenes para la configuración compartida y la entrega opcional mediante URL. Los valores predeterminados siguientes se aplican sin un proveedor configurado.

Formatos de salida

Ardo genera AVIF para cada resolución de cada imagen estática local de un artículo y conserva la transparencia. Cada imagen también recibe un JPEG de hasta 1280 píxeles de ancho, sin ampliación. El JPEG usa el encuadre de respaldo del preajuste de imagen o la composición original si la imagen no tiene recorte. Las zonas transparentes se aplanan sobre blanco solo en el JPEG.

El elemento picture selecciona las fuentes AVIF según las condiciones de medios, con las resoluciones en cada srcset. Su elemento img usa el único JPEG como respaldo, sin un srcset de JPEG. Los feeds reutilizan ese JPEG, y también los metadatos sociales, salvo que la entrada defina ogImage. Los retratos de los autores se sirven directamente como AVIF.

Sharp/libvips gestiona el recorte, el redimensionamiento, AVIF y JPEG durante el build o la preparación en desarrollo. No se necesita ningún paquete de códec adicional ni un entorno de ejecución WebAssembly. Los SVG, las imágenes animadas y las imágenes externas se siguen utilizando sin modificaciones.

Imágenes para compartir

Las etiquetas Open Graph y Twitter usan el JPEG de la imagen de portada. Para compartir en su lugar una imagen preparada, como una tarjeta de 1200 × 630 con el título, define ogImage:

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

Un ogImage relativo indica un JPEG o PNG junto a la entrada. Ardo lo publica con su tamaño y formato originales, sin EXIF ni otros metadatos. Las URL y las rutas relativas a la raíz en public/ se mantienen tal cual. Una entrada sin ninguna de las dos imágenes usa el metadata.image del sitio.

Seleccionar un preajuste de presentación

El encuadre describe el origen. Un preajuste describe el uso de una imagen: qué composición utilizar, las condiciones multimedia ordenadas del viewport y el ancho de visualización previsto.

Ardo proporciona preajustes sustituibles article y card. El preajuste predeterminado de artículo elige 16:10 a partir de un ancho de viewport de 52rem y 4:3 por debajo; las tarjetas usan 4:3. Estas reglas se aplican a imágenes con encuadre. Las imágenes sin encuadre conservan su composición original.

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 selecciona la primera fuente coincidente. El srcset de cada fuente contiene resoluciones de una sola composición. Las condiciones multimedia evalúan el viewport y el entorno, no el ancho de la tarjeta que contiene la imagen. Elige un preajuste adecuado para el uso, en lugar de suponer que una misma política de puntos de ruptura sirve para todas las imágenes.

Feeds completos y MDX

Ardo genera /news/atom.xml y /news/rss.xml con el artículo portátil completo, autores, etiquetas y URL absolutas de imágenes. El índice enlaza ambos feeds e incluye metadatos para descubrirlos. Los identificadores estables de las entradas siguen siendo su identidad en el feed cuando cambia una URL. Ambos feeds declaran el idioma de la publicación: su identificador de idioma o el lang del sitio. Define lang en un sitio de un solo idioma, porque de lo contrario vale en.

De forma predeterminada, el identificador de una entrada del feed solo contiene el identificador de la entrada. Cuando varios sitios o publicaciones comparten identificadores de entradas, por ejemplo una entrada traducida en dos sitios monolingües, define feeds: { entryIds: "publication" }. El identificador incluye entonces el host y la ruta de la publicación, de modo que los lectores de feeds conservan ambas entradas. Los lectores tratan las entradas con identificadores nuevos como entradas nuevas, así que elige la opción antes del primer lanzamiento o acepta una ronda de entradas repetidas.

Markdown normal se exporta directamente. Si MDX contiene componentes, expresiones, sentencias de módulo o HTML que la proyección estática omitiría, proporciona el artículo portátil completo como Markdown en feedContent. El build informa de las representaciones que faltan.

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

El componente MDX Image predeterminado muestra los metadatos de imagen preparados, por ejemplo <Image src="./detail.jpg" alt="The trail" />. Los componentes JSX también necesitan una representación portátil en feedContent. Los elementos literales <img> en minúsculas siguen el comportamiento JSX normal; usa imágenes Markdown o Image para el tratamiento automático de imágenes de publicación.

Versiones de documentación e idiomas

Las URL de publicación siguen siendo independientes de las versiones de documentación. Si el versionado está activado, selecciona directorios documentales completos y mantén la publicación fuera de ellos:

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

Así, la página de inicio está en /, las entradas en /news/... y las guías en /v2/guide/.... Todas las URL respetan también la base del despliegue. Sin directories, los proyectos existentes conservan el versionado de todo el sitio. Consulta la configuración para el comportamiento de migración.

Con localización estricta activada, organiza las entradas bajo posts/<locale>/. Ardo genera /<locale>/news/ y sus feeds para cada idioma configurado. La validación existente del árbol completo de rutas sigue vigente; esta función no introduce traducciones de respaldo. Pasa los textos de interfaz traducidos mediante labels.publication de ArdoRoot.

Archivos de etiquetas

Define tags: true para generar una página por etiqueta en /news/tags/<key>. El sitemap incluye estas páginas. Las claves de etiqueta deben ser slugs en minúsculas con guiones, como release-notes. El build falla cuando una clave no coincide, cuando una entrada repite una clave o cuando la ruta de una entrada queda bajo /news/tags. Los feeds mantienen la clave como categoría. Con archivos, las etiquetas de una entrada enlazan a su archivo. Sin archivos, las etiquetas pueden ser cualquier texto. Con i18n, cada idioma necesita las mismas claves de etiqueta, porque cada página localizada debe existir en todos los idiomas.

Nombres de etiqueta

Una clave de etiqueta es la identidad de la etiqueta en las URL, el sitemap y los feeds, así que es la misma en todos los idiomas. Para mostrar en su lugar un nombre legible o traducido, define tagLabel con un módulo cuya exportación por defecto asigne a cada clave su nombre:

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

Ardo llama a la función mientras renderiza una página, dentro del contexto de renderizado del servidor, para que pueda usar las traducciones del sitio. Con Palamedes, da a cada clave un mensaje, para que i18n:extract lo encuentre:

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

El nombre aparece en el encabezado y en el título predeterminado del archivo de la etiqueta, y en la lista de etiquetas de una entrada. Tus propios componentes lo reciben como label o lo leen con useArdoPublicationTags() de ardo/ui. Solo las páginas de publicación generadas importan el módulo. Los feeds mantienen la clave, porque Ardo los genera sin un idioma activo. Sin tagLabel, las páginas muestran la clave.

Presentación y metadatos propios

Un sitio con diseño propio puede renderizar las páginas generadas con sus propios módulos de ruta. Las rutas son relativas a la raíz del proyecto:

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

Cada módulo exporta por defecto un componente de React. index recibe { publication }, post recibe { post, children } y envuelve el artículo renderizado en lugar de ArdoPost, y tag recibe { publication, tag, label, posts }. Un módulo también puede exportar meta. Ardo lo llama al renderizar la ruta, como la exportación meta de cualquier ruta, con los datos de la ruta y defaults, los descriptores que Ardo renderizaría sin él. La lista devuelta sustituye a los valores predeterminados, incluido el enlace canónico y las etiquetas Open Graph, Twitter y JSON-LD; expande defaults para conservarlos. Sin exportación meta, se aplican los metadatos de Ardo.

Los defaults de una entrada contienen un elemento JSON-LD BlogPosting, { "script:ld+json": … }, con el titular, la descripción, la URL canónica, el idioma, las fechas, los autores, la imagen propia de la entrada y el sitio. Si expandes defaults, se conserva. Un filtro que descarte descriptores debe conservar las entradas en las que se cumpla "script:ld+json" in entry, como en el ejemplo siguiente. seo.jsonLd: false desactiva el elemento. Su mainEntityOfPage apunta a la URL canónica de Ardo, así que un módulo que sustituya el enlace canónico también debería sustituir o eliminar el 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 función meta se ejecuta durante el renderizado, así que puede traducir como label. Los tipos de módulo PublicationIndexModule, PublicationPostModule y PublicationTagModule de ardo/config describen las exportaciones. Cuando una exportación no coincide con su tipo, la ruta generada hace fallar la comprobación de tipos del sitio. Todas las páginas y módulos comparten los datos de la publicación, por eso Ardo los congela, y sus listas son de solo lectura: ordena una copia, como [...publication.posts].sort(…). defaults es una lista nueva en cada llamada. Los valores predeterminados del índice, de las entradas y de los archivos de etiquetas terminan todos con los enlaces de descubrimiento Atom y RSS de la publicación. Con un módulo de entrada, el build falla cuando una entrada exporta su propio meta, porque eso eliminaría los enlaces canónico, Open Graph y de feed de la entrada; varía los metadatos en el meta del módulo. Sin módulo de entrada, el meta propio de una entrada sustituye los metadatos de Ardo, como en cualquier página.

Campos propios de las entradas

Los campos de frontmatter que Ardo no lee llegan a la entrada como post.data, por ejemplo nextStep: /contact. El módulo de entrada los recibe en sus props y en meta; comprueba el tipo de cada valor antes de usarlo. Se quedan en la página propia de la entrada: las entradas de los listados y de virtual:ardo/publication tienen un data vacío, para que los campos de una entrada no viajen con todas las demás páginas. La raíz lee los mismos campos con useArdoPage().frontmatter.

Solo las rutas de publicación generadas importan estos módulos. El marco de entrada forma parte de las páginas de entradas, no de la documentación ni de otras páginas. Con i18n, Ardo sigue añadiendo los enlaces alternativos de idioma de cada página y un enlace canónico cuando los metadatos devueltos no tienen ninguno.

Datos de página para la raíz

El índice y los archivos de etiquetas no tienen frontmatter propio. Sus módulos pueden exportar frontmatter para dar a la raíz datos de página, como un enlace a la misma página en otro idioma. Ardo la llama al renderizar la página, como meta, con { publication } para el índice y { publication, tag, label, posts } para cada archivo de etiqueta. La raíz lee el resultado con useArdoPage().frontmatter, en el servidor y durante la hidratación, igual que lee los campos de una entrada. Sin la exportación, estas páginas no tienen 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 no escribe datos de página en el bundle. La ruta de cada archivo de etiqueta contiene su propia etiqueta y sus entradas y las pasa a la función. Todo lo que el módulo importa, como una lista de etiquetas traducidas, se entrega con el módulo a cada archivo de etiqueta.

Diseños personalizados y metadatos AT

Importa los datos de publicación desde virtual:ardo/publication para reutilizarlos en otro lugar. La exportación predeterminada es la publicación del idioma predeterminado; publications asigna los identificadores de idioma (o default sin localización) a sus datos. ArdoPostList, ArdoPost, ArdoImage y ardoImagePresets están disponibles desde ardo/ui. El contenido fuente de las entradas sigue siendo MDX; la exportación pública contiene metadatos y descriptores de imágenes preparados. Con archivos de etiquetas, publication.tags enumera la clave, la ruta y la URL de cada etiqueta; pasa una como tag a ArdoPostList para listar solo sus entradas.

Utiliza ArdoPostNavigation de ardo/ui para una navegación compacta entre artículos. Pasa la publicación del idioma actual mediante la prop mobileMenuContent de ArdoHeader para completar el menú móvil de una página de noticias. El componente muestra los diez artículos publicados más recientes por defecto, destaca la página actual y enlaza al índice completo de la publicación mediante «Todos los artículos». Define limit para cambiar la longitud de la lista. Traduce labels.publication.recentPosts y labels.publication.allPosts junto con las demás etiquetas de publicación.

Los nombres de metadatos siguen, cuando corresponde, el léxico de documentos de Standard.site: title, description, publishedAt, updatedAt, tags, coverImage y path. Las claves locales de autores, las rutas de imágenes fuente, los metadatos de encuadre, id, draft y feedContent son campos de creación de Ardo. Un futuro publicador AT los traducirá al exportar. Los builds normales generan el sitio estático y los feeds; no publican en una cuenta AT.

Editar esta página en GitHubÚltima actualización: 13 de noviembre de 2026