Taxonomías

Una taxonomía es una clasificación con nombre aplicada a una o más colecciones. EmDash comienza con la taxonomía jerárquica category y la taxonomía plana tag para posts. Un sitio también puede definir taxonomías como genre, topic o difficulty.

Los términos pertenecen a una taxonomía. Una categoría como «Guides» puede tener categorías hijas, mientras que las etiquetas y otras taxonomías planas tienen un nivel.

Gestionar términos

Abre una taxonomía desde Taxonomies en la administración de EmDash.

Los editores asignan términos desde los paneles de taxonomía en una entrada de contenido. La definición de la taxonomía controla qué colecciones muestran cada panel.

Eliminar un término quita sus asignaciones del contenido. No elimina las entradas de contenido.

Añadir una etiqueta a varios posts

Los editores pueden seleccionar posts en una lista de colección y hacer clic en Add tag, o abrir Tags y hacer clic en Add to posts para pegar URLs públicas de posts (una por línea, hasta 50). Elige una etiqueta existente o crea una en el diálogo, luego haz clic en Review posts. Comprueba cada título e idioma coincidentes, luego haz clic en el botón que muestra cuántos posts se etiquetarán. Los enlaces que no coinciden exactamente con un post publicado en este sitio se marcan en lugar de adivinarse.

Añadir la etiqueta surte efecto de inmediato, incluso cuando un post tiene otras ediciones de borrador no publicadas; no publica esas ediciones. Las etiquetas existentes permanecen, y los posts que ya tienen la etiqueta se omiten. La lista de resultados muestra qué posts se etiquetaron, se omitieron o no pudieron etiquetarse; usa Retry failures para fallos de escritura. La coincidencia de URL usa el origen público configurado del sitio y los patrones de URL de las colecciones, incluidos rutas de fecha e idioma.

Añadir una taxonomía personalizada

Crea una taxonomía cuando una colección existente necesite una clasificación separada.

Las plantillas consultan el nombre estable. Cambiar una etiqueta de visualización no requiere un cambio de plantilla.

Las taxonomías personalizadas usan los mismos ayudantes de consulta y filtro que categorías y etiquetas. El siguiente ejemplo lee los términos genre y filtra libros por uno de sus slugs:

import { getEmDashCollection, getTaxonomyTerms } from "emdash";

const genres = await getTaxonomyTerms("genre", { includeCounts: false });
const { entries: scienceFictionBooks } = await getEmDashCollection("books", {
  where: { genre: "science-fiction" },
});

Eliminar una taxonomía

Abre la taxonomía en la administración, elige Delete taxonomy en el menú de acciones de la cabecera de la página y confirma. La acción requiere el permiso taxonomies:manage, que tienen editores y administradores.

Eliminar una taxonomía elimina sus términos en todos los idiomas y quita esos términos del contenido archivado bajo ellos. Las entradas de contenido en sí se conservan.

Consultar una lista de términos

Usa getTaxonomyTerms() para renderizar un índice de taxonomía, una lista de navegación o un conjunto de filtros. Las taxonomías jerárquicas devuelven un árbol a través del array children de cada término.

Los conteos de términos se incluyen por defecto y requieren una agregación entre las colecciones asignadas de la taxonomía. Omite ese trabajo cuando el componente no muestra conteos.

El siguiente componente renderiza enlaces de categoría sin conteos:

---
import { getTaxonomyTerms } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";

const locale = Astro.currentLocale;
const categories = await getTaxonomyTerms("category", {
  locale,
  includeCounts: false,
});

