Taxonomias

Taxonomias são sistemas de classificação para organizar conteúdo. O EmDash inclui categorias e tags integradas, e suporta taxonomias personalizadas para necessidades de classificação especializadas.

Taxonomias Integradas

O EmDash fornece duas taxonomias padrão:

Taxonomia	Tipo	Descrição
Categorias	Hierárquica	Classificação aninhada com relações pai-filho
Tags	Plana	Rótulos simples sem hierarquia

Ambas estão disponíveis para a coleção de posts por padrão.

Gerenciando Termos

Criar um Termo

Painel de Administração

1. Vá para a página da taxonomia (ex: /_emdash/admin/taxonomies/category)

2. Digite o nome do termo no formulário Adicionar Novo

3. Opcionalmente, defina:

   • Slug - Identificador da URL (gerado automaticamente a partir do nome)
   • Pai - Para taxonomias hierárquicas
   • Descrição - Descrição do termo

4. Clique em Adicionar

Editor de Conteúdo

5. Abra uma entrada de conteúdo no editor

6. Encontre o painel da taxonomia na barra lateral

7. Para categorias: marque as caixas para os termos aplicáveis, ou clique em + Adicionar Novo

8. Para tags: digite os nomes das tags separados por vírgulas

9. Salve o conteúdo

API

POST /_emdash/api/taxonomies/category/terms
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "slug": "tutorials",
  "label": "Tutoriais",
  "parentId": "term_abc",
  "description": "Guias práticos e tutoriais"
}

Editar um Termo

1. Vá para a página de termos da taxonomia

2. Clique em Editar ao lado do termo

3. Atualize o nome, slug, pai ou descrição

4. Clique em Salvar

Excluir um Termo

1. Vá para a página de termos da taxonomia

2. Clique em Excluir ao lado do termo

3. Confirme a exclusão

Cuidado

Excluir um termo o remove de todo o conteúdo associado. O conteúdo não é excluído, apenas a atribuição do termo.

Consultando Taxonomias

O EmDash fornece funções para consultar termos de taxonomia e filtrar conteúdo por termo.

Obter Todos os Termos

Recupere todos os termos de uma taxonomia:

import { getTaxonomyTerms } from "emdash";

// Obter todas as categorias (retorna estrutura em árvore)
const categories = await getTaxonomyTerms("category");

// Obter todas as tags (retorna lista plana)
const tags = await getTaxonomyTerms("tag");

Para taxonomias hierárquicas, os termos incluem um array children:

interface TaxonomyTerm {
  id: string;
  name: string; // Taxonomy name ("category")
  slug: string; // Term slug ("news")
  label: string; // Display label ("News")
  parentId?: string;
  description?: string;
  children: TaxonomyTerm[];
  count?: number; // Number of entries with this term
}

Obter um Único Termo

import { getTerm } from "emdash";

const category = await getTerm("category", "news");
// Retorna TaxonomyTerm ou null

Obter Termos para uma Entrada

import { getEntryTerms } from "emdash";

// Obter todas as categorias para um post
const categories = await getEntryTerms("posts", "post-123", "category");

// Obter todas as tags para um post
const tags = await getEntryTerms("posts", "post-123", "tag");

Filtrar Conteúdo por Termo

Use getEmDashCollection com o filtro where:

import { getEmDashCollection } from "emdash";

// Posts na categoria "news"
const { entries: newsPosts } = await getEmDashCollection("posts", {
  status: "published",
  where: { category: "news" },
});

// Posts com a tag "javascript"
const { entries: jsPosts } = await getEmDashCollection("posts", {
  status: "published",
  where: { tag: "javascript" },
});

Ou use a função de conveniência:

import { getEntriesByTerm } from "emdash";

const newsPosts = await getEntriesByTerm("posts", "category", "news");

Construindo Páginas de Taxonomia

Arquivo de Categoria

Crie uma página que lista posts em uma categoria:

astro title="src/pages/category/[slug].astro"
---
import { getTaxonomyTerms, getTerm, getEmDashCollection } from "emdash";
import Base from "../../../layouts/Base.astro";

export async function getStaticPaths() {
  const categories = await getTaxonomyTerms("category");

  // Achatar árvore hierárquica para roteamento
  function flatten(terms) {
    return terms.flatMap((term) => [term, ...flatten(term.children)]);
  }

  return flatten(categories).map((cat) => ({
    params: { slug: cat.slug },
    props: { category: cat },
  }));
}

