Using a headless CMS — Semono Astro
Connecting a headless CMS works the same for every Astro template sold on Framebrick, so this page lists only what is specific to Semono.
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 / getOtherServices, getPosts / getPost /
getRelatedPosts, getCareers / getCareer, getLegalPages / getLegalPage, getTestimonials, getTeam and
getClients. 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 |
6 | slug, name, summary, image, highlight, overview (paragraphs), included (points), gallery (three images), deliver (four items: title, description), impact (four items: value, label) |
testimonials |
7 | slug, company, logo, quote, name, role, photo, summary, services (names), results (four items: value, label) |
posts |
12 | slug, title, excerpt, image, category, date, body (rich text) |
careers |
5 | slug, title, summary, location, type, overview, responsibilities (points), qualifications (points), offers (points) |
legal |
2 | slug, title, updated, body (rich text) |
team |
6 | slug, name, role, photo, linkedin |
clients |
10 | name, logo |
- Relations. No collection refers to another by key; the links are by position and by value:
- the testimonials are read by position: the first is the client story in “Why Choose” on Home, the third the quote on About, the fourth the quote beside the closing line of “Our Services” on Home, and the first eight are the grid of cards on Home and Services (each card’s look follows its position); the Testimonial page lists them all. Keep the order in the CMS, and at least one testimonial: Home and About can’t be built without;
- a testimonial’s
servicesare names, not references. The Contact form’s “Service Required” choices are typed insrc/content/pages/contact.json, not read from the services; - related posts share a category:
getRelatedPostsreturns up to three other posts with the samecategory, in list order, and the section is left out when there are none. The demo uses Operational, Leadership and Business, so a choice field in the CMS works; getOtherServicesreturns the first four other services, in list order.
- 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. Home shows the first four services (services.limitinsrc/content/pages/home.json), up to eight testimonials, every client and the first three posts; About the first three team members; the Services page numbers its rows 01, 02, … by position. The Services, Testimonial and Blog pages load four items at a time (six on desktop for the Blog). - Ids. Keep each entry’s
idequal to itsslug(a client’s to itsname), assrc/content.config.tsdoes:getService(slug),getPost(slug),getCareer(slug)andgetLegalPage(slug)look entries up by it. - Counts. A service needs three
galleryimages, fourdeliveritems and fourimpactitems; a testimonial fourresults(Editing the content). - Dates. A post’s
dateand a legal page’supdatedare ISO dates ("2026-05-20"). getOtherServicesandgetRelatedPostsfilter the full list, so they keep working when the loaders fetch from the CMS. The footer’s Services column and the sitemap read the same functions.- The footer’s legal links (
footer.legalLinksinsrc/content/site.json) are typed, not read from the legal pages.
Rich text
Section titled “Rich text”Post bodies and legal texts are blocks, not HTML:
{ type: "heading", text: "…" } // one heading size{ type: "paragraph", text: "…" } // *italic* between asterisks, "\n" for a line break{ type: "list", ordered?: true, items: [[ …blocks ], [ …blocks ]] } // each item is a list of blocksThere is no bold and there are no links inside the text. The demo’s posts use headings, paragraphs and bulleted lists;
the legal texts add one list to headings and paragraphs. Convert your CMS’s rich text to these blocks in your mapping,
italics as *…* (how).
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:
| Image | Size |
|---|---|
A service’s image (the wide photo, the row’s photo and the share image) |
1800 × 1013 |
A service’s gallery |
600 px wide: 600 × 900 for the tall one, shorter for the others |
A post’s image (the card and the wide cover) |
1800 px wide, landscape |
A team member’s photo |
800 × 1200 (2 : 3, cropped from the top) |
A testimonial’s photo |
160 × 160 (shown round, 42 px) |
| Client and company logos | SVG, shown 24 px tall (20 on phones) in the ticker and about 15 px tall on the cards |
A CMS gives full image URLs: the image components (FillImage and SizedImage in
src/design-system/components/media/) and the share images 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).
For logos in src/assets/images/, src/lib/image-size.ts reads their size when the site builds; a logo from another
address gets a default box (100 × 24 for a client, 90 × 15 for a company logo, 78 × 15 in the “Why Choose” story; see src/lib/to-ui.ts). Every CMS
stores an image’s width and height: return them from your mapping and let imageSize() answer with them for CMS
addresses, so the logos keep their own proportions.