# Sections

## Sections

**Files:** `src/content/sections/english/` (and each other language folder), page content files · **Skill level:** Beginner to edit, light code to add or move

A **section** is one full-width block of a page: the hero, the causes, the supporter quotes, the FAQ. Each section is two files that share a name:

```text
src/layouts/components/sections/ReviewsSection.astro   ← how it looks (component)
src/content/sections/english/reviews-section.md        ← what it says (content)
src/content/sections/french/reviews-section.md
src/content/sections/arabic/reviews-section.md
```

[How Givo Works](/givo/getting-started/how-givo-works/) explains the idea in full. This page is the practical reference: every section, its file, and the block name a page uses to change it.

### Change A Section Everywhere
Edit its file in `src/content/sections/english/` and the file with the same name in each other language folder. The comments in each file list its options and the allowed values.

Section files have no schema, so `npm run astro-check` doesn't catch a wrong value in them, such as a misspelled `layout`. Copy values from the comments, then check the page in the browser.

### Hide A Section
- **Everywhere:** set `enable: false` at the top of its section file.
- **On one page:** add its block to that page's content file with `enable: false`:

  ```yaml
  questionsSection:
    enable: false
  ```

### Change A Section On One Page
Add a **named block** to the page's content file with only the keys you want to change. Givo merges the block over the section file:

- **Objects merge key by key.** A block only needs the fields it changes.
- **Lists replace the whole list.** Repeat every item you want to keep.
- **An empty string (`""`) clears a value**, for example `image: ""` hides a photo.

```yaml
# src/content/donate/english/-index.md
questionsSection:
  title: "Questions about giving" # replaces the title only
  options:
    layout: "grid" # the other options keep their section defaults
```

Copy block names exactly from the catalog below (they are the keys of `sectionsSchema` in `src/sections.schema.ts`). A block with a wrong name, for example `faqSection:` instead of `questionsSection:`, is ignored without an error.

In collections with a schema, `npm run astro-check` checks the values inside each block before the merge. Most fields are optional there, with these exceptions:

- `contactSection` needs `title`, `description`, `imagePosition`, and `form`. Copy them from `src/content/sections/english/contact-section.md`.
- A nested object keeps its own required fields: a `button` needs a `label`.
- `ctaSection` ships **off** in its section file. A `ctaSection:` block that changes only the title leaves the closing band hidden. Start the block with `enable: true`.

The `contact` collection (`src/content/contact/`) has no schema, so blocks in the contact page file are not checked. Open `/contact/` after each change.

