Taxonomias

Uma taxonomia é uma classificação nomeada aplicada a uma ou mais collections. O EmDash começa com a taxonomia hierárquica category e a taxonomia plana tag para posts. Um site também pode definir taxonomias como genre, topic ou difficulty.

Os termos pertencem a uma taxonomia. Uma categoria como “Guides” pode ter categorias filhas, enquanto tags e outras taxonomias planas têm um nível.

Gerenciar termos

Abra uma taxonomia em Taxonomies na administração do EmDash.

Editores atribuem termos pelos painéis de taxonomia em uma entrada de conteúdo. A definição da taxonomia controla quais collections mostram cada painel.

Excluir um termo remove suas atribuições do conteúdo. Não exclui as entradas de conteúdo.

Adicionar uma tag a vários posts

Editores podem selecionar posts em uma lista de collection e clicar em Add tag, ou abrir Tags e clicar em Add to posts para colar URLs públicas de posts (uma por linha, até 50). Escolha uma tag existente ou crie uma no diálogo e clique em Review posts. Confira cada título e idioma correspondentes e clique no botão que mostra quantos posts serão marcados. Links que não correspondem exatamente a um post publicado neste site são sinalizados em vez de adivinhados.

Adicionar a tag tem efeito imediato, mesmo quando um post tem outras edições de rascunho não publicadas; não publica essas edições. Tags existentes permanecem, e posts que já têm a tag são ignorados. A lista de resultados mostra quais posts foram marcados, ignorados ou não puderam ser marcados; use Retry failures para falhas de escrita. A correspondência de URL usa a origem pública configurada do site e os padrões de URL das collections, incluindo caminhos de data e idioma.

Adicionar uma taxonomia personalizada

Crie uma taxonomia quando uma collection existente precisar de uma classificação separada.

Templates consultam o nome estável. Alterar um rótulo de exibição não exige mudança de template.

Taxonomias personalizadas usam os mesmos helpers de consulta e filtro que categorias e tags. O exemplo a seguir lê os termos genre e filtra livros por um de seus slugs:

import { getEmDashCollection, getTaxonomyTerms } from "emdash";

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

Excluir uma taxonomia

Abra a taxonomia na administração, escolha Delete taxonomy no menu de ações do cabeçalho da página e confirme. A ação exige a permissão taxonomies:manage, que editores e administradores possuem.

Excluir uma taxonomia exclui seus termos em todos os idiomas e remove esses termos do conteúdo arquivado sob eles. As entradas de conteúdo em si são mantidas.

Consultar uma lista de termos

Use getTaxonomyTerms() para renderizar um índice de taxonomia, uma lista de navegação ou um conjunto de filtros. Taxonomias hierárquicas retornam uma árvore pelo array children de cada termo.

Contagens de termos são incluídas por padrão e exigem uma agregação nas collections atribuídas da taxonomia. Pule esse trabalho quando o componente não exibir contagens.

O componente a seguir renderiza links de categoria sem contagens:

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

Quando um componente exibe o uso, omita includeCounts: false e renderize term.count. A contagem inclui entradas visíveis publicamente no locale usado na consulta.

Construir um arquivo de taxonomia

Decodifique um parâmetro de rota dinâmica antes de procurar um termo. Consulte o termo e o conteúdo com o mesmo locale e passe os caminhos gerados pelo helper de URL de locale do Astro.

A rota a seguir lista posts publicados em uma categoria:

---
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 o nome da taxonomia como chave e um slug de termo como valor. Identificadores de ordenação de consulta usam nomes de campo do banco como published_at; os dados da entrada expõem o valor correspondente como publishedAt.

Use a rota pública real da collection em postHref(). Se a collection usar um urlPattern personalizado, construa links a partir desse padrão em vez de assumir /posts/{slug}.

Exibir os termos de uma entrada

getEmDashEntry() e getEmDashCollection() hidratam termos atribuídos em entry.data.terms. Leia esse valor em vez de executar uma consulta getEntryTerms() para cada entrada em uma lista.

O componente a seguir renderiza categorias e tags já carregadas com um 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>
)}

Use getEntryTerms() quando tiver apenas um nome de collection e um ID de entrada. Use getTermsForEntries() para agrupar termos de várias entradas quando não foram hidratados pela consulta de conteúdo.

Traduzir taxonomias e termos

Definições de taxonomia e termos têm uma linha por locale. O EmDash registra quais linhas são traduções da mesma taxonomia ou termo. Atribuições de conteúdo usam essa identidade compartilhada, de modo que uma atribuição feita em um locale resolve para o termo traduzido em outro locale quando um existe.

Uma definição de taxonomia divide seus campos entre a taxonomia e cada locale:

Uma definição criada para um nome que já existe em outro locale junta-se a essa taxonomia, com ou sem translationOf, e assume seus hierarchical e collections. Criá-la com valores diferentes falha; altere-os com uma atualização. Um locale sem definição própria ainda lista os termos da taxonomia e mostra o rótulo do primeiro locale em sua cadeia de fallback que tenha um, senão o rótulo do locale padrão, senão o rótulo do locale com o código de locale mais baixo.

Use o seletor de locale em uma página de taxonomia para gerenciar termos em cada locale configurado. Abra o diálogo de edição de um termo e use seu painel Translations para adicionar ou abrir outro locale. Um termo traduzido pode usar um slug e um rótulo diferentes.

O pai e a posição de um termo são compartilhados por cada locale. Uma tradução criada sem pai assume o pai e a posição do seu termo. Criar uma tradução sob um pai diferente, ou alterar o pai por qualquer locale, move o termo em cada locale.

Os helpers de consulta usam um locale explícito quando fornecido. Caso contrário, usam o locale da solicitação atual e depois o padrão configurado. Consultas de um único termo seguem a cadeia de fallback configurada quando a tradução solicitada estiver ausente.

Veja Internationalization para roteamento de locale e configuração de fallback e Working with Content para editar entradas. A referência da API de runtime documenta os helpers de consulta de taxonomia. Para alterações programáticas, autentique-se com um token Bearer e adicione X-EmDash-Request: 1 a cada solicitação que altere o estado. Veja os endpoints de taxonomia para corpos de solicitação e respostas.