Skip to content
Sign inJoin waitlist

Using a headless CMS — Brickfolio Astro

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

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 (each loads a JSON file of src/content/collections/), src/content/schemas.ts checks every entry when the site builds, and pages read them through src/lib/content.ts: getProjects / getProject / getMoreProjects, getServices and getPosts / getPost / getMorePosts. 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
projects (projects.json) 6 slug, title, service (text), date, client, summary, cover, description (rich text), highlights (rich text), gallery (three images, each with visible)
services (services.json) 4 slug, title, description, price (text, “$3,000”), href (“More Details”), images (four images, each with visible)
posts (posts.json) 12 slug, title, category (text), date, image, body (rich text)

An image is an object, { src, alt } (with visible: true | false in a gallery or a service): the path or address and its description. Dates are ISO dates ("2024-07-08"); a project shows only its month and year.

  • No references. A project’s service and a post’s category are plain text, not links to other collections. “More Posts” matches the category text exactly, so keep one spelling per category (a select field in the CMS).
  • Order. Projects and services keep the order they arrive in, by their position (the JSON loader numbers the items of the file; src/lib/content.ts sorts by it): give them an order field in the CMS and map it to position. getPosts() sorts the posts by date, newest first, whatever order the CMS returns. Home shows four projects and four posts, then four more per click (pageSize in src/content/pages/home.json); “More Projects” lists the first three other projects, “More Posts” the three newest other posts of the category (count in project.json and post.json).
  • Services have no page. They appear on Home only, so slug is just an identifier. Testimonials, experience, client logos and the questions are lists in src/content/pages/home.json, not collections: move them to the CMS as a settings document if editors should change them.
  • Gallery images. A project has exactly three: the first two side by side, the third full width; visible: false hides one. A service has four, shown in two moving columns. Model them as fixed fields (as the original design does) or as a list of up to three or four.
  • Every project and post has a page. /project/<slug> and /blog/<slug> are built from the collections, and the sitemap reads the same functions.

A project’s description and highlights and a post’s body are blocks, not HTML:

{ type: "paragraph", text: "…" } // **bold** and `code` inline
{ type: "heading", level: 3, text: "…" } // levels 2–6 share one style
{ type: "list", ordered: false, items: ["…", "…"] } // an item is a string …
{ type: "list", ordered: true, items: [{ text: "…", ordered: false, items: ["…"] }] } // … a string with a nested list …
{ type: "list", ordered: true, items: [{ text: "…", blocks: [/* paragraphs and lists */] }] } // … or a string followed by blocks

The demo uses paragraphs, headings of level 3, bulleted and numbered lists, items that hold more paragraphs and lists, bold and inline code (three posts). There are no italics, links or images inside the text. Convert your CMS’s rich text to these blocks in your mapping function, bold as **…** and code as `…` (how).

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:

Image Size
A project’s cover (3 : 2 on its page, up to 1000 px wide; 380 px tall on the cards) 1600 × 1066 or larger
A project’s gallery (3 : 2; the first two half the column, the third the full 1000 px) 1000 wide (first two), 1600 wide (third)
A post’s image (3 : 2 on its page; 250 px tall on the cards) 1600 wide
A service’s images (100 × 150 tiles) 300 wide (200 to 375 tall)

A full URL in src works as it is (isRemote in src/design-system/utils/image.ts); allow the CMS’s domain in image.domains of astro.config.mjs so Astro resizes it like the local files (Images). Every photo fills a frame of its own shape, so the layout needs no width and height from the CMS.