# How Givo Works

## 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](/givo/features/editions/).

```text
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:

```astro
<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:

```yaml
# 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](/givo/customization/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](/givo/customization/sections/) table, or `sectionsSchema` in `src/sections.schema.ts`.

<Aside type="caution" title="A block only works where the route uses it">
  Adding `eventsSection:` to the donate page does nothing, because
  `donate.astro` does not render the events section. Check the route file to
  see which blocks a page reads.
</Aside>

### 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:

```yaml
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:

```yaml
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](/givo/customization/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](/givo/customization/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](/givo/customization/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](/givo/customization/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](/givo/customization/collections/).

### 13. What Happens During A Build
<Steps>

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.

</Steps>

### 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 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>F</kbd> (<kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>F</kbd> 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`.