Editing the content — Balancee Astro
All the words of this Astro template live in src/content/ and its photos in src/assets/images/: plain JSON files you edit while npm run dev shows them.
No CMS is needed: text goes between quotes and entries are separated by commas. If you would rather manage content in Sanity, Payload, Strapi or Directus, see Using a headless CMS.
src/content/ site.json name, title, description, domain, menu, "Contact us", contact details, socials, footer pages/home.json the copy of the home page pages/about.json …and of every other page pages/shared.json the call-to-action band, "How we work", the consultation prompt, the contact form collections/*.json the services, the case studies, the posts and the legal pages routes.ts the URL of every page schemas.ts the fields each kind of item has, and which are requiredNot sure which file holds a piece of text? The page maps label every section of every page with its file.
Your details first
Section titled “Your details first”src/content/site.json holds what appears on every page:
| Field | Shown where |
|---|---|
site.name |
The browser title suffix (“About us | Balancee”), share cards and the logo’s name for screen readers. It is the template’s name in the demo: put your own (your company’s). |
site.title |
The browser title of the home page |
site.description |
Search results and share cards of any page without its own description. It describes the template: write yours. |
site.url |
Set this to your domain before publishing. Canonical links, share links, sitemap.xml and robots.txt are built from it. |
navigation |
The menu in the header (and the phone menu): Home, About, Services, Portfolio, Blog |
contactLink |
The “Contact us” button in the header (from desktop width) and at the end of the phone menu (/contact in the demo) |
contact |
email, phone, address and hours (a list of lines): the Contact page’s details and the footer’s phone and e-mail |
socials |
The links “Linkedin”, “Instagram”, “Facebook”, “Twitter” of the footer and of the Contact page |
footer |
The footer: the newsletter box (newsletter: title, placeholder, button), the labels “To More Inquiry” and “To Send Mail”, the column titles (quickLinksLabel, caseStudyLabel, socialLabel), quickLinks, how many case studies and services it lists (caseStudyCount: 5, serviceCount: 4), the legal links (legalLinks) and the copyright line (note, where {year} becomes the current year) |
logo, logoWhite |
The logo’s name for screen readers (logo.alt). The wordmark itself is drawn by the code (Making it look like your brand) |
The demo’s e-mail (hello@example.com), phone number and Brooklyn address are placeholders: replace them. The phone’s
link is built from the number (+44 20 7946 0345 calls tel:+442079460345), so write it the way people should read it.
The social links open the networks’ home pages: point them to your own profiles. The footer lists the first five case
studies and the first four services of the collections, in their order.
Some details are written in more than one file, so change each copy:
| Detail | Where |
|---|---|
| Your e-mail | contact.email in site.json (the Contact page and the footer) |
Your booking link (“Let’s talk” and “Book a Free Consultation” open https://cal.com/ in the demo) |
consultation.link.href and ctaBand.secondary.href in shared.json |
| Your social links | socials in site.json; the team members’ own links are href in about.json (team.members), and the awards’ href too |
| The numbers (“$86M+”, “320+”, “4.9”…) | about.facts in home.json, hero.mainFact and hero.facts in about.json, hero.rating in home.json, the results of each case study |
| The company name in the copy | search src/content/ for “Balancee”: it is in the page copy, the legal texts and the case studies |
| The people | the team (team.members in about.json), the three testimonials (testimonials.items in home.json), the post author (each post’s author) |
The footer’s social links open in a new tab; mailto: and tel: links open the visitor’s mail app or phone. Search src/content/ for “example.com”, “Brooklyn” and “Emma Carter” to find the demo’s
details.
Page copy
Section titled “Page copy”There is one file per page in src/content/pages/, and one for the blocks several pages share. A page file holds the
sections of that page and a meta entry:
{ "meta": { "title": "Services", "description": "Business consulting services built to address your challenges and drive growth: strategy, operations, organization and more." }, "hero": { "breadcrumb": "Services", "title": "Empowering Businesses with Tailored Strategies", "text": "At Balancee, we deliver business consulting services designed to address your challenges and drive growth." }}title becomes the browser tab (“Services | Balancee”), and description the text in search results and share cards
(80–160 characters). Change the text between the quotes, keeping the field names: the sections read them by name.
Apostrophes are safe inside the double quotes, and the demo uses the typographic ’ in places. A double quote inside the
text needs a backslash before it (\"). JSON has no comments and no comma after the last entry of a list; if the site
stops building after an edit, that is usually why.
| File | Page or block |
|---|---|
home.json |
Home: the hero (hero: the title, the client rating with its three portraits, the text, two buttons, the caption over the video and the video), the client logos (clients), “Services built for growth” (services: its heading and count, the number of services shown, 6), “About Balancee” (about: three figures, the heading, the button, the photo and the small video), the photo of “How we work” (process; its four steps are in shared.json), “Case Studies” (caseStudies, see below), “What our clients say” (testimonials: three testimonials, one with a video, and the photo with the consultation prompt) and “Insights that drive better business” (blog: the heading, the button and count, the number of posts, 3). meta.description is the description of Home; its browser title is site.title. |
about.json |
About: its meta, the top block with two photos and three figures (hero), “Who We Are” (who: the heading, three cards, four photos), “Our Journey” (journey: the heading, six milestones and the awards) and “Our Team” (team: the heading and six members) |
service.json |
Services and every service page: the Services page’s meta and hero, the “Get in Touch” block with the form (contactSection), and the labels of a service page (detail: “What we offer”, “What we do”, “Services Offered”, “How we work”, the button, “Other services” and otherCount, 3, the number of other services shown) |
portfolio.json |
Portfolio: its meta and hero, list (pageSize: 4, the case studies shown at first and loaded each time, and the text screen readers hear while more load) and the labels of a case study page (detail: “Client”, “Budget”, “Duration”, “Team Size”, “Other case studies”, otherCount: 2) |
blog.json |
Blog: its meta and hero, list (pageSize: 4, loading) and the block under every post (post: “Other blogs”, otherCount: 2 and “See all blog”) |
contact.json |
Contact: its meta, the title and text (hero) and the labels of the details (details: “Email Address”, “Phone”, “Location”, “Hours:”, “Follow us”) |
legal.json |
The legal pages: “Last updated:” (updatedLabel) |
not-found.json |
The 404 page: its browser meta, the code, the title, the text and the button (notFound) |
shared.json |
Blocks of several pages: ctaBand (the dark band with a photo, before the footer of every page except Contact and Services), process (the four steps of “How we work” on Home, Services and every service page, with intro and the “Want to know what’s possible?” pill in action), consultation (the prompt “Let’s talk about your goals…” on the last photo of About’s “Who We Are” and on the photo of Home’s testimonials), contactForm (the contact form, see Forms) and formLegal (the line under its button, with the links to the legal pages) |
Home’s case studies
Section titled “Home’s case studies”caseStudies in home.json picks case studies by their slug: cards (the two photo cards), spotlight (the first row of
“Recent case studies”, open at the start) and recent (the three rows after it). Keep these slugs in step with
portfolio.json: a slug that matches no case study stops the build. The rows’ numbers (“(001)”, “(002)”…) follow their
order.
Testimonials, steps and figures
Section titled “Testimonials, steps and figures”testimonials.items in home.json has three entries, written for three different cards: the first (figures, video,
videoLabel) is the dark card and the video, the second and third (avatar) the two light quote cards. Keep that shape:
the cards read them by position. “How we work” (process.steps in shared.json) is a list of title, promise and
text, numbered 01, 02, … in their order. A figure is a value written as it should read (“+37%”) and a label:
nothing counts up and nothing is computed.
The timeline, the awards and the team
Section titled “The timeline, the awards and the team”On About, journey.milestones is a list of year and title (six in the demo, shown in their order), journey.awards.items
a list of award, by, year and href, and team.members a list of slug, name, role, photo, bio and href
(the LinkedIn button of the card). The team has no collection and no page of its own: add or remove a member by editing
the list; the cards are three across on desktops, two on tablets, one on phones.
Collections
Section titled “Collections”src/content/collections/ holds the lists the site builds pages and sections from:
| File | What it feeds |
|---|---|
services.json |
The Services page (every service), Home’s “Services built for growth” (the first services.count: 6), the page of each service (/service/<slug>), “Other services”, and the footer’s row (the first serviceCount: 4) |
portfolio.json |
The Portfolio page (every case study), Home’s cards and accordion rows (by slug), the page of each case study (/portfolio/<slug>), “Other case studies” and the footer’s column (the first caseStudyCount: 5) |
posts.json |
The Blog (every post, four at a time as the visitor scrolls), one page per post, Home’s “Insights that drive better business” (the first three: blog.count) and “Other blogs” under a post (up to two other posts of its category) |
legal.json |
One page per legal page (/legal/<slug>), linked from the footer (footer.legalLinks in site.json) and from the contact form |
The order of the items in the file is the order on the site. The Blog doesn’t sort posts by date: the demo lists them newest first, so put a new post first to show it first, on Home too. Every post is in the Blog’s HTML from the start, so search engines find them all.
Adding a post
Section titled “Adding a post”Copy an existing entry, paste it where it should appear (mind the comma between entries), and change the values:
{ "slug": "five-questions-before-you-scale", "title": "Five questions to ask before you scale", "excerpt": "Growth multiplies what is already there, good and bad. Five questions that show whether your business is ready for it.", "image": { "src": "/images/post-five-questions-before-you-scale.jpg", "alt": "A whiteboard with a growth plan" }, "category": "Business", "date": "2026-11-03", "author": { "name": "Emma Carter", "role": "Founder & CEO", "avatar": { "src": "/images/team-emma-carter.jpg", "alt": "Emma Carter" } }, "body": [ { "type": "paragraph", "text": "First paragraph.\nA second line in the same paragraph." }, { "type": "heading", "level": 3, "text": "Start with the numbers" }, { "type": "paragraph", "text": "A paragraph with a **bold** phrase." } ]}Here’s what each field does:
slugis the URL:/blog/five-questions-before-you-scale.titleis the card’s title and the post’s title.excerptis shown under the title on the post page and on the cards, and is its search description (followed by the start of the first paragraph when it is under 80 characters).imageis the card’s photo and the cover of the post, and the picture shown when the post is shared;altdescribes it.categoryis shown on the card and next to the date, and decides “Other blogs”: other posts with exactly the samecategory. The demo uses Marketing, Business and Innovation.date("2026-11-03") is shown as “Nov 3, 2026”.authoris the name, role and small portrait above the cover. The demo’s authors are the six team members of the About page (their photos are reused, so no extra file); no author writes more than two posts.bodyis the article (rich text).
Adding a service
Section titled “Adding a service”A service has a card (on Home, Services and under other services) and a page of its own:
{ "slug": "sustainability-advisory", "name": "Sustainability advisory", "summary": "Turning environmental and social goals into a plan the business can fund and run.", "image": { "src": "/images/service-sustainability-advisory.jpg", "alt": "…" }, "intro": "The paragraph under the title of the service's page.", "whatWeDo": { "title": "A greener path that pays for itself", "text": "The text beside the photo.", "image": { "src": "/images/service-sustainability-advisory-what-we-do.jpg", "alt": "…" } }, "offered": { "title": "Practical steps for a lower-impact business", "items": [{ "title": "Footprint audit", "text": "…" }] }, "process": { "title": "A plan you can follow", "text": "…", "image": { "src": "/images/service-sustainability-advisory-process.jpg", "alt": "…" }, "steps": [{ "title": "Measure", "text": "…" }] }}slugis the URL:/service/sustainability-advisory.nameis the card’s and the page’s title;summarythe text on the cards;imagethe card’s photo and the photo on the service page’s top.introis the paragraph under the title of the service page and the start of its search description.offered.itemsare the numbered cards of “Services Offered” (six in the demo); the same titles are the chips under “What we offer” at the top of the page.process.stepsare the four steps of “How we work” on that page.
Also add the service’s name to the choices of the contact form (Forms): the radio list is
written in shared.json, not read from the collection. The Home’s row shows the first six services, Services shows all of
them, the footer the first four.
Adding a case study
Section titled “Adding a case study”{ "slug": "green-logistics", "name": "Green Logistics", "headline": "Cutting delivery costs while halving emissions", "summary": "The paragraph under the headline, also shown on Home's accordion.", "image": { "src": "/images/portfolio-green-logistics-cover.jpg", "alt": "…" }, "client": "Northline Freight", "budget": "$120,000", "duration": "8 months", "team": "6 people", "overview": { "title": "Overview", "body": [{ "type": "paragraph", "text": "…" }], "images": [] }, "challenges": { "title": "Client Challenges", "body": [], "images": [] }, "solutions": { "title": "Solutions", "body": [], "images": [] }, "results": { "title": "Results", "body": [], "images": [], "stats": [{ "value": "-31%", "label": "Cost per delivery" }] }}nameis the chip on the cards and the title of the page;headlineis the big title on the cards and at the top.imageis the cover and the card’s photo.client,budget,durationandteamare the four fact boxes under it.- Each of the four sections has a
title, abody(rich text) andimages: the first photo ofoverviewis wide and the next three sit in a row under it,challengesshows two photos side by side,solutionsandresultsone. A section with no photos shows none (the demo’s “Merge Mastery” has no photos in two sections). results.statsare the three figures; the first one is also shown in the accordion row of Home.
Legal pages
Section titled “Legal pages”legal.json holds Terms of Service and Privacy Policy: a slug (the URL, /legal/terms-of-service), a title, the date
of the last update (updated, an ISO date shown as “Aug 10, 2025”) and a body (rich text). The demo’s
texts are samples with placeholders such as [Your Company Name] and [URL]: have your own texts written for your
business and the law where you work. A legal page’s search description is built from its date and title in
src/pages/legal/[slug].astro. Link a new legal page from footer.legalLinks in site.json (and from formLegal in
shared.json if it should sit under the contact form).
Removing an item
Section titled “Removing an item”Delete the entry (and the comma before it, if it was the last one). The item’s page and its sitemap entry disappear on the
next build. Places that name an item by hand stay as they are: Home’s caseStudies (cards, spotlight, recent) must
not point at a deleted case study, the contact form’s radio list still offers a deleted service, and footer.legalLinks
still links a deleted legal page.
What each field means
Section titled “What each field means”src/content/schemas.ts is the reference: it lists every field and a comment for the ones that are not obvious.
npm run check and npm run build report a missing field (a misspelled name counts as missing) with the collection, the
item and the field.
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:
"body": [ { "type": "paragraph", "text": "A paragraph with a **bold** phrase.\nA new line inside it." }, { "type": "heading", "level": 3, "text": "A heading" }, { "type": "list", "ordered": false, "items": [ [{ "type": "paragraph", "text": "**First point:** its text." }], [{ "type": "paragraph", "text": "Second point." }] ] }]- Paragraphs: words between double asterisks (
**…**) are set in bold, words between single ones (*…*) in italics, and\nstarts a new line. There are no links inside the text. - Headings are set in Heading 3 and are
<h2>elements under the page’s title, whatever theirlevel. - Lists:
"ordered": truenumbers the items (1., 2., …), otherwise each gets a bullet. Each item is itself a list of blocks, so an item can hold several paragraphs or a list of its own.
Images
Section titled “Images”- Put the file in
src/assets/images/. - Refer to it in the content as
/images/<file>, with analt.
Astro resizes, compresses and converts the photos when the site builds, so each device gets a size that fits. The download’s placeholders show the size each photo was designed for; use photos at least as large:
| Photos | Demo size | How it is shown |
|---|---|---|
The Home hero’s poster (home-hero-poster.png) |
1920 × 1080 | The picture under the hero video until the video plays; the video box is 1140 × 500 on desktops, 400 tall on tablets and phones, cropped to fill it |
The poster of Home’s small clip (home-about-video-poster.png) and the testimonial video (home-review-poster.jpg) |
1280 × 720, 1506 × 1004 | The clip box at 350 : 189; the video card (two columns wide on tablets and desktops) |
Home’s tall photos (home-about.jpg, home-process.jpg, home-cta.jpg) |
1040 × 1558, 934 × 1401, 734 × 918 | Beside the text of “About Balancee”, beside the steps of “How we work”, and under the consultation prompt of the testimonials |
The call-to-action band (cta-office.jpg) |
2400 × 1600 | Behind the band, the full width, under a Black 80 % cover |
The Home hero’s three portraits (avatar-1.jpg … avatar-3.jpg), the quote cards’ portraits (client-maya-chen.jpg, client-kareem-alvi.jpg) and a post’s author (the team photos in images/, team-<name>.jpg, shown at 48 × 48) |
120 × 120 | Small circles beside a name |
The client logos (client-logo-1.svg … client-logo-6.svg) |
SVG, shown at 144 × 31 | White 250 × 125 tiles of the ticker |
About’s photos (about-hero-1.jpg, about-hero-2.jpg) |
510 × 287, 934 × 623 | The small photo and the photo under the figure card, in the 2 × 2 grid at the top |
“Who We Are” (about-who-1.jpg … about-who-4.jpg) |
1120 × 1493, 1120 × 747, 346 × 519, 734 × 918 | A tall photo, a wide one, two small ones; the last one carries the consultation prompt |
A team member’s photo (team-*.jpg) |
714 × 893 to 714 × 1071 | A frame at 0.742 : 1 (about 3 : 4), cropped from the centre |
A service’s image (service-*.jpg) |
1034 × 550 to 1034 × 690 | A square on the cards, a 4 : 5 photo (517 wide on desktops) on the top of its page |
A service’s whatWeDo.image (service-*-what-we-do.jpg) |
1090 × 614 to 1090 × 727 | 545 : 400, beside the “What we do” title |
A service’s process.image (service-*-process.jpg) |
934 × 622 to 934 × 668 | The tall photo of “How we work” on its page: it takes the height the title leaves, so it is cropped |
A case study’s image (portfolio-*-cover.jpg) |
2400 × 1427 to 2400 × 1800 | The cover of its page (12 : 5 from tablets up, 300 tall on phones) and the card’s photo |
A case study’s overview.images |
1900 × 1168 and 620 × 413 (three) | One wide photo and three small ones at 3 : 2 |
challenges.images, solutions.images, results.images |
940 × 529 to 940 × 684 (two), 1900 × 1069 to 1900 × 1608 | Two photos side by side at 3 : 2, then one wide photo each at 3 : 2 |
A post’s image (post-*.jpg) |
2000 × 1333 to 2000 × 3200 | The card (360 : 236) and the cover (2.4 : 1, at least 300 tall) |
The share image (public/opengraph-image.png) |
2400 × 1260 | Shared links (below) |
Photos in a fixed frame are cropped to fill it, from the centre, so a photo of other proportions works, but you lose the edges the frame cuts. Frames that follow the screen change shape between phone, tablet and desktop, so keep the subject away from the edges. A content path that points to a missing file stops the build with its name.
Every photo has an alt: a short description for screen readers and search engines. Write one for each photo you change
(an empty "alt": "" marks a photo as decoration, as the call-to-action band’s).
src/assets/images/logo.svg and logo-white.svg are copies of the wordmark for use elsewhere (an e-mail signature, a
social profile); the site draws its wordmark from Wordmark.astro (Making it look like your brand).
Videos
Section titled “Videos”Home has three clips: the hero’s (hero.video in src/content/pages/home.json, playing under the title), the small clip
of “About Balancee” (about.video, playing while it is on screen) and the testimonial’s (testimonials.items[0].video, which
plays when “Watch a review” is clicked). Each is a src and a poster. In the demo all three are clips from Pexels,
played from the Pexels website (https://videos.pexels.com/…); they are not in the download. Replace them before you
publish, with clips you have the rights to:
- Put the file in
public/, for examplepublic/videos/hero.mp4(an MP4, H.264, 1280 × 720 is plenty; keep it a few MB). - Set
"src": "/videos/hero.mp4"in thevideoentry, and give it a poster insrc/assets/images/(poster.src, with itsalt).
A full URL to a file on your own video host works too. The videos are muted and loop, and have no controls; the poster stays until the video plays. To leave a clip out, remove the section that plays it from the page file (Pages and sections).
Files browsers ask for
Section titled “Files browsers ask for”Files that browsers and social networks ask for by name live in public/:
| File | What it is |
|---|---|
public/icon-light.svg, public/icon-dark.svg |
The icon in the browser tab: the “B” in white on Ink for a light browser theme, the “B” in Ink on white for a dark theme |
public/apple-icon.png |
The icon on a phone’s home screen (180 × 180) |
public/opengraph-image.png |
The picture shown when someone shares a link (2400 × 1260; 1200 × 630 or larger) |
The share image’s description for screen readers is shareImage.alt in src/lib/meta.ts, next to its size: change
width and height there if your image has another size, and write a description of your own (the demo’s calls the
site a template). Every page uses this image when shared, apart from the posts and the case studies, which share their
cover.
Text that is not in content/
Section titled “Text that is not in content/”Almost every word is content, including the form’s messages (shared.json) and the names screen readers hear. The few
interface words that never change per site live in the code:
- “Main” and “Mobile” (the menus’ names for screen readers) and “Menu” (the phone menu button’s name) in
src/components/site/Header.astro; - the date format of the cards and legal pages (“Feb 21, 2024”) in
src/lib/format.ts; - the newsletter box’s two messages, “Thank you” and “Try again”, in
src/lib/forms/definitions.ts; - the fallback description of a legal page in
src/pages/legal/[slug].astro; - the share image’s description in
src/lib/meta.ts; - the page’s language,
lang="en", insrc/layouts/Layout.astro.
Search for the word and you will find it.
After editing
Section titled “After editing”npm run checknpm run buildnpm run check compares the collections with their schemas and the page copy with the sections that read it, and names
the file and the field that is missing. A successful build means every page still renders and every image it shows
exists. Neither checks that links written as text ("/contact") lead somewhere: click through the site once with
npm run preview after big changes. See Going live for the rest of the checklist.