Taxonomies

Les taxonomies sont des systèmes de classification pour organiser le contenu. EmDash inclut des catégories et des tags intégrés, et supporte des taxonomies personnalisées pour des besoins de classification spécialisés.

Taxonomies intégrées

EmDash fournit deux taxonomies par défaut :

Les deux sont disponibles pour la collection de posts par défaut.

Gérer les termes

Créer un terme

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

{
  "slug": "tutorials",
  "label": "Tutoriels",
  "parentId": "term_abc",
  "description": "Guides pratiques et tutoriels"
}

Modifier un terme

1. Allez à la page des termes de la taxonomie

2. Cliquez sur Modifier à côté du terme

3. Mettez à jour le nom, le slug, le parent ou la description

4. Cliquez sur Sauvegarder

Supprimer un terme

1. Allez à la page des termes de la taxonomie

2. Cliquez sur Supprimer à côté du terme

3. Confirmez la suppression

Interroger les taxonomies

EmDash fournit des fonctions pour interroger les termes de taxonomie et filtrer le contenu par terme.

Obtenir tous les termes

Récupérez tous les termes d’une taxonomie :

import { getTaxonomyTerms } from "emdash";

// Obtenir toutes les catégories (retourne une structure arborescente)
const categories = await getTaxonomyTerms("category");

// Obtenir tous les tags (retourne une liste plate)
const tags = await getTaxonomyTerms("tag");

Pour les taxonomies hiérarchiques, les termes incluent un tableau children :

interface TaxonomyTerm {
	id: string;
	name: string; // Nom de taxonomie ("category")
	slug: string; // Slug du terme ("news")
	label: string; // Label d'affichage ("News")
	parentId?: string;
	description?: string;
	children: TaxonomyTerm[];
	count?: number; // Nombre d'entrées avec ce terme
}

Calculer count agrège chaque assignation contenu-terme dans les collections de la taxonomie, ce qui est la partie la plus coûteuse de l’appel. Si vous n’avez besoin que de labels et slugs, omettez-le — count est alors exclu des termes retournés :

const tags = await getTaxonomyTerms("tag", { includeCounts: false });

Obtenir un seul terme

L’exemple suivant récupère un terme par taxonomie et slug :

import { getTerm } from "emdash";

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

Obtenir les termes d’une entrée

L’exemple suivant récupère les catégories et tags assignés à une seule entrée :

import { getEntryTerms } from "emdash";

// Obtenir toutes les catégories d'un post
const categories = await getEntryTerms("posts", "post-123", "category");

// Obtenir tous les tags d'un post
const tags = await getEntryTerms("posts", "post-123", "tag");

Filtrer le contenu par terme

Utilisez getEmDashCollection avec le filtre where :

import { getEmDashCollection } from "emdash";

// Posts dans la catégorie "news"
const { entries: newsPosts } = await getEmDashCollection("posts", {
	status: "published",
	where: { category: "news" },
});

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

Ou utilisez la fonction de commodité :

import { getEntriesByTerm } from "emdash";

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

Créer des pages de taxonomie

Archive de catégorie

Créez une page qui liste les posts d’une catégorie :

---
import { getTaxonomyTerms, getTerm, getEmDashCollection } from "emdash";
import Base from "../../layouts/Base.astro";

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

  // Aplatir l'arbre hiérarchique pour le routage
  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} articles</p>

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

Archive de tag

Créez une page qui liste les posts avec un tag :

---
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 taggés "${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 liste de catégories

Affichez une liste de catégories avec le nombre de posts :

---
import { getTaxonomyTerms } from "emdash";

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

<nav class="category-list">
  <h3>Catégories</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>

Nuage de tags

Affichez des tags avec une taille basée sur l’utilisation :

---
import { getTaxonomyTerms } from "emdash";

const tags = await getTaxonomyTerms("tag");

// Calculer les tailles de police basées sur le comptage
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>

Afficher les termes sur le contenu

Affichez les catégories et tags sur un post :

---
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>Publié dans :</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>

Taxonomies personnalisées

Créez des taxonomies au-delà des catégories et tags pour des besoins spécialisés.

Créer une taxonomie personnalisée

Utilisez l’API admin pour créer une taxonomie :

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

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

Utiliser les taxonomies personnalisées

Interrogez et affichez les taxonomies personnalisées de la même manière que les intégrées :

import { getTaxonomyTerms, getEmDashCollection } from "emdash";

// Obtenir tous les genres
const genres = await getTaxonomyTerms("genre");

// Obtenir les livres d'un genre
const { entries: sciFiBooks } = await getEmDashCollection("books", {
	where: { genre: "science-fiction" },
});

Assigner aux collections

Les taxonomies spécifient à quelles collections elles s’appliquent :

{
  "name": "difficulty",
  "label": "Niveaux de difficulté",
  "hierarchical": false,
  "collections": ["recipes", "tutorials"]
}

Référence API des taxonomies

Endpoints REST

Assigner des termes au contenu

La requête suivante assigne des termes de catégorie à un post :

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

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

Prochaines étapes

• Créer un blog - Utiliser les catégories et tags dans un blog
• Interroger le contenu - Filtrer par termes de taxonomie
• Travailler avec le contenu - Assigner des termes dans l’éditeur