Astro Content Collections: Unaprijedite Svoju Web-Stranicu Upravljanjem Sadržajem Sigurnim za Vrstu

Astro, popularni generator statičkih stranica, nudi moćnu značajku pod nazivom Content Collections. Ovaj sustav pruža strukturirani i tipski siguran način upravljanja sadržajem vaše web-stranice, osiguravajući dosljednost, smanjujući pogreške i poboljšavajući cjelokupno iskustvo razvoja. Bez obzira gradite li osobni blog, stranicu s dokumentacijom ili složenu platformu za e-trgovinu, Content Collections mogu značajno pojednostaviti vaš radni proces.

Što su Astro Content Collections?

Content Collections su namjenski direktorij unutar vašeg Astro projekta u kojem organizirate datoteke sadržaja (obično Markdown ili MDX). Svaka zbirka definirana je shemom, koja specificira očekivanu strukturu i tipove podataka frontmattera vašeg sadržaja (metapodaci na početku svake datoteke). Ova shema osigurava da se sav sadržaj unutar zbirke pridržava dosljednog formata, sprječavajući nedosljednosti i pogreške koje mogu nastati ručnim unosom podataka.

Zamislite to kao bazu podataka, ali za vaše datoteke sadržaja. Umjesto pohranjivanja sadržaja u poslužitelj baze podataka, pohranjuje se u običnim tekstualnim datotekama, nudeći prednosti kontrole verzija i omogućujući vam da sadržaj držite blizu koda. Međutim, za razliku od jednostavnog posjedovanja mape Markdown datoteka, Content Collections nameću strukturu i sigurnost tipova putem sheme.

Zašto Koristiti Content Collections?

• Sigurnost tipova: Integracija TypeScripta osigurava da se podaci o vašem sadržaju provjeravaju tijekom razvoja, rano otkrivajući pogreške i sprječavajući probleme tijekom izvođenja. Ovo je osobito korisno u većim projektima s više suradnika.
• Validacija sheme: definirana shema provjerava frontmatter svake datoteke sadržaja, osiguravajući da su sva potrebna polja prisutna i ispravnog tipa podataka.
• Poboljšana dosljednost sadržaja: Nametanjem dosljedne strukture, Content Collections pomažu u održavanju jednolikog izgleda i dojma na cijeloj vašoj web-stranici.
• Poboljšano iskustvo programera: Tipski siguran API pruža izvrsno automatsko dovršavanje i otkrivanje pogrešaka u vašem IDE-u, čineći upravljanje sadržajem lakšim i učinkovitijim.
• Pojednostavljen pristup podacima: Astro pruža prikladan API za upite i pristup sadržaju iz vaših zbirki, pojednostavljujući dohvaćanje podataka u vašim komponentama.
• Organizacija sadržaja: Zbirke pružaju jasnu i logičku strukturu za organiziranje vašeg sadržaja, što olakšava pronalaženje i upravljanje. Na primjer, web-mjesto s dokumentacijom može imati zbirke za "vodiče", "api-referencu" i "changelog".

Početak s Content Collections

Evo vodiča korak po korak za implementaciju Content Collections u vašem Astro projektu:

1. Omogućite Content Collections

Prvo omogućite integraciju @astrojs/content u svojoj datoteci astro.config.mjs (ili 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. Stvorite direktorij zbirke sadržaja

Stvorite direktorij pod nazivom src/content/[naziv-zbirke] gdje je [naziv-zbirke] naziv vaše zbirke (npr. src/content/blog). Astro će automatski prepoznati ovaj direktorij kao zbirku sadržaja.

Na primjer, da biste stvorili zbirku 'blog', struktura vašeg projekta trebala bi izgledati ovako:

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

3. Definirajte shemu zbirke

Stvorite datoteku src/content/config.ts (ili src/content/config.js) da biste definirali shemu za svoju zbirku. Ova datoteka izvozi objekt config koji specificira shemu za svaku zbirku.

Evo primjera sheme za zbirku '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
              
            
          

Objašnjenje:

• defineCollection: Ova se funkcija koristi za definiranje zbirke sadržaja.
• schema: Ovo svojstvo definira shemu za frontmatter zbirke.
• z.object: Ovo definira shemu kao JavaScript objekt. Koristimo Zod za validaciju sheme, popularnu TypeScript-first biblioteku za deklaraciju i validaciju sheme.
• z.string(), z.date(), z.array(): Ovo su Zod tipovi sheme, koji specificiraju očekivane tipove podataka za svako polje.
• z.optional(): Čini polje neobaveznim.
• transform: Koristi se za transformaciju podataka frontmattera. U ovom slučaju, osiguravamo da su pubDate i updatedDate objekti tipa Date.

4. Stvorite datoteke sadržaja

Stvorite Markdown ili MDX datoteke unutar svog direktorija zbirke (npr. src/content/blog/my-first-post.md). Svaka datoteka treba sadržavati frontmatter koji je u skladu sa shemom koju ste definirali.

Evo primjera Markdown datoteke s frontmatterom:

            ---
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. Pristupite sadržaju u svojim komponentama

Koristite funkciju getCollection() iz astro:content za dohvaćanje sadržaja iz svojih zbirki u svojim Astro komponentama. Ova funkcija vraća niz unosa, od kojih svaki predstavlja datoteku sadržaja.

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

Objašnjenje:

• getCollection('blog'): Dohvaća sve unose iz zbirke 'blog'.
• post.slug: 'Slug' je jedinstveni identifikator za svaku datoteku sadržaja, automatski generiran iz naziva datoteke (npr. 'my-first-post' za 'my-first-post.md').
• post.data: Sadrži podatke frontmattera za svaki unos, tipski provjerene prema shemi.

Napredne značajke i prilagodba

Content Collections nude nekoliko naprednih značajki i mogućnosti prilagodbe kako bi se sustav prilagodio vašim specifičnim potrebama:

1. MDX podrška

Content Collections se besprijekorno integriraju s MDX-om, omogućujući vam da ugradite JSX komponente izravno u svoj Markdown sadržaj. Ovo je korisno za stvaranje interaktivnog i dinamičkog sadržaja.

Da biste koristili MDX, instalirajte integraciju @astrojs/mdx i konfigurirajte je u svojoj datoteci astro.config.mjs (kao što je prikazano u koraku 1). Zatim stvorite MDX datoteke (npr. my-post.mdx) i upotrijebite JSX sintaksu unutar svog sadržaja.

            ---
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. Prilagođeni tipovi sheme

Zod pruža širok raspon ugrađenih tipova sheme, uključujući string, number, boolean, date, array i object. Također možete definirati prilagođene tipove sheme pomoću Zodove metode .refine() da biste nametnuli specifičnija pravila validacije.

Na primjer, mogli biste provjeriti je li niz valjani 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. Prilagođena generacija slugova

Prema zadanim postavkama, Astro generira slug za svaku datoteku sadržaja iz naziva datoteke. Ovo ponašanje možete prilagoditi tako da navedete svojstvo slug u frontmatteru ili korištenjem svojstva entry.id za stvaranje prilagođenog sluga na temelju putanje datoteke.

Na primjer, za korištenje putanje datoteke za generiranje sluga:

            // 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. Filtriranje i sortiranje sadržaja

Možete koristiti JavaScript metode niza (filter, sort, itd.) za daljnje pročišćavanje sadržaja preuzetog iz vaših zbirki. Na primjer, mogli biste filtrirati postove na temelju njihovih oznaka ili ih sortirati prema datumu objave.

            // 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. Internacionalizacija (i18n)

Iako Content Collections ne pružaju izravno i18n značajke, možete implementirati internacionalizaciju stvaranjem zasebnih zbirki sadržaja za svaki jezik ili korištenjem polja frontmattera za označavanje jezika svake datoteke sadržaja.

Primjer korištenjem zasebnih zbirki:

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

Tada biste imali dvije definicije zbirki: blog-en i blog-es, svaka sa svojim odgovarajućim sadržajem.

Primjer korištenjem polja `lang` u frontmatteru:

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

# My First Blog Post

            

              
                Copy
              
            
          

Zatim biste filtrirali zbirku na temelju polja lang da biste dohvatili ispravan sadržaj za svaki jezik.

Najbolje prakse za korištenje Content Collections

• Pažljivo planirajte svoju shemu: Razmislite o strukturi i tipovima podataka vašeg sadržaja prije definiranja sheme. Dobro dizajnirana shema učinit će vaše upravljanje sadržajem lakšim i učinkovitijim dugoročno.
• Koristite deskriptivne nazive polja: Odaberite nazive polja koji su jasni i samoobjašnjivi. To će poboljšati čitljivost i održavanje koda.
• Navedite jasne opise za svako polje: Koristite svojstvo `description` u Zod shemi da biste pružili korisne opise za svako polje. To će pomoći drugim programerima (i vašem budućem ja) u razumijevanju svrhe svakog polja.
• Nametnite obavezna polja: Koristite Zodovu metodu `required()` kako biste osigurali da su sva obavezna polja prisutna u frontmatteru.
• Koristite neobavezna polja štedljivo: Koristite neobavezna polja samo kada su uistinu neobavezna. Nametanje obaveznih polja pomaže u održavanju dosljednosti i sprječavanju pogrešaka.
• Dokumentirajte svoje zbirke: Stvorite dokumentaciju za svoje zbirke sadržaja, objašnjavajući svrhu svake zbirke, strukturu sheme i sva specifična pravila validacije.
• Neka vaš sadržaj bude organiziran: Koristite dosljednu konvenciju imenovanja za svoje datoteke sadržaja i organizirajte ih u logičke direktorije unutar svojih zbirki.
• Temeljito testirajte svoje zbirke: Napišite testove kako biste osigurali da vaše zbirke sadržaja rade ispravno i da vaša shema provjerava frontmatter kako se očekuje.
• Razmislite o korištenju CMS-a za autore sadržaja: Za web-mjesta s puno sadržaja razmislite o spajanju Astra s Headless CMS-om. To će pružiti korisničko sučelje za kreatore sadržaja koji ne moraju komunicirati s kodom. Primjeri uključuju Contentful, Strapi i Sanity.

Primjeri slučajeva upotrebe: Od osobnih blogova do globalne e-trgovine

Svestranost Astro Content Collections čini ga prikladnim za širok raspon projekata:

• Osobni blog: Upravljajte objavama na blogu s poljima za naslov, datum objave, autora, sadržaj i oznake. To omogućuje jednostavno ažuriranje sadržaja, generiranje popisa blogova i popis kategorija.
• Web-mjesto s dokumentacijom: Strukturirajte stranice s dokumentacijom s poljima za naslov, verziju, kategoriju i sadržaj. Omogućuje dosljednu strukturu dokumentacije i jednostavnu navigaciju kroz različite verzije. Razmislite o velikom projektu otvorenog koda kao što je Kubernetes, gdje je dokumentacija kritična.
• Marketinško web-mjesto: Definirajte stranice s poljima za naslov, opis, ključne riječi i sadržaj. Optimizirajte sadržaj za SEO i održavajte dosljednost robne marke na svim stranicama.
• Platforma za e-trgovinu: Katalogizirajte proizvode s poljima za naziv, cijenu, opis, slike i kategorije. Implementirajte dinamički popis proizvoda i olakšajte jednostavno ažuriranje proizvoda. Za globalni primjer e-trgovine, razmislite o tome da imate različite zbirke na temelju regije kako biste zadovoljili lokalna tržišta i zakonske zahtjeve. To bi omogućilo različita polja kao što su porezne informacije ili regulatorni odricanja odgovornosti na temelju zemlje.
• Baza znanja: Organizirajte članke s poljima za naslov, temu, autora i sadržaj. Omogućite korisnicima da jednostavno pretražuju i pregledavaju članke na temelju teme.

Zaključak