# Noticias y publicaciones

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

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

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.

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

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

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

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

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

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.

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

```yaml
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](<https://ardo-docs.dev/v6/es/guide/images/>) para la configuración compartida y la entrega opcional mediante URL. Los valores predeterminados siguientes se aplican sin un proveedor configurado.

## Formatos de salida {#output-formats}

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

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

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

## Seleccionar un preajuste de presentación {#select-a-presentation-preset}

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.

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

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

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

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:

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

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

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:

```ts
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](<https://ardo-docs.dev/v6/es/guide/internationalization/#server-render-context>), para que pueda usar las traducciones del sitio. Con Palamedes, da a cada clave un mensaje, para que `i18n:extract` lo encuentre:

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

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

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:

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

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

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

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.

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

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