<Aside type="caution">
  A block only works on a page whose route reads it. The table [Blocks Each Page
  Reads](#blocks-each-page-reads) lists them. A block for a section the page
  doesn't show does nothing.
</Aside>

### Blocks Each Page Reads
Every page also reads `ctaSection` (the closing band above the footer) and, for inner pages, `pageHeader`. Paths are for English. The other languages use the same file names in `french/` and `arabic/`.

| Page | Page file (`src/content/`) | Blocks the page reads |
| --- | --- | --- |
| Main homepage `/` | `homepage/english/-index.md` | `heroSection`, `metricsSection`, `featureGridSection`, `causesSection`, `reviewsSection`, `giftSplitSection`, `relatedPostsSection`, `eventsSection`, `involvedSection` (a second feature grid), `clientsSection` |
| Appeal `/home-appeal/` | `homepage/english/home-appeal.md` | `announcementBar`, `heroSection`, `appealBriefSection`, `appealUpdatesSection`, `giftSplitSection`, `clientsSection`, `reviewsSection`, `questionsSection` |
| Community `/home-community/` | `homepage/english/home-community.md` | `heroSection`, `featureGridSection`, `eventsSection`, `volunteerRolesSection`, `metricsSection`, `gallerySection`, `plansSection`, `reviewsSection`, `newsletterSection` |
| Causes `/causes/` | `causes/english/-index.md` | `causesSection`, `questionsSection`, `categories` |
| Cause page | `causes/english/<cause>.md` | `causeHeroSection`, `questionsSection` (else the one in `-index.md`) |
| Donate `/donate/` | `donate/english/-index.md` | `donateSection`, `plansSection`, `spendSplit`, `otherWays`, `questionsSection`, `jumpNav` |
| Tribute `/tribute/` | `pages/english/tribute.md` | `tributePage`, `donateSection`, `questionsSection` |
| Events `/events/` | `events/english/-index.md` | `eventListingSection`, `categories` |
| Event page | `events/english/<event>.md` | `eventHeroSection` |
| Volunteer `/volunteer/` | `pages/english/volunteer.md` | `featureGridSection`, `volunteerRolesSection`, `stepsSection`, `volunteerSection`, `questionsSection` |
| Fundraise `/fundraise/` | `pages/english/fundraise.md` | `featureGridSection`, `stepsSection`, `fundraisersSection`, `toolkitSection`, `contactSection`, `questionsSection` |
| Partners `/partners/` | `pages/english/partners.md` | `partnersPage` |
| Impact `/impact/` | `impact/english/-index.md` | `figures`, `spend`, `results`, `reports`, `facts`, `policies`, `questionsSection` |
| Gallery `/gallery/` | `gallery/english/-index.md` | `categories`, `items` (the photos) |
| About `/about/` | `about-us/english/-index.md` | `storySection`, `metricsSection`, `stepsSection`, `valuesSection`, `teamGridSection`, `clientsSection` |
| Team `/team/` | `team/english/-index.md` | `teamGridSection`, `jumpNav` |
| Testimonials `/testimonials/` | `pages/english/testimonials.md` | `reviewsSection`, `videoSection` |
| Careers `/careers/` | `careers/english/-index.md` | `valuesSection`, `openRolesSection`, `stepsSection` |
| FAQ `/faq/` | `faq/english/-index.md` | `questionsSection` |
| Contact `/contact/` | `contact/english/-index.md` | `contactSection`, `contactOptionsSection`, `questionsSection` |
| Stories `/blog/` | `blog/english/-index.md` | `blogListSection`, `newsletterSection` |
| Story page | `blog/english/<story>.mdx` | `relatedPostsSection` and `newsletterSection` from their section files |
| Text pages (legal) | `pages/english/<page>.md` | `contentPage` |

The section order on each page is set in its route file in `src/pages/[...lang]/`. See [Homepages](/givo/customization/homepages/) and [Pages](/givo/customization/pages/).

### Section Catalog
Every section, its content file in `src/content/sections/<language>/`, and the block name a page uses to override it. Layout values are in [Section Layouts](/givo/customization/section-layouts/).

#### Homepage And Giving
| Section (component) | Content file | Page block | Used on |
| --- | --- | --- | --- |
| Hero (`HeroSection`) | `hero-section.md` | `heroSection` | All three homepages. The `photo` layout holds the quick donation widget |
| Numbers (`MetricsSection`) | `metrics-section.md` | `metricsSection` | Main and community homepages, `/about/` |
| Feature grid (`FeatureGridSection`) | `feature-grid-section.md` | `featureGridSection` (and `involvedSection` on `/`) | Main and community homepages, `/volunteer/`, `/fundraise/` |
| Causes (`CausesSection`) | `causes-section.md` | `causesSection` | Main homepage, `/causes/` |
| Cause hero (`CauseHeroSection`) | `cause-hero-section.md` | `causeHeroSection` | The top of every cause page |
| Donate (`DonateSection`) | `donate-section.md` | `donateSection` | `/donate/` and `/tribute/` (the full donation form) |
| Giving tiers (`PlansSection`) | `plans-section.md` | `plansSection` | `/donate/`, community homepage. The tiers come from the donate file |
| Where your gift goes (`GiftSplitSection`) | `gift-split-section.md` | `giftSplitSection` | Main and appeal homepages |
| Appeal brief (`AppealBriefSection`) | `appeal-brief-section.md` | `appealBriefSection` | Appeal homepage |
| Appeal updates (`AppealUpdatesSection`) | `appeal-updates-section.md` | `appealUpdatesSection` | Appeal homepage. The updates come from the cause file |
| Supporter voices (`ReviewsSection`) | `reviews-section.md` | `reviewsSection` | All three homepages, `/testimonials/` |
| Steps (`StepsSection`) | `steps-section.md` | `stepsSection` | `/about/`, `/volunteer/`, `/fundraise/`, `/careers/` |
| Partners (`Clients`) | `clients.md` | `clientsSection` | Main and appeal homepages, `/about/` |
| FAQ (`QuestionsSection`) | `questions-section.md` | `questionsSection` | Appeal homepage, FAQ, contact, causes and cause pages, donate, tribute, volunteer, fundraise, impact |
| Closing band (`CallToAction`) | `call-to-action.md` | `ctaSection` | Above the footer, on pages that turn it on |

#### Events, Volunteering, And Fundraising
| Section (component) | Content file | Page block | Used on |
| --- | --- | --- | --- |
| Upcoming events (`EventsSection`) | `events-section.md` | `eventsSection` | Main and community homepages |
| Events index (`EventListingSection`) | `event-listing-section.md` | `eventListingSection` | `/events/` |
| Event hero (`EventHeroSection`) | `event-hero-section.md` | `eventHeroSection` | The top of every event page |
| Volunteer roles (`VolunteerRolesSection`) | `volunteer-roles-section.md` | `volunteerRolesSection` | `/volunteer/`, community homepage |
| Volunteer sign-up (`VolunteerSection`) | `volunteer-section.md` | `volunteerSection` | `/volunteer/` |
| Example fundraisers (`FundraisersSection`) | `fundraisers-section.md` | `fundraisersSection` | `/fundraise/` |
| Fundraising toolkit (`ToolkitSection`) | `toolkit-section.md` | `toolkitSection` | `/fundraise/` |
| Gallery strip (`GallerySection`) | `gallery-section.md` | `gallerySection` | Community homepage |

#### About, Contact, And Stories
| Section (component) | Content file | Page block | Used on |
| --- | --- | --- | --- |
| Our story (`StorySection`) | `story-section.md` | `storySection` | `/about/` |
| Values (`ValuesSection`) | `values-section.md` | `valuesSection` | `/about/`, `/careers/` |
| Team (`TeamGridSection`) | `team-grid-section.md` | `teamGridSection` | `/team/`, `/about/` |
| Video story (`VideoSection`) | `video-section.md` | `videoSection` | `/testimonials/` |
| Open roles (`OpenRolesSection`) | `open-roles-section.md` | `openRolesSection` | `/careers/` |
| Contact (`ContactSection`) | `contact-section.md` | `contactSection` | `/contact/`, `/fundraise/` (the register form) |
| Contact options (`ContactOptionsSection`) | `contact-options-section.md` | `contactOptionsSection` | `/contact/` |
| Stories list (`BlogListSection`) | `blog-list-section.md` | `blogListSection` | `/blog/`, its pages, category and tag pages |
| Story teaser (`RelatedPostsSection`) | `related-posts-section.md` | `relatedPostsSection` | Main homepage, under each story |
| Newsletter (`NewsletterSection`) | `newsletter-section.md` | `newsletterSection` | Stories pages, community homepage |
| Not found (`NotFoundSection`) | `not-found-section.md` | `notFoundSection` | 404 pages |

Two names don't follow the pattern: the closing band is `CallToAction` / `call-to-action.md` / `ctaSection`, and the FAQ is `QuestionsSection` / `questions-section.md` / `questionsSection`. The partners logos are `Clients` / `clients.md` / `clientsSection`.

Two more files in `src/content/sections/` belong to site-wide widgets: `announcement-bar.md`, the optional bar above the header ([Header](/givo/customization/header/#the-announcement-bar)), and `cookie-consent.md`, the cookie banner ([Cookies & Analytics](/givo/customization/cookies-analytics/)).

#### Page-Only Blocks
These blocks have no section file. They exist only in page frontmatter:

| Block | Where | What it sets |
| --- | --- | --- |
| `pageHeader` | Any inner page | The page header: badge, description, buttons, photo and caption, and its layout. See [Section Layouts](/givo/customization/section-layouts/#page-header) |
| `jumpNav` | `donate/english/-index.md`, `team/english/-index.md` | The "On this page" links under the page header (`label`, `anchor`) |
| `spendSplit`, `otherWays` | `donate/english/-index.md` | "Where your money goes" and "Other ways to give" on `/donate/`. See [Donation Form](/givo/customization/donation-form/) |
| `tributePage` | `pages/english/tribute.md` | The tribute paths and the type ticked on load. See [Donation Form](/givo/customization/donation-form/) |
| `partnersPage` | `pages/english/partners.md` | Every block of `/partners/`. See [Partners & Gallery](/givo/customization/partners-gallery/) |
| `figures`, `spend`, `results`, `reports`, `facts`, `policies` | `impact/english/-index.md` | The impact page. See [Impact & Transparency](/givo/customization/impact-transparency/) |
| `announcementBar` | Any page | The appeal bar above the header, on this page only |
| `contentPage` | Text pages in `src/content/pages/` | Options of the legal and policy pages |
| `layoutGallery` | `pages/english/elements.md` | The copy around the `/elements/` previews |

<Aside type="tip">
  Some sections take their items from a collection instead of the section file:
  causes from `src/content/causes/`, events from `src/content/events/`,
  supporter quotes from `src/content/reviews/`, team members from
  `src/content/team/`, and stories from the blog. The giving tiers come from
  `src/content/donate/`. See [Collections](/givo/customization/collections/).
</Aside>

### Add A Section To A Page
This is a small code edit in the page's route file in `src/pages/[...lang]/`. Import the component and place it inside `<Base>`, then add its block with the copy to the page's content file in every language folder:

```astro
---

---
<StepsSection content={page?.data.stepsSection} />
```

The hero, metrics, causes, reviews, events, plans, FAQ, donate, steps, and closing band are written as `<LayoutVariants section="faq" content={questionsSection} />` on the homepages. Keep that wrapper when you move them: it renders the section exactly like a direct import, and lets the demo layout switcher preview it.

Building a brand-new section is a developer task. `AGENTS.md` and the "Add a new section" recipe in `SKILLS.md` explain the rules (one `.astro` component, one content file in each language, and a schema in `src/sections.schema.ts`), so an AI assistant can do it for you.

### Do It With AI
```text
On the page [URL], change the [SECTION] section only for that page: [CHANGES]. Find the page's
content file and the block name in sectionsSchema of src/sections.schema.ts, add a named block
with only the keys that change (lists must repeat every item I keep), and do the same in the
other language folders. Don't edit src/content/sections/. Then run npm run astro-check.
```

```text
Add the [SECTION, e.g. steps] section to [PAGE, e.g. /impact/] after the [OTHER] section.
Follow the "Add a new section" and "Add or reorder a homepage section" recipes in SKILLS.md:
import the component in the route, then add the block with the copy to the page's content file
in every language folder.
```