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.
Collections
Section titled “Collections”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.tssorts 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.countinsrc/content/pages/home.json); the footer lists the first five case studies and the first four services (caseStudyCountandserviceCountinsite.json). - Home’s case studies.
caseStudiesinhome.jsonnames case studies byslug(cards,spotlight,recent). Keep those slugs in the CMS, or change the lists. - Related posts. A post ends with up to two other posts (
otherCountinsrc/content/pages/blog.json) whosecategoryis 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 (otherCountinportfolio.jsonandservice.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
idequal to itsslug, assrc/content.config.tsdoes:getService(slug),getPortfolioItem(slug),getPost(slug)andgetLegalPage(slug)look entries up by it. - Dates. A post’s
dateand a legal page’supdatedare ISO dates ("2024-02-21"), shown as “Feb 21, 2024”. - Case study sections. A section with no photos (
imagesempty) shows none;overviewexpects one wide photo and up to three small ones,challengestwo,solutionsandresultsone. - 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.
Rich text
Section titled “Rich text”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 blocksHeadings 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.
Images
Section titled “Images”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.