function categoryHref(slug: string) {
  const path = `/category/${slug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

<nav aria-label="Categories">
  <ul>
    {categories.map((category) => (
      <li>
        <a href={categoryHref(category.slug)}>{category.label}</a>
        {category.children.length > 0 && (
          <ul>
            {category.children.map((child) => (
              <li><a href={categoryHref(child.slug)}>{child.label}</a></li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
</nav>

Cuando un componente muestra el uso, omite includeCounts: false y renderiza term.count. El conteo incluye entradas visibles públicamente en el locale usado para la consulta.

Crear un archivo de taxonomía

Decodifica un parámetro de ruta dinámica antes de buscar un término. Consulta el término y el contenido con el mismo locale, y pasa las rutas generadas por el ayudante de URL de locale de Astro.

La siguiente ruta lista posts publicados en una categoría:

---
import { decodeSlug, getEmDashCollection, getTerm } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";
import Base from "../../layouts/Base.astro";

const locale = Astro.currentLocale;
const slug = decodeSlug(Astro.params.slug);
const category = slug
  ? await getTerm("category", slug, { locale, includeCounts: false })
  : null;

if (!category) {
  return Astro.redirect("/404");
}

const { entries: posts } = await getEmDashCollection("posts", {
  status: "published",
  locale,
  where: { category: category.slug },
  orderBy: { published_at: "desc" },
});

function postHref(postSlug: string) {
  const path = `/posts/${postSlug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

<Base title={`${category.label} posts`}>
  <h1>{category.label}</h1>
  {category.description && <p>{category.description}</p>}

  {posts.length > 0 ? (
    <ul>
      {posts.map((post) => (
        post.data.slug && (
          <li>
            <a href={postHref(post.data.slug)}>{post.data.title}</a>
          </li>
        )
      ))}
    </ul>
  ) : (
    <p>No posts in this category.</p>
  )}
</Base>

where usa el nombre de la taxonomía como clave y un slug de término como valor. Los identificadores de ordenación de consulta usan nombres de campo de base de datos como published_at; los datos de la entrada exponen el valor correspondiente como publishedAt.

Usa la ruta pública real de la colección en postHref(). Si la colección usa un urlPattern personalizado, construye los enlaces a partir de ese patrón en lugar de asumir /posts/{slug}.

Mostrar los términos de una entrada

getEmDashEntry() y getEmDashCollection() hidratan los términos asignados en entry.data.terms. Lee ese valor en lugar de ejecutar una consulta getEntryTerms() por cada entrada de una lista.

El siguiente componente renderiza categorías y etiquetas ya cargadas con un post:

---
import type { ContentEntry, InferCollectionData } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";

interface Props {
  post: ContentEntry<InferCollectionData<"posts">>;
}

const { post } = Astro.props;
const locale = Astro.currentLocale;
const categories = post.data.terms?.category ?? [];
const tags = post.data.terms?.tag ?? [];

function termHref(taxonomy: string, slug: string) {
  const path = `/${taxonomy}/${slug}`;
  return locale ? getRelativeLocaleUrl(locale, path) : path;
}
---

{categories.length > 0 && (
  <ul aria-label="Categories">
    {categories.map((category) => (
      <li>
        <a href={termHref("category", category.slug)}>{category.label}</a>
      </li>
    ))}
  </ul>
)}

{tags.length > 0 && (
  <ul aria-label="Tags">
    {tags.map((tag) => (
      <li>
        <a href={termHref("tag", tag.slug)}>{tag.label}</a>
      </li>
    ))}
  </ul>
)}

Usa getEntryTerms() cuando solo tengas un nombre de colección y un ID de entrada. Usa getTermsForEntries() para agrupar términos de varias entradas cuando no fueron hidratados por la consulta de contenido.

Traducir taxonomías y términos

Las definiciones de taxonomía y los términos tienen una fila por locale. EmDash registra qué filas son traducciones de la misma taxonomía o término. Las asignaciones de contenido usan esa identidad compartida, de modo que una asignación hecha en un locale se resuelve al término traducido en otro locale cuando existe.

Una definición de taxonomía reparte sus campos entre la taxonomía y cada locale:

Una definición creada para un nombre que ya existe en otro locale se une a esa taxonomía, con o sin translationOf, y toma sus hierarchical y collections. Crearla con valores distintos falla; cámbialos con una actualización. Un locale sin su propia definición sigue listando los términos de la taxonomía y muestra la etiqueta del primer locale de su cadena de fallback que tenga una, si no la etiqueta del locale predeterminado, si no la etiqueta del locale con el código de locale más bajo.

Usa el conmutador de locale en una página de taxonomía para gestionar términos en cada locale configurado. Abre el diálogo de edición de un término y usa su panel Translations para añadir o abrir otro locale. Un término traducido puede usar un slug y una etiqueta distintos.

El padre y la posición de un término son compartidos por cada locale. Una traducción creada sin padre toma el padre y la posición de su término. Crear una traducción bajo un padre distinto, o cambiar el padre a través de cualquier locale, mueve el término en cada locale.

Los ayudantes de consulta usan un locale explícito cuando se suministra. En caso contrario usan el locale de la solicitud actual, luego el predeterminado configurado. Las búsquedas de un solo término siguen la cadena de fallback configurada cuando falta la traducción solicitada.

Consulta Internationalization para el enrutamiento de locales y la configuración de fallback y Working with Content para editar entradas. La referencia de API de runtime documenta los ayudantes de consulta de taxonomía. Para cambios programáticos, autentícate con un token Bearer y añade X-EmDash-Request: 1 a cada solicitud que cambie el estado. Consulta los endpoints de taxonomía para cuerpos de solicitud y respuestas.