Skip to content
New: Customize your theme with an AI assistant. Read the guide

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 layouts
menu.en.json ─► header and footer links, the Causes mega menu
theme.css ────► colors, type scale, pattern strength
donate/ ──────► currency, amounts, impact lines, monthly tiers, payment connection
causes/ ──────► 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 banner

1. 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:

src/content/causes/english/-index.md
---
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 blockResult
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 | community

The 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] header in config.toml, or headerLayout in a page), with the menus, the Donate button, and, in the centered and utility layouts, the phone from [organization] (utility adds an “open now” line from your office hours)
  • the call to action above the footer, from call-to-action.md and the page’s ctaSection block
  • the footer in one of three layouts ([settings.layout] footer, or footerLayout in a page), from the menu files, [organization], src/config/social.json, and src/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

  1. config.toml is converted to JSON.
  2. Astro checks the content collections that have a schema, including the named blocks in their page frontmatter (sectionsSchema in src/sections.schema.ts). A wrong value there stops the build with the file name and field. The sections and contact collections have no schema, so a wrong value in those files is not reported. Check those pages in the browser.
  3. Every route is rendered once per language into dist/, with the campaign figures and days left of that day. A page without its own image gets a generated Open Graph card.
  4. 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.
  5. Yellow warnings print for anything still a placeholder or wrong: [site] for the https://example.com site 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.
  6. Draft pages are removed from the sitemap.

Development vs. Production

Some things behave differently while you work with npm run dev:

Featurenpm run devBuilt site (npm run build)
Pages with draft: trueShown, so you can preview themNot built
Changes to config.tomlShown when you save. Restart after changing languages, trailingSlash, or fontsRead at the start of every build
Placeholder form addressA warning box inside the form, and a [forms] line in the terminalA [forms] line in the build output
Donation form without a payment connectionA notice inside the form; it sends nothingSends nothing; a [forms] line in the build output
Site URL warningNot shownPrinted when the Astro build finishes, while the URL is example.com
Days left on causesCounted when the page is loadedCounted on the day of the build
Open Graph cards for each pageNot generatedGenerated 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:

  1. The page’s own file, in a named block (src/content/<page>/<language>/-index.md, or src/content/pages/<language>/ for single pages such as /volunteer/)
  2. The section’s default file (src/content/sections/<language>/)
  3. A collection entry (src/content/causes/, events/, blog/, team/, reviews/, careers/)
  4. The giving data (src/content/donate/<language>/-index.md) for amounts, impact lines, and monthly tiers
  5. The interface text (src/i18n/<language>.json)
  6. The menus (src/config/menu.<language>.json)
  7. 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.

Type something to search...