How Givo Works
Skill level: Everyone · Time: 10 minutes
Read this page once and the rest of the theme stops being a mystery. Givo is built from a few simple ideas that repeat everywhere.
The Big Picture
Givo is a static site: when you run npm run build, it turns your text files into finished HTML pages in dist/. In the Astro edition there is no database and no admin panel: your files are the website. The Tina edition adds a visual editor for those same files, and the Sanity edition keeps your content in your own Sanity project. The built site is static files in all three. See Theme Editions.
config.toml ──► site settings, [organization] details, forms, header and footer layoutsmenu.en.json ─► header and footer links, the Causes mega menutheme.css ────► colors, type scale, pattern strengthdonate/ ──────► currency, amounts, impact lines, monthly tiers, payment connectioncauses/ ──────► one file per cause: goal, raised, donors, deadline
ROUTE src/pages/[...lang]/donate.astro │ which sections, in which order │ ├─ PAGE src/content/donate/english/-index.md │ title, SEO, page header, giving data, named blocks │ └─ each SECTION ├─ default: sections/english/plans-section.md ├─ + page block: plansSection: { ... } └─ look: options.layout (many sections)
Base.astro wraps every page: head · header · page · call to action · footer · donate bar on phones · cookie banner1. Routes Decide What A Page Shows
Each file in src/pages/[...lang]/ is one page (a route). It lists the sections that page shows, top to bottom. This is the donate page, src/pages/[...lang]/donate.astro, shortened:
<Base {...entry?.data}> <PageHeader content={{ ...entry?.data, currentLabel: entry?.data.title }} /> <LayoutVariants section="donate" id="give" content={donateSection} /> <LayoutVariants section="plans" id="monthly" content={plansSection} /> <GiftSplitSection id="spend" content={...} /> <!-- other ways to give --> <LayoutVariants section="faq" id="questions" content={questionsSection} /></Base>To reorder sections, move a line. To remove a section from one page, delete its line. The [...lang] folder name means one file builds every language: English at /donate/, French at /fr/donate/, Arabic at /ar/donate/.
Sections that have more than one layout are drawn through <LayoutVariants section="..." content={...} />. Keep that wrapper when you move them.
2. Sections Have Default Content
Every section has a matching content file in src/content/sections/<language>/. For example, CausesSection.astro reads causes-section.md. That file holds the section’s default text, lists, buttons, and options, with comments that explain them.
Edit a section file and the change appears everywhere that section is used, unless a page overrides it. Set enable: false at the top of the file to hide the section on every page.
3. Pages Can Override Any Section
A page file can change a section for that page only with a named block. Almost every page file in Givo uses them, the homepages included. This is the causes block on the causes page:
---causesSection: enable: true title: "" # empty: the filter row sits right under the page header limit: 0 # every cause options: layout: "featured" # grid | featured | list filter: true # category tabs---Block names are the section name in camelCase: heroSection, causesSection, plansSection, questionsSection, ctaSection, and so on. Many blocks have a comment that names the section file they override (# defaults: hero-section.md). Sections has the full list.
A block with a wrong name, for example faqSection: instead of questionsSection:, is ignored without an error. Copy block names from the page file, the Sections table, or sectionsSchema in src/sections.schema.ts.
4. How Overrides Merge
When a page block meets the section’s default content, Givo merges them with four rules:
| You write in the page block | Result |
|---|---|
A text or number (title: "Hello") | Replaces the default value |
An object (button:, options:) | Merges key by key: only the keys you write change |
A list (list:, items:, steps:) | Replaces the whole list. Write every item you want to keep |
An empty string (description: "") | Clears the value. Leave the key out to keep the default |
So this block switches the call to action to another layout on one page and keeps all its text and buttons:
ctaSection: enable: true options: layout: "volunteer"Keep enable: true at the top of each page block, as the shipped files do. In files that have a schema, each block is checked on its own before the merge: most of its fields are optional, but contactSection needs title, description, imagePosition, and form, and a button needs label.
5. Layouts Change The Look, Not The Content
Many sections can be drawn in more than one way. The layout is one option:
options: layout: "appeal" # the hero: photo | appeal | communityThe allowed values are in the comment next to layout:, and the full list is in layoutOption([...]) for that section in src/sections.schema.ts. Without a value, a section uses the first value of its list. Most content fields stay the same, so you can switch back and forth. A few fields belong to one layout only, and their comment says so. Set the layout in the section file (every page) or in a page block (one page).
Open /elements/ on your local site to see the layouts of the multi-layout sections and of the page header side by side. See Section Layouts for every value.
6. Base Wraps Every Page
src/layouts/Base.astro adds the parts that every page shares:
- the
<head>: title, description, Open Graph tags, structured data, fonts, and your[head]scripts - the header in one of three layouts (
[settings.layout] headerinconfig.toml, orheaderLayoutin a page), with the menus, the Donate button, and, in thecenteredandutilitylayouts, the phone from[organization](utilityadds an “open now” line from your office hours) - the call to action above the footer, from
call-to-action.mdand the page’sctaSectionblock - the footer in one of three layouts (
[settings.layout] footer, orfooterLayoutin a page), from the menu files,[organization],src/config/social.json, andsrc/i18n/<language>.json. Every footer layout also has the Ask AI row ([settings.pageActions]) and the theme credit ([settings.themeCredit]) - the Donate bar on phones (
[settings.mobileActionBar]), the cookie banner, the back-to-top button, and shared scripts
7. Organization Details Are Set Once
Your organization’s name, registration number, phone, email, address, office hours, time zone, and closed dates live in [organization] in config.toml. The header, footer, contact page, donation form fine print, event pages, structured data, and llms.txt all read them from there.
Inside Markdown text and some content fields, you can write {name}, {phone}, {email}, {address}, or {hours}, and Givo fills in the value from [organization]. The tokens work in .md files, not in .mdx files. See Organization Info.
8. Giving Numbers Come From One File
The donation form, the quick donate panel, the monthly tiers, and the impact receipt all read src/content/donate/<language>/-index.md: the currency, the preset amounts, the smallest amount, the “cover the fees” percentage, the impact map (amount to outcome), and the monthly tiers. You never type an amount into a section. Keep every number the same in every language: npm run build prints a [donate] warning when they differ. See Donation Form.
9. Campaign Figures Are Counted At Build Time
Each cause file has a goal, the amount raised, the number of donors, and an optional deadline. Givo turns them into the progress bar, the “raised of goal” line, the donor count (“1 donor”, “412 donors”), and the days left. The site does not count gifts: you update raised and donors yourself.
The days left are counted on the day the site is built. A static site keeps showing that count until the next build, so rebuild the site every day (most hosts can run a scheduled deploy) while an appeal is running. On the deadline day a cause says “Last day”, and after it the cause says “Ended” but stays online and still takes gifts. See Causes & Campaigns.
10. Small Interface Text Lives In i18n Files
Labels that are not page content, such as the header button (“Donate”), the “days left” and “donors” labels, form messages, the page-title tagline, the footer description and copyright, and the 404 text, live in src/i18n/<language>.json. Several config.toml labels are empty on purpose (label = ""): empty means “use the translated text from the i18n file”. Fill them in only if your site has one language.
11. Config Is Converted Before Astro Reads It
Astro cannot read TOML, so npm run dev, npm run build, and npm run astro-check first convert src/config/config.toml into .astro/config.generated.json. While npm run dev is running, this happens every time you save config.toml, and the page reloads. Always edit the TOML file, never the generated JSON.
Restart npm run dev after you change trailingSlash or [settings.multilingual], after you add a language, and after you change src/config/fonts.json: Astro reads those only when it starts.
12. Collections Hold The Repeated Content
A collection is a folder of similar entries, each one a file. Givo’s collections are homepage, pages, sections, causes, donate, events, gallery, impact, reviews, blog, author, careers, team, faq, about-us, and contact. They are defined in src/content.config.ts, and most have a schema: the list of fields an entry may have. See Collections.
13. What Happens During A Build
config.tomlis converted to JSON.- Astro checks the content collections that have a schema, including the named blocks in their page frontmatter (
sectionsSchemainsrc/sections.schema.ts). A wrong value there stops the build with the file name and field. Thesectionsandcontactcollections have no schema, so a wrong value in those files is not reported. Check those pages in the browser. - Every route is rendered once per language into
dist/, with the campaign figures and days left of that day. A page without its ownimagegets a generated Open Graph card. llms.txt,llms-full.txt, the Markdown copies of pages, the add to calendar file of each event, the sitemap,robots.txt, and the RSS feed are written.- Yellow warnings print for anything still a placeholder or wrong:
[site]for thehttps://example.comsite URL,[forms]for a placeholder form address or an unconnected donation form,[organization]for a value it could not read, and[donate]when the donation files of your languages differ. - Draft pages are removed from the sitemap.
Development vs. Production
Some things behave differently while you work with npm run dev:
| Feature | npm run dev | Built site (npm run build) |
|---|---|---|
Pages with draft: true | Shown, so you can preview them | Not built |
Changes to config.toml | Shown when you save. Restart after changing languages, trailingSlash, or fonts | Read at the start of every build |
| Placeholder form address | A warning box inside the form, and a [forms] line in the terminal | A [forms] line in the build output |
| Donation form without a payment connection | A notice inside the form; it sends nothing | Sends nothing; a [forms] line in the build output |
| Site URL warning | Not shown | Printed when the Astro build finishes, while the URL is example.com |
| Days left on causes | Counted when the page is loaded | Counted on the day of the build |
| Open Graph cards for each page | Not generated | Generated during the build |
Find Where Any Text Comes From
See a sentence on the site and want to change it? Search the whole project for it: in VS Code press Ctrl + Shift + F (⌘ + Shift + F on Mac) and paste a few words. It will be in one of these places, checked in this order:
- The page’s own file, in a named block (
src/content/<page>/<language>/-index.md, orsrc/content/pages/<language>/for single pages such as/volunteer/) - The section’s default file (
src/content/sections/<language>/) - A collection entry (
src/content/causes/,events/,blog/,team/,reviews/,careers/) - The giving data (
src/content/donate/<language>/-index.md) for amounts, impact lines, and monthly tiers - The interface text (
src/i18n/<language>.json) - The menus (
src/config/menu.<language>.json) - Site settings and organization details (
src/config/config.toml)
If the same text appears in both a page block and a section file, the page block wins on that page. If you can’t find a phone number, an address, a registration number, or office hours anywhere in src/content/, it comes from [organization] in config.toml.