Skip to content
Sign inJoin waitlist

Using a headless CMS — Denzel Astro

Connecting a headless CMS works the same for every Astro template sold on Framebrick, so this page lists only what is specific to Denzel.

Loaders and schemas, rich text, images, rebuilding on publish, and step-by-step guides for Sanity, Payload, Strapi and Directus are in Use a headless CMS with an Astro template.

src/content.config.ts defines them, src/content/schemas.ts checks every entry when the site builds, and pages read them through src/lib/content.ts: getPosts / getPost / getPostsBySlug / getPostsByCategory / getPostsByAuthor / getRelatedPosts / getMoreByAuthor, getCategories / getCategory, getAuthors / getAuthor. To fetch a collection from a CMS, replace its loader and keep its schema, or rewrite those functions; pages, sections and components stay unchanged. Mirror the schemas in the CMS:

Collection In the demo Fields
posts 26 slug, title, excerpt, category (a category’s slug), author (an author’s slug), date, image (src, alt), body (rich text)
categories 5 slug, title, description, image (or null)
authors 6 slug, name, bio, avatar (or null), social (facebook, twitter, instagram: a URL or null each)

An image is an object with a src (a path or URL) and an alt.

  • References. A post’s category and author are slugs, not nested objects: a reference field in the CMS, mapped to the referenced entry’s slug. A slug that matches nothing shows the slug as the label and links to a page that doesn’t exist.
  • Order. Posts are sorted by date, newest first, wherever they are listed (getPosts): the Blog, Home’s “Latest” (the first latest.count, 8, in src/content/pages/home.json), the category and author pages, Related Posts and More Articles by (three each, post.related.count and post.more.count in blog.json). Categories and authors keep the order they arrive in, by their position (src/lib/content.ts sorts by it).
  • Home’s picks. The slider, Editor’s Pick and Trending (slider, picks, trending in home.json), the sidebar’s Recent (sidebar.recent.posts in site.json), the footer’s two posts (footer.posts.slugs) and the Explore Topics categories (sidebar.topics.categories) are lists of slugs in the page copy. Keep those slugs in the CMS, or change the lists, or replace them with a query (a “featured” flag, say) in src/pages/index.astro, src/lib/sidebar.ts and src/components/site/Footer.astro. A slug in picks or trending that matches no post stops the build.
  • The default entries. “Uncategory” and “Admin” have no photo (image and avatar are null) and no posts in the demo; every category and author gets a page, with or without posts.
  • Ids. Keep each entry’s id equal to its slug, as src/content.config.ts does: getPost(slug), getCategory(slug) and getAuthor(slug) look entries up by it.
  • Dates. A post’s date is an ISO date ("2023-09-14"), shown as “Sep 14, 2023”.
  • Search. The header’s search is built from the same three collections when the site builds (toSearchItems() in src/lib/to-ui.ts), so new entries are searchable once the site rebuilds.
  • The sitemap reads the same functions, so new posts, categories and authors are listed once the site rebuilds.

A post’s body is a list of blocks, not HTML:

{ type: "heading", level: 3, text: "…" } // level 2 to 6; 2–3 are set as H3, 4–6 as H4
{ type: "paragraph", text: "…" } // **bold** between double asterisks
{ type: "list", ordered: false, items: ["…", { text: "…", ordered: true, items: ["…", "…"] }] }

A list item is a string, or an item with a nested list under it (one level deep). There are no italics, line breaks, links or images inside the text. Convert your CMS’s rich text to these blocks in your mapping, bold as **…** (how). A post’s search description is its title followed by its first paragraph.

Every photo sits in a frame and is cropped to fill it, so a photo of other proportions works; upload images at least as large as the layout uses, and store an alt text for each:

Image Size
A post’s image (the cover at 734 : 406, the cards from 477 : 430 to an 80 px square, the post’s share image) 1600 wide (the demo’s are 1600 × 1067, some taller)
A category’s image (336 : 234 on its page, a 52 px circle in Explore Topics) 800 × 533
An author’s avatar (circles of 100, 42 and 32 px) 120 × 120

A CMS gives full image URLs: the image components (FillImage and SizedImage in src/design-system/components/media/) take either a /images/<file> path or a URL (isRemote() and imageUrl() in src/design-system/utils/image.ts). Allow the CMS’s image host in astro.config.mjs (image.domains) so Astro resizes its photos too (Images). The logo, the sidebar’s background and the 404 illustration are page copy (site.json, not-found.json), not collections.