Astro sisukogud: Tõstke oma veebisaiti tüübikindla sisuhaldussüsteemiga

Astro, populaarne staatilise saidi generaator, pakub võimsat funktsiooni nimega Sisukogud. See süsteem pakub struktureeritud ja tüübikindlat viisi oma veebisaidi sisu haldamiseks, tagades järjepidevuse, vähendades vigu ja parandades üldist arenduskogemust. Ükskõik, kas ehitate isiklikku blogi, dokumentatsioonisaidi või keerukat e-kaubanduse platvormi, saavad sisukogud teie töövoogu oluliselt sujuvamaks muuta.

Mis on Astro sisukogud?

Sisukogud on teie Astro projekti spetsiaalne kataloog, kus saate korraldada oma sisufaile (tavaliselt Markdown või MDX). Iga kogu on määratletud skeemiga, mis määrab teie sisu frontmatter'i (iga faili alguses olevad metaandmed) eeldatava struktuuri ja andmetüübid. See skeem tagab, et kogu kogu sisu vastab ühtsele vormingule, vältides vastuolusid ja vigu, mis võivad tekkida käsitsi andmesisestuse tõttu.

Mõelge sellele kui andmebaasile, kuid teie sisufailide jaoks. Sisu ei salvestata andmebaasiserverisse, vaid lihttekstifailidesse, mis pakuvad versioonikontrolli eeliseid ja võimaldavad teil sisu koodile lähedal hoida. Kuid erinevalt lihtsalt Markdown-failide kaustast tagavad sisukogud struktuuri ja tüübikindluse skeemi kaudu.

Miks kasutada sisukogusid?

• Tüübikindlus: TypeScripti integreerimine tagab, et teie sisu andmed on arenduse ajal tüübikontrollitud, tuvastades vead varakult ja vältides käitusajal tekkivaid probleeme. See on eriti kasulik suuremates projektides, kus on mitu kaastöölist.
• Skeemi valideerimine: Määratletud skeem valideerib iga sisufaili frontmatter'i, tagades, et kõik nõutavad väljad on olemas ja õiget tüüpi.
• Parem sisu järjepidevus: Järjepideva struktuuri jõustamisega aitavad sisukogud säilitada kogu teie veebisaidi ühtlast välimust ja tunnetust.
• Täiustatud arendaja kogemus: Tüübikindel API pakub teie IDE-s suurepärast automaatset lõpetamist ja veatuvastust, muutes sisuhalduse lihtsamaks ja tõhusamaks.
• Lihtsustatud andmetele juurdepääs: Astro pakub mugavat API-t oma kogudest sisu päringute esitamiseks ja sellele juurdepääsuks, lihtsustades andmete otsimist teie komponentides.
• Sisu korraldus: Kogud pakuvad selget ja loogilist struktuuri teie sisu korraldamiseks, muutes selle leidmise ja haldamise lihtsamaks. Näiteks võib dokumentatsioonisaidil olla kogud "juhendid", "api-viide" ja "muudatuste logi".

Sisukogudega alustamine

Siin on samm-sammult juhend sisukogude juurutamiseks oma Astro projektis:

1. Lubage sisukogud

Esmalt lubage integratsioon @astrojs/content failis astro.config.mjs (või 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. Looge sisukogu kataloog

Looge kataloog nimega src/content/[collection-name], kus [collection-name] on teie kogu nimi (nt src/content/blog). Astro tunneb selle kataloogi automaatselt sisukoguna ära.

Näiteks 'blogi' kogu loomiseks peaks teie projekti struktuur välja nägema selline:

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

3. Määratlege kogu skeem

Looge fail src/content/config.ts (või src/content/config.js), et määratleda oma kogu skeem. See fail ekspordib objekti config, mis määrab iga kogu skeemi.

Siin on näide 'blogi' kogu skeemist:

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

Selgitus:

• defineCollection: seda funktsiooni kasutatakse sisukogu määratlemiseks.
• schema: see atribuut määratleb kogu frontmatter'i skeemi.
• z.object: see määratleb skeemi JavaScripti objektina. Me kasutame Zodit skeemi valideerimiseks, mis on populaarne TypeScript-first skeemideklaratsiooni ja valideerimisteek.
• z.string(), z.date(), z.array(): need on Zodi skeemitüübid, mis määratlevad iga välja jaoks eeldatavad andmetüübid.
• z.optional(): muudab välja valikuliseks.
• transform: kasutatakse frontmatter'i andmete teisendamiseks. Sel juhul tagame, et pubDate ja updatedDate on Date objektid.

4. Looge sisufaile

Looge oma kogu kataloogis Markdown- või MDX-faile (nt src/content/blog/my-first-post.md). Iga fail peaks sisaldama frontmatter'i, mis vastab teie määratletud skeemile.

Siin on näide Markdown-failist koos frontmatter'iga:

            ---
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. Juurdepääs sisule oma komponentides

Kasutage funktsiooni getCollection() kataloogist astro:content, et tuua sisu oma kogudest oma Astro komponentides. See funktsioon tagastab massiivi kirjetest, millest igaüks esindab sisufaili.

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

Selgitus:

• getCollection('blog'): hangib kõik kirjed kogust 'blogi'.
• post.slug: 'slug' on iga sisufaili jaoks unikaalne identifikaator, mis genereeritakse automaatselt failinimest (nt 'my-first-post' faili 'my-first-post.md' jaoks).
• post.data: sisaldab iga kirje frontmatter'i andmeid, mis on tüübikontrollitud vastavalt skeemile.

Täiustatud funktsioonid ja kohandamine

Sisukogud pakuvad mitmeid täiustatud funktsioone ja kohandamisvalikuid, et kohandada süsteemi vastavalt teie konkreetsetele vajadustele:

1. MDX tugi

Sisukogud integreeruvad sujuvalt MDX-iga, võimaldades teil manustada JSX-komponente otse oma Markdowni sisusse. See on kasulik interaktiivse ja dünaamilise sisu loomiseks.

MDX-i kasutamiseks installige integratsioon @astrojs/mdx ja konfigureerige see oma failis astro.config.mjs (nagu näidatud 1. etapis). Seejärel looge MDX-faile (nt my-post.mdx) ja kasutage oma sisus JSX-i süntaksit.

            ---
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. Kohandatud skeemitüübid

Zod pakub laias valikus sisseehitatud skeemitüüpe, sealhulgas string, number, boolean, date, array ja object. Samuti saate määratleda kohandatud skeemitüüpe, kasutades Zodi meetodit .refine(), et jõustada spetsiifilisemaid valideerimisreegleid.

Näiteks võite valideerida, kas string on kehtiv 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. Kohandatud slug'i genereerimine

Vaikimisi genereerib Astro iga sisufaili slug'i failinimest. Saate seda käitumist kohandada, lisades frontmatter'isse atribuudi slug või kasutades atribuuti entry.id, et luua kohandatud slug faili tee põhjal.

Näiteks faili tee kasutamiseks slug'i genereerimiseks:

            // 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. Sisu filtreerimine ja sortimine

Saate kasutada JavaScripti massiivi meetodeid (filter, sort jne), et veelgi täpsustada oma kogudest hangitud sisu. Näiteks võite filtreerida postitusi nende siltide põhjal või sortida neid avaldamiskuupäeva järgi.

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

Kuigi sisukogud ei paku otseselt i18n-funktsioone, saate rahvusvahelistumise juurutada, luues iga keele jaoks eraldi sisukogud või kasutades frontmatter'i välja, et näidata iga sisufaili keelt.

Näide eraldi kogude kasutamisest:

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

Seejärel oleks teil kaks kogu määratlust: blog-en ja blog-es, millest kummalgi on oma sisu.

Näide välja lang kasutamisest frontmatter'is:

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

# My First Blog Post

            

              
                Copy
              
            
          

Seejärel filtreeriksite kogu välja lang põhjal, et tuua iga keele jaoks õige sisu.

Sisukogude kasutamise parimad tavad

• Planeerige oma skeem hoolikalt: mõelge oma sisu struktuurile ja andmetüüpidele enne skeemi määratlemist. Hästi kujundatud skeem muudab teie sisuhalduse pikemas perspektiivis lihtsamaks ja tõhusamaks.
• Kasutage kirjeldavaid väljanimesid: valige väljanimed, mis on selged ja enesestmõistetavad. See parandab koodi loetavust ja hooldatavust.
• Esitage iga välja jaoks selged kirjeldused: kasutage Zodi skeemis atribuuti description, et anda iga välja jaoks kasulikke kirjeldusi. See aitab teistel arendajatel (ja teie tulevasel minal) mõista iga välja eesmärki.
• Jõustage nõutavad väljad: kasutage Zodi meetodit required(), et tagada, et kõik nõutavad väljad on frontmatter'is olemas.
• Kasutage valikulisi välju säästlikult: kasutage valikulisi välju ainult siis, kui need on tõesti valikulised. Nõutavate väljade jõustamine aitab säilitada järjepidevust ja vältida vigu.
• Dokumenteerige oma kogud: looge oma sisukogude jaoks dokumentatsioon, milles selgitatakse iga kogu eesmärki, skeemi struktuuri ja kõiki konkreetseid valideerimisreegleid.
• Hoidke oma sisu korrastatuna: kasutage oma sisufailide jaoks järjepidevat nimetamiskonventsiooni ja korraldage need oma kogudes loogilistesse kataloogidesse.
• Testige oma kogusid põhjalikult: kirjutage teste, et tagada oma sisukogude korrektne toimimine ja skeem valideerib frontmatter'i ootuspäraselt.
• Kaaluge CMS-i kasutamist sisuloojate jaoks: sisurikka veebisaidi puhul kaaluge Astro sidumist peatu CMS-iga. See pakub kasutajasõbralikku liidest sisuloojatele, kes ei pea koodiga suhtlema. Näited hõlmavad Contentfuli, Strapi ja Sanity.

Näited kasutusjuhtumite kohta: isiklikest blogidest ülemaailmse e-kaubanduseni

• Isiklik blogi: hallake blogipostitusi väljadega pealkiri, avaldamiskuupäev, autor, sisu ja sildid. See võimaldab hõlpsat sisu värskendamist, blogirulli genereerimist ja kategooriate loendit.
• Dokumentatsioonisaidid: struktureerige dokumentatsioonilehti väljadega pealkiri, versioon, kategooria ja sisu. Võimaldab järjepidevat dokumentatsiooni struktuuri ja lihtsat navigeerimist erinevate versioonide vahel. Mõelge suurele avatud lähtekoodiga projektile nagu Kubernetes, kus dokumentatsioon on kriitilise tähtsusega.
• Turundusveebisait: määratlege lehed väljadega pealkiri, kirjeldus, märksõnad ja sisu. Optimeerige sisu SEO jaoks ja säilitage kaubamärgi järjepidevus kõigil lehtedel.
• E-kaubanduse platvorm: kataloogige tooted väljadega nimi, hind, kirjeldus, pildid ja kategooriad. Rakendage dünaamiline toodete loend ja hõlbustage lihtsaid toodete värskendusi. Ülemaailmse e-kaubanduse näite puhul kaaluge erinevate kogude olemasolu piirkonniti, et kohandada kohalike turgude ja õiguslike nõuetega. See võimaldaks erinevaid välju, nagu maksuteave või regulatiivsed lahtiütlused, sõltuvalt riigist.
• Teadmiste baas: korraldage artikleid väljadega pealkiri, teema, autor ja sisu. Lubage kasutajatel hõlpsalt otsida ja sirvida artikleid teema põhjal.

Järeldus