Skip to content
Sign inJoin waitlist

Using a headless CMS — Balancee Astro

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

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: getServices / getService, getPortfolio / getPortfolioItem, getPosts / getPost / getRelatedPosts, getLegalPages / getLegalPage. 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
services 8 slug, name, summary, image (src, alt), intro, whatWeDo (title, text, image), offered (title, items: title and text, six), process (title, text, image, steps: title and text, four)
portfolio 8 slug, name, headline, summary, image, client, budget, duration, team (text), overview, challenges, solutions (each title, body rich text, images), results (the same plus stats: value and label, three)
posts 9 slug, title, excerpt, image, category (text), date, author (name, role, avatar), body (rich text)
legal 2 slug, title, updated (a date), body (rich text)

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

  • Order. Lists keep the order they arrive in, not by date: return entries in the CMS’s order with their position (src/lib/content.ts sorts by it), and give the CMS a sort field. The demo’s posts are newest first, and the CMS order should keep them so: Home shows the first three, the Blog lists them in that order (four at a time as the visitor scrolls). Home shows the first six services (services.count in src/content/pages/home.json); the footer lists the first five case studies and the first four services (caseStudyCount and serviceCount in site.json).
  • Home’s case studies. caseStudies in home.json names case studies by slug (cards, spotlight, recent). Keep those slugs in the CMS, or change the lists.
  • Related posts. A post ends with up to two other posts (otherCount in src/content/pages/blog.json) whose category is exactly the same, in list order (getRelatedPosts). The category is plain text, not a reference: in the CMS a fixed list of choices (Marketing, Business, Innovation in the demo) keeps the spelling consistent. A case study and a service end with the first others of the list (otherCount in portfolio.json and service.json).
  • Services in the form. The contact form’s “I’m interested in …” choices are written in shared.json (contactForm.fields.service.options), not read from the collection: keep the list in step with the services.
  • Ids. Keep each entry’s id equal to its slug, as src/content.config.ts does: getService(slug), getPortfolioItem(slug), getPost(slug) and getLegalPage(slug) look entries up by it.
  • Dates. A post’s date and a legal page’s updated are ISO dates ("2024-02-21"), shown as “Feb 21, 2024”.
  • Case study sections. A section with no photos (images empty) shows none; overview expects one wide photo and up to three small ones, challenges two, solutions and results one.
  • The team, the timeline, the awards, the testimonials, “How we work” and the contact form are not collections: they are page copy in src/content/pages/ (about.json, home.json, shared.json). Keep them there or add collections of your own.
  • The sitemap reads the same functions, so new services, case studies, posts and legal pages are listed once the site rebuilds.

A post’s, a legal page’s and a case study section’s body is a list of blocks, not HTML:

{ type: "heading", level: 3, text: "…" }
{ type: "paragraph", text: "…" } // **bold** between double asterisks, *italic* between single ones, "\n" for a line break
{ type: "list", ordered: false, items: [[{ type: "paragraph", text: "…" }], …] } // each item is a list of blocks

Headings are drawn as <h2> in Heading 3, whatever their level; lists can be numbered (ordered: true) and nested. There are no links or images inside the text. Convert your CMS’s rich text to these blocks in your mapping, bold as **…** and italics as *…* (how). A post’s search description uses its first paragraph when the excerpt is short.

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 card at 360 : 236, the cover at 2.4 : 1, the post’s share image) 2000 wide (the demo’s are 2000 × 1333 and taller)
A service’s image (a square card, a 4 : 5 photo on its page) 1034 × 550 to 690
A service’s whatWeDo.image (545 : 400) and process.image 1090 × 727, 934 × 668
A case study’s image (the card, the 12 : 5 cover, the share image) 2400 × 1600
A case study’s overview.images 1900 × 1267 (wide), then three at 620 × 413
challenges.images (two), solutions.images, results.images (3 : 2) 940 × 627, 1900 × 1267
A post’s author.avatar 120 × 120

A CMS gives full image URLs: the image component (FillImage in src/design-system/components/media/) takes 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 team photos and the testimonials’ portraits are page copy (about.json, home.json), not collections.