Astro Content Collections: Pozvedněte svůj web pomocí správy obsahu s bezpečným typem

Astro, populární generátor statických stránek, nabízí výkonnou funkci s názvem Content Collections. Tento systém poskytuje strukturovaný a typově bezpečný způsob správy obsahu vašeho webu, zajišťuje konzistenci, snižuje chyby a zlepšuje celkový vývojářský zážitek. Ať už vytváříte osobní blog, dokumentační web nebo složitou platformu elektronického obchodu, Content Collections mohou výrazně zefektivnit váš pracovní postup.

Co jsou Astro Content Collections?

Content Collections jsou vyhrazený adresář ve vašem projektu Astro, kde organizujete soubory obsahu (obvykle Markdown nebo MDX). Každá kolekce je definována schématem, které určuje očekávanou strukturu a datové typy frontmatteru vašeho obsahu (metadata na začátku každého souboru). Toto schéma zajišťuje, že veškerý obsah v kolekci dodržuje konzistentní formát, čímž se předchází nekonzistencím a chybám, které mohou vzniknout při ručním zadávání dat.

Představte si to jako databázi, ale pro vaše soubory s obsahem. Místo ukládání obsahu do databázového serveru se ukládá v prostých textových souborech, což nabízí výhody správy verzí a umožňuje vám uchovávat obsah blízko kódu. Nicméně, na rozdíl od pouhého mít složku souborů Markdown, Content Collections vynucují strukturu a typovou bezpečnost prostřednictvím schématu.

Proč používat Content Collections?

• Typová bezpečnost: Integrace s TypeScriptem zajišťuje, že jsou data vašeho obsahu typově kontrolována během vývoje, čímž se chyby zachytí včas a zabrání se problémům za běhu. To je zvláště užitečné ve větších projektech s více přispěvateli.
• Validace schématu: Definované schéma validuje frontmatter každého souboru s obsahem, čímž zajišťuje, že jsou všechna povinná pole přítomna a mají správný datový typ.
• Vylepšená konzistence obsahu: Vynucením konzistentní struktury pomáhají Content Collections udržovat jednotný vzhled a dojem na vašem webu.
• Vylepšená vývojářská zkušenost: Typově bezpečné API poskytuje vynikající automatické dokončování a detekci chyb ve vašem IDE, čímž usnadňuje a zefektivňuje správu obsahu.
• Zjednodušený přístup k datům: Astro poskytuje pohodlné API pro dotazování a přístup k obsahu z vašich kolekcí, čímž zjednodušuje načítání dat ve vašich komponentách.
• Organizace obsahu: Kolekce poskytují jasnou a logickou strukturu pro organizaci vašeho obsahu, čímž usnadňují jeho vyhledávání a správu. Například dokumentační web může mít kolekce pro "guides", "api-reference" a "changelog".

Začínáme s Content Collections

Zde je podrobný návod k implementaci Content Collections ve vašem projektu Astro:

1. Povolte Content Collections

Nejprve povolte integraci @astrojs/content ve vašem souboru astro.config.mjs (nebo astro.config.js):

            // astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { contentIntegration } from '@astrojs/content'

export default defineConfig({
  integrations: [
    mdx(),
    contentIntegration()
  ],
});

            

              
                Copy
              
            
          

2. Vytvořte adresář Content Collection

Vytvořte adresář s názvem src/content/[collection-name], kde [collection-name] je název vaší kolekce (např. src/content/blog). Astro automaticky rozpozná tento adresář jako content collection.

Například pro vytvoření kolekce 'blog' by měla struktura vašeho projektu vypadat takto:

  src/
    content/
      blog/
        my-first-post.md
        my-second-post.md
        ...
    pages/
    ...

3. Definujte schéma kolekce

Vytvořte soubor src/content/config.ts (nebo src/content/config.js) pro definování schématu vaší kolekce. Tento soubor exportuje objekt config, který určuje schéma pro každou kolekci.

Zde je příklad schématu pro kolekci 'blog':

            // src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z
      .string()
      .or(z.date())
      .transform((val) => new Date(val)),
    updatedDate: z
      .string()
      .optional()
      .transform((str) => (str ? new Date(str) : undefined)),
    heroImage: z.string().optional(),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = {
  blog,
};

            

              
                Copy
              
            
          

Vysvětlení:

