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 el administrador de EmDash.

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

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

Añadir un término a varios posts

Los editores pueden seleccionar posts en una lista de colección y hacer clic en Add seguido del nombre singular de la taxonomía (por ejemplo, Add tag), o abrir la página de una taxonomía y hacer clic en Add to posts para pegar las URL públicas de los posts (una por línea, hasta 50). Cuando a la colección se aplica más de una taxonomía, la lista muestra Add term y el cuadro de diálogo pregunta qué taxonomía usar. Elige un término existente o crea uno en el cuadro de diálogo y luego haz clic en Review posts. Comprueba cada título e idioma coincidente y luego haz clic en el botón que indica cuántos posts se actualizarán. Los enlaces que no coinciden exactamente con un post publicado de este sitio se marcan en lugar de adivinarse. Solo se pueden hacer coincidir las entradas de colecciones que usan la taxonomía elegida.

Añadir el término surte efecto de inmediato, incluso cuando un post tiene otras ediciones de borrador sin publicar; no publica esas ediciones. Los términos existentes se conservan y los posts que ya tienen el término se omiten. La lista de resultados muestra qué posts se actualizaron, se omitieron o no se pudieron actualizar; usa Retry failures para los fallos de escritura. La coincidencia de URL usa el origen público configurado del sitio y los patrones de URL de las colecciones, incluidas las rutas de fecha e idioma.

Añadir una taxonomía personalizada

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

Las plantillas consultan el nombre estable. Cambiar una etiqueta visible no requiere cambiar la plantilla.

Las taxonomías personalizadas usan los mismos helpers de consulta y filtrado que las categorías y las etiquetas. El siguiente ejemplo lee los términos de 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 el administrador, elige Delete taxonomy en el menú de acciones del encabezado de la página y confirma. La acción requiere el permiso taxonomies:manage, que tienen los editores y los administradores.

Eliminar una taxonomía elimina sus términos en todos los idiomas y quita esos términos del contenido clasificado 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 recuentos de términos se incluyen por defecto y requieren una agregación sobre las colecciones asignadas a la taxonomía. Omite ese trabajo cuando el componente no muestre recuentos.

El siguiente componente renderiza enlaces de categorías sin recuentos:

---
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 muestre el uso, omite includeCounts: false y renderiza term.count. El recuento incluye las entradas visibles públicamente en el locale usado para la consulta.

Crear un archivo de taxonomía

Decodifica el parámetro de una 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 helper de URL de locale de Astro.

La siguiente ruta lista los posts publicados de 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.rewrite("/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 el slug de un término como valor. Los identificadores de ordenación de las consultas usan nombres de campo de la 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 suponer /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 las 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 el nombre de una colección y el ID de una entrada. Usa getTermsForEntries() para obtener por lotes los términos de varias entradas cuando la consulta de contenido no los hidrató.

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 del mismo 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 definición propia 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 por defecto y, si no, la etiqueta del locale con el código de locale más bajo.

Usa el selector de locale de la página de una taxonomía para gestionar los términos en cada locale configurado. Abre el cuadro de diálogo de edición de un término y usa su panel Translations para añadir u 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 todos los locales. 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 desde cualquier locale, mueve el término en todos los locales.

Los helpers de consulta usan un locale explícito cuando se proporciona. En caso contrario usan el locale de la solicitud actual y después el valor por defecto configurado. Las búsquedas de un solo término siguen la cadena de fallback configurada cuando falta la traducción solicitada.

Consulta Internacionalización (i18n) para el enrutamiento por locale y la configuración de fallback, y Trabajar con contenido para editar entradas. La Referencia de la API JavaScript documenta los helpers de consulta de taxonomías. 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ías para ver los cuerpos de solicitud y las respuestas.