const { category } = Astro.props;

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

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

  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/blog/${post.data.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

Arquivo de Tag

Crie uma página que lista posts com uma tag:

astro title="src/pages/tag/[slug].astro"
---
import { getTaxonomyTerms, getEmDashCollection } from "emdash";
import Base from "../../../layouts/Base.astro";

export async function getStaticPaths() {
  const tags = await getTaxonomyTerms("tag");

  return tags.map((tag) => ({
    params: { slug: tag.slug },
    props: { tag },
  }));
}

const { tag } = Astro.props;

const { entries: posts } = await getEmDashCollection("posts", {
  status: "published",
  where: { tag: tag.slug },
});
---

<Base title={`Posts tagged "${tag.label}"`}>
  <h1>#{tag.label}</h1>

  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/blog/${post.data.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

Widget de Lista de Categorias

Exiba uma lista de categorias com contagens de posts:

astro title="src/components/CategoryList.astro"
---
import { getTaxonomyTerms } from "emdash";

const categories = await getTaxonomyTerms("category");
---

<nav class="category-list">
  <h3>Categorias</h3>
  <ul>
    {categories.map((cat) => (
      <li>
        <a href={`/category/${cat.slug}`}>
          {cat.label} ({cat.count})
        </a>
        {cat.children.length > 0 && (
          <ul>
            {cat.children.map((child) => (
              <li>
                <a href={`/category/${child.slug}`}>
                  {child.label} ({child.count})
                </a>
              </li>
            ))}
          </ul>
        )}
      </li>
    ))}
  </ul>
</nav>

Nuvem de Tags

Exiba tags com tamanho baseado no uso:

astro title="src/components/TagCloud.astro"
---
import { getTaxonomyTerms } from "emdash";

const tags = await getTaxonomyTerms("tag");

// Calcule tamanhos de fonte baseados na contagem
const counts = tags.map((t) => t.count ?? 0);
const maxCount = Math.max(...counts, 1);
const minSize = 0.8;
const maxSize = 2;

function getSize(count: number) {
  const ratio = count / maxCount;
  return minSize + ratio * (maxSize - minSize);
}
---

<div class="tag-cloud">
  {tags.map((tag) => (
    <a
      href={`/tag/${tag.slug}`}
      style={`font-size: ${getSize(tag.count ?? 0)}rem`}
    >
      {tag.label}
    </a>
  ))}
</div>

Exibindo Termos no Conteúdo

Mostre categorias e tags em um post:

astro title="src/components/PostTerms.astro"
---
import { getEntryTerms } from "emdash";

interface Props {
  collection: string;
  entryId: string;
}

const { collection, entryId } = Astro.props;

const categories = await getEntryTerms(collection, entryId, "category");
const tags = await getEntryTerms(collection, entryId, "tag");
---

<div class="post-terms">
  {categories.length > 0 && (
    <div class="categories">
      <span>Publicado em:</span>
      {categories.map((cat, i) => (
        <>
          {i > 0 && ", "}
          <a href={`/category/${cat.slug}`}>{cat.label}</a>
        </>
      ))}
    </div>
  )}

  {tags.length > 0 && (
    <div class="tags">
      {tags.map((tag) => (
        <a href={`/tag/${tag.slug}`} class="tag">
          #{tag.label}
        </a>
      ))}
    </div>
  )}
</div>

Taxonomias Personalizadas

Crie taxonomias além de categorias e tags para necessidades especializadas.

Criar uma Taxonomia Personalizada

Use a API de administração para criar uma taxonomia:

POST /_emdash/api/taxonomies
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "name": "genre",
  "label": "Genres",
  "labelSingular": "Genre",
  "hierarchical": true,
  "collections": ["books", "movies"]
}

Usar Taxonomias Personalizadas

Consulte e exiba taxonomias personalizadas da mesma forma que as integradas:

import { getTaxonomyTerms, getEmDashCollection } from "emdash";

// Obter todos os gêneros
const genres = await getTaxonomyTerms("genre");

// Obter livros em um gênero
const { entries: sciFiBooks } = await getEmDashCollection("books", {
  where: { genre: "science-fiction" },
});

Atribuir a Coleções

As taxonomias especificam a quais coleções elas se aplicam:

{
  "name": "difficulty",
  "label": "Difficulty Levels",
  "hierarchical": false,
  "collections": ["recipes", "tutorials"]
}

Referência da API de Taxonomias

Endpoints REST

Endpoint	Método	Descrição
/_emdash/api/taxonomies	GET	Listar definições de taxonomias
/_emdash/api/taxonomies	POST	Criar taxonomia
/_emdash/api/taxonomies/:name/terms	GET	Listar termos
/_emdash/api/taxonomies/:name/terms	POST	Criar termo
/_emdash/api/taxonomies/:name/terms/:slug	GET	Obter termo
/_emdash/api/taxonomies/:name/terms/:slug	PUT	Atualizar termo
/_emdash/api/taxonomies/:name/terms/:slug	DELETE	Excluir termo

Atribuir Termos ao Conteúdo

POST /_emdash/api/content/posts/post-123/terms/category
Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

{
  "termIds": ["term_news", "term_featured"]
}

Próximos Passos

• Criar um Blog - Use categorias e tags em um blog
• Consultar Conteúdo - Filtrar por termos de taxonomia
• Trabalhar com Conteúdo - Atribuir termos no editor