• defineCollection: Tato funkce se používá k definování content collection.
• schema: Tato vlastnost definuje schéma pro frontmatter kolekce.
• z.object: Toto definuje schéma jako objekt JavaScriptu. Používáme Zod pro validaci schématu, populární TypeScript-first knihovnu pro deklaraci a validaci schématu.
• z.string(), z.date(), z.array(): Toto jsou typy schématu Zod, které určují očekávané datové typy pro každé pole.
• z.optional(): Umožňuje, aby bylo pole volitelné.
• transform: Používá se k transformaci dat frontmatter. V tomto případě zajišťujeme, aby pubDate a updatedDate byly objekty Date.

4. Vytvořte soubory obsahu

Vytvořte soubory Markdown nebo MDX ve vašem adresáři kolekce (např. src/content/blog/my-first-post.md). Každý soubor by měl obsahovat frontmatter, který odpovídá schématu, které jste definovali.

Zde je příklad souboru Markdown s frontmatter:

            ---
title: My First Blog Post
description: This is a short description of my first blog post.
pubDate: 2023-10-27
heroImage: /images/my-first-post.jpg
tags:
  - astro
  - blog
  - javascript
---

# My First Blog Post

This is the content of my first blog post.

            

              
                Copy
              
            
          

5. Získejte přístup k obsahu ve svých komponentách

Použijte funkci getCollection() z astro:content k načtení obsahu z vašich kolekcí ve vašich komponentách Astro. Tato funkce vrací pole záznamů, z nichž každý reprezentuje soubor obsahu.

            // src/pages/blog.astro
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');

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

            

              
                Copy
              
            
          

Vysvětlení:

• getCollection('blog'): Načte všechny položky z kolekce 'blog'.
• post.slug: 'Slug' je jedinečný identifikátor pro každý soubor obsahu, automaticky generovaný z názvu souboru (např. 'my-first-post' pro 'my-first-post.md').
• post.data: Obsahuje data frontmatter pro každou položku, typově zkontrolovaná podle schématu.

Pokročilé funkce a přizpůsobení

Content Collections nabízejí několik pokročilých funkcí a možností přizpůsobení pro přizpůsobení systému vašim specifickým potřebám:

1. Podpora MDX

Content Collections se bezproblémově integrují s MDX, což vám umožňuje vkládat komponenty JSX přímo do vašeho obsahu Markdown. To je užitečné pro vytváření interaktivního a dynamického obsahu.

Chcete-li použít MDX, nainstalujte integraci @astrojs/mdx a nakonfigurujte ji ve vašem souboru astro.config.mjs (jak je uvedeno v kroku 1). Poté vytvořte soubory MDX (např. my-post.mdx) a použijte syntaxi JSX ve svém obsahu.

            ---
title: My MDX Post
description: This post uses MDX.
---

# My MDX Post

<MyComponent prop1="value1" prop2={2} />

This is some regular Markdown content.

            

              
                Copy
              
            
          

2. Vlastní typy schématu

Zod poskytuje širokou škálu vestavěných typů schématu, včetně string, number, boolean, date, array a object. Můžete také definovat vlastní typy schématu pomocí metody .refine() Zodu, abyste vynutili konkrétnější pravidla ověřování.

Například byste mohli ověřit, zda je řetězec platná URL:

            // src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    url: z.string().url(), // Validates that the string is a URL
  }),
});

export const collections = {
  blog,
};

            

              
                Copy
              
            
          

3. Vlastní generování slug

Ve výchozím nastavení Astro generuje slug pro každý soubor obsahu z názvu souboru. Toto chování můžete přizpůsobit poskytnutím vlastnosti slug ve frontmatteru nebo použitím vlastnosti entry.id k vytvoření vlastního slug na základě cesty k souboru.

Například pro použití cesty k souboru ke generování slug:

            // src/pages/blog/[...slug].astro
import { getCollection, type CollectionEntry } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug }, // Use the default slug
    props: {
      post,
    },
  }));
}

type Props = {
  post: CollectionEntry<'blog'>;
};

const { post } = Astro.props as Props;

            

              
                Copy
              
            
          

4. Filtrování a řazení obsahu

Můžete použít metody pole JavaScriptu (filter, sort atd.) k dalšímu zpřesnění obsahu načteného z vašich kolekcí. Například byste mohli filtrovat příspěvky na základě jejich tagů nebo je seřadit podle data publikování.

            // src/pages/blog.astro
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');

const featuredPosts = posts.filter((post) => post.data.tags?.includes('featured'));
const sortedPosts = posts.sort((a, b) => new Date(b.data.pubDate).getTime() - new Date(a.data.pubDate).getTime());

            

              
                Copy
              
            
          

5. Internacionalizace (i18n)

Zatímco Content Collections přímo neposkytují funkce i18n, můžete implementovat internacionalizaci vytvořením samostatných content collection pro každý jazyk nebo použitím pole frontmatter k označení jazyka každého souboru obsahu.

Příklad s použitím samostatných kolekcí:

  src/
    content/
      blog-en/
        my-first-post.md
      blog-es/
        mi-primer-articulo.md

Poté byste měli dvě definice kolekcí: blog-en a blog-es, každá s příslušným obsahem.

Příklad s použitím pole lang ve frontmatter:

            ---
title: My First Blog Post
lang: en
---

# My First Blog Post

            

              
                Copy
              
            
          

Poté byste filtrovali kolekci na základě pole lang, abyste načetli správný obsah pro každý jazyk.

Osvědčené postupy pro používání Content Collections

• Pečlivě naplánujte své schéma: Přemýšlejte o struktuře a datových typech svého obsahu před definováním schématu. Dobře navržené schéma usnadní a zefektivní správu vašeho obsahu v dlouhodobém horizontu.
• Používejte popisné názvy polí: Vyberte názvy polí, které jsou jasné a samovysvětlující. Zlepšíte tak čitelnost a udržovatelnost kódu.
• Poskytněte jasné popisy pro každé pole: Použijte vlastnost description ve schématu Zod k poskytnutí užitečných popisů pro každé pole. To pomůže ostatním vývojářům (a vaší budoucí osobě) pochopit účel každého pole.
• Vynucujte povinná pole: Použijte metodu required() Zodu k zajištění toho, aby byla všechna povinná pole přítomna ve frontmatteru.
• Používejte volitelná pole střídmě: Používejte volitelná pole pouze tehdy, když jsou skutečně volitelná. Vynucování povinných polí pomáhá udržovat konzistenci a předcházet chybám.
• Dokumentujte své kolekce: Vytvořte dokumentaci pro své content collection, která vysvětluje účel každé kolekce, strukturu schématu a veškerá specifická pravidla ověřování.
• Udržujte svůj obsah organizovaný: Používejte konzistentní konvenci pojmenovávání pro své soubory obsahu a organizujte je do logických adresářů ve vašich kolekcích.
• Důkladně otestujte své kolekce: Napište testy, abyste zajistili, že vaše content collection fungují správně a že vaše schéma ověřuje frontmatter podle očekávání.
• Zvažte použití CMS pro autory obsahu: Pro webové stránky s velkým obsahem zvažte propojení Astro s Headless CMS. To poskytne uživatelsky přívětivé rozhraní pro tvůrce obsahu, kteří nepotřebují pracovat s kódem. Příklady zahrnují Contentful, Strapi a Sanity.

Příklady použití: Od osobních blogů po globální e-commerce

• Osobní blog: Spravujte příspěvky na blogu s poli pro název, datum publikování, autora, obsah a tagy. To umožňuje snadné aktualizace obsahu, generování blog roll a výpis kategorií.
• Dokumentační web: Strukturujte dokumentační stránky s poli pro název, verzi, kategorii a obsah. Umožňuje konzistentní strukturu dokumentace a snadnou navigaci mezi různými verzemi. Zvažte velký open-source projekt, jako je Kubernetes, kde je dokumentace kritická.
• Marketingový web: Definujte stránky s poli pro název, popis, klíčová slova a obsah. Optimalizujte obsah pro SEO a udržujte konzistenci značky na všech stránkách.
• Platforma elektronického obchodu: Katalog produktů s poli pro název, cenu, popis, obrázky a kategorie. Implementujte dynamické výpisy produktů a usnadněte snadné aktualizace produktů. Pro globální příklad elektronického obchodu zvažte různé kolekce založené na regionu, abyste vyhověli místním trhům a právním požadavkům. To by umožnilo různá pole, jako jsou daňové informace nebo regulační prohlášení, v závislosti na zemi.
• Znalostní báze: Organizujte články s poli pro název, téma, autora a obsah. Umožněte uživatelům snadno vyhledávat a procházet články podle tématu.

Závěr