Sadržaj svoje web stranice možete mijenjati bez mijenjanja React komponenti. Datoteke pišete u običnom tekstu. Sustav se brine o strukturi, renderiranju i SEO-u. Ova metoda čini sadržaj brzim, dosljednim i jednostavnim za rast.
Ovaj članak govori o tome kako koristimo Markdown za izradu statičnih stranica i blog postova na našim projektima. Proces ima strogu strukturu koja održava sadržaj jednakim kroz jezike i postavke.
Zašto koristiti Markdown?
Uz Markdown, imate potpunu kontrolu nad svojim sadržajem uz vrlo malo sintakse. Koncentrirate se na pisanje. Sustav se brine o parsiranju, generiranju HTML-a i metapodacima.
Važne prednosti za vas:
- Mijenjate sadržaj bez korištenja frontend koda.
- Koristite Git za verziranje sadržaja.
- Podržavate više od jednog jezika i imate jasnu strukturu datoteka.
- Održavate brzu izradu obradom na strani poslužitelja.
Tijekom vremena izrade (build time) ili renderiranja na poslužitelju (server rendering), poslužitelj obrađuje sve markdown datoteke.
Pregled sustava
Za rad pipelinea za markdown potreban je mali broj biblioteka.
| Biblioteka | Funkcija |
|---|---|
| Graymatter | Čita metapodatke iz blog postova. |
| Remark | Obrađuje sintaksu za markdown. |
| Remark-gfm | Dodaje precrtavanje, tablice i popise zadataka. |
| remark-rehype | Pretvara markdown u HTML. |
| rehype-raw | Omogućuje korištenje ugrađenog HTML-a (inline HTML). |
| rehype-stringify | Generira konačni HTML. |
Pišete u Markdownu. Sustav vraća čist HTML.
Struktura direktorija
Sve datoteke se nalaze u src/files.
Statične stranice su u sljedećim mapama:
src/files/static/ensrc/files/static/hr
Blog postovi: src/files/blog/en i src/files/blog/hr
Postoji mapa za svaki jezik. Postoji verzija svake stranice ili posta na oba jezika. Za imena datoteka koristi se kebab case. Zajednički slugovi su ono o čemu ovisi prebacivanje jezika.
Ovaj izgled održava usmjeravanje (routing), SEO i prijevode sinkroniziranima.
Statične stranice
Statične stranice sadrže pravne dokumente, politike i druge opće informacije. U tim datotekama postoji samo markdown. Nema bloka metapodataka na vrhu.
Cijela datoteka se pretvara u HTML.
Koristite naslove, popise, tablice, blokove koda, poveznice, slike i ugrađeni HTML. GitHub-stil Markdown je i dalje u potpunosti podržan.
Izrada statične stranice
Prvi korak. Izradite datoteke koje su iste za svaki jezik. Primjer:
src/files/static/en/terms-of-service.mdsrc/files/static/hr/terms-of-service.md
Imena datoteka moraju biti ista na svim jezicima.
Drugi korak. U App Routeru dodajte rutu za stranicu.
Koristeći lokalitet, tip i ime datoteke, ruta dobiva sadržaj kroz getPage. Stranica daje 404 pogrešku ako datoteka ne postoji.
import { getPage } from '@/lib/page';
const TermsOfService = async ({ params }: PageProps) => {
const { locale } = await params;
const content = await getPage(locale, 'static', 'terms-of-service');
if (!content) {
notFound();
}
return (
<Layout>
<StaticPage content={content} />
</Layout>
);
};
Treći korak. Dodajte metapodatke za SEO. Naslov i opis postavljate u datotekama za prijevod. Postoji drugačija verzija za svaki jezik.
Četvrti korak: Dodajte putanje koje su specifične za vašu lokaciju. Postavljate konfiguraciju usmjeravanja za mapiranje engleskih i hrvatskih URL-ova. Ovaj korak čini stvari jasnijima za korisnike i pomaže kod SEO-a.
Stranica se automatski pojavljuje na oba jezika nakon postavljanja.
Blog postovi
YAML frontmatter dodaje se markdownu u blog postovima. Ovaj blok postavlja metapodatke za SEO, usmjeravanje i stranice s popisima.
Svaki blog post ima:
- Slug
- Naslov
- Putanja do naslovne slike
- Datum objave
- Kategorija
- Oznaka za istaknuto (Featured Flag)
- Ime autora
- Izborni avatar za autora
Sustav izračunava procijenjeno vrijeme čitanja na temelju duljine sadržaja.
Pravila za Frontmatter
Front matter se nalazi na vrhu datoteke.
Tri crtice (---) označavaju početak i kraj.
Polja moraju biti upisana točno.
Neispravne kategorije ili polja koja nedostaju uzrokuju neuspjeh izrade (builds to fail).
Postoje samo četiri kategorije: frontend, backend, design i business.
Slug je isti za obje jezične verzije istog posta.
---
title: Naslov mog blog posta
slug: my-blog-post-title
image: /images/blog/my-post-cover.webp
date: 2025-01-15
category: category-name
featured: false
author:
name: Ivan Horvat
avatar: /images/avatars/ivan.webp
---
Izrada blog posta
Prvi korak. Napravite naslovnu fotografiju.
Fotografija treba imati rezoluciju od 1200 puta 630 piksela.
Gdje: public/images/blog.
Imenujte datoteku.
Drugi korak: Napravite markdown datoteke za svaki jezik.
Lokacija: src/files/blog/en / src/files/blog/hr
Slug bi trebao odgovarati imenu datoteke.
Treći korak. Napišite tekst. Koristite naslove za organiziranje posta. Popisi, tablice i blokovi koda mogu biti od pomoći. Provjerite jesu li vaši odlomci sažeti i fokusirani.
Četvrti korak. Uključite avatare za autore koji nisu obavezni.
Stavite slike u public/images/avatars.
U front matteru pokažite na putanju.
Peti korak: Provedite test.
- Uključite razvojni poslužitelj (dev server).
- Pogledajte popis blogova.
- Idite na stranicu posta.
- Provjerite oba jezika.
- Provjerite slike i vrijeme koje je potrebno za čitanje.
Stranice s često postavljanim pitanjima (FAQ)
Postoji strogi markdown obrazac za FAQ stranice.
- Naslovi s jednom hash oznakom (
#) pokazuju što su grupe. - Pitanja su definirana naslovima s dvostrukom hash oznakom (
##). - Odgovor je sve ispod pitanja do sljedećeg naslova.
Sustav automatski raščlanjuje grupe i pitanja. Odgovori se mogu u potpunosti formatirati s markdownom.
Ova struktura pruža dijelove harmonike (accordion parts) s potrebnim sadržajem bez potrebe za bilo kakvim dodatnim postavljanjem.
API za sadržaj
Sav pristup markdownu ide kroz pomoćne funkcije.
| Funkcija | Vraća |
|---|---|
getPage | HTML za statičnu stranicu. |
getBlogPosts | Popis metapodataka postova. |
getBlogPost | Cijeli post sa svim sadržajem. |
// Dohvati HTML za statičnu stranicu
const content = await getPage('en', 'static', 'privacy-policy');
// Dohvati sve blog postove
const posts = getBlogPosts('en');
// Dohvati pojedinačni blog post po slugu
const post = await getBlogPost('en', 'my-blog-post-slug');
Nikada ne biste trebali dirati logiku sustava datoteka u komponentama.
Kontrolni popis za sadržaj
Za statične stranice:
- Postoje oba jezika.
- Postoje načini da se dođe do njih (rute).
- Postoje metapodaci.
- Putanja su korisne.
- Stranice se prikazuju.
Za blog postove:
- Postoji naslovna slika.
- Ispunjen je front matter.
- Slug se podudara na oba jezika.
- Kategorija je važeća.
- Post se prikazuje na popisu.
- Stranica posta se učitava u redu.
Česti problemi
- Ako postovi nedostaju na blogu, obično je to zato što su u pogrešnoj mapi ili imaju nevažeći front matter.
- Ako vidite pogreške slugova, to znači da postoje problemi s YAML sintaksom.
- Često netočne putanje ili imena datoteka dovode do problema sa slikama.
- Nakon izmjena, lokalizirane rute moraju se ponovno pokrenuti na poslužitelju.
Ukratko
Ovaj markdown sustav olakšava rad s kodom i sadržajem. Sadržaj pišete samo jednom. Sustav se brine o arhitekturi, renderiranju i lokalizaciji. Stvari objavljujete brže. Sadržaj ostaje isti. Skaliranje sadržaja je i dalje lako.
