# Sections

## Sections

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

A **section** is one full-width block of a page: the hero, the projects, the services, the FAQ. Each section is two kinds of file that share a name:

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

[How Margo Works](/margo/getting-started/how-margo-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 `french/` and `arabic/`. 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
  faqSection:
    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. Margo 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 `description: ""` removes the short line under a heading.

```yaml
# src/content/pricing/english/-index.md
faqSection:
  title: "Questions about *prices*" # replaces the title only
  options:
    layout: "single" # 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 `teamSection:` instead of `teamGridSection:`, 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`, 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`.

The `contact`, `faq`, and `pricing` collections have no schema, so blocks in `src/content/contact/`, `src/content/faq/`, and `src/content/pricing/` are not checked. Open the page after each change.

<Aside type="caution">
  A block only works on a page whose route reads it. The table below 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 call to action above the footer, where the page shows it), and inner pages read `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 |
| --- | --- | --- |
| Solo designer `/` | `homepage/english/-index.md` | `heroSection`, `projectsSection`, `servicesSection`, `statsSection`, `aboutSection`, `testimonialsSection`, `logosSection`, `pricingSection`, `faqSection`, `journalSection` |
| Studio `/home-studio/` | `homepage/english/home-studio.md` | `heroSection`, `logosSection`, `projectsSection`, `quoteSection`, `servicesSection`, `stepsSection`, `statsSection`, `teamGridSection`, `testimonialsSection`, `journalSection` |
| Photographer `/home-photo/` | `homepage/english/home-photo.md` | `heroSection`, `quoteSection`, `gallerySection`, `projectsSection`, `pricingSection`, `logosSection`, `testimonialsSection` |
| Projects `/projects/` | `projects/english/-index.md` | `projectsSection`, `logosSection` |
| Project page | `projects/english/<project>.md` | `statsSection`, `quoteSection`, `gallerySection`, `nextProjectSection`, `logosSection` |
| Archive `/archive/` | `pages/english/archive.mdx` | `projectsSection` |
| Services `/services/` | `services/english/-index.md` | `servicesSection`, `stepsSection`, `faqSection` |
| Pricing `/pricing/` | `pricing/english/-index.md` | `pricingSection`, `faqSection` |
| About `/about/` | `about-us/english/-index.md` | `aboutSection`, `statsSection`, `servicesSection`, `testimonialsSection`, `logosSection` |
| Team `/team/` | `team/english/-index.md` | `teamGridSection` |
| Team member page | `team/english/<member>.md` | `teamGridSection` (the other members) |
| Testimonials `/testimonials/` | `testimonials/english/-index.md` | `testimonialsSection`, `statsSection` |
| FAQ `/faq/` | `faq/english/-index.md` | `faqSection` |
| Contact `/contact/` | `contact/english/-index.md` | `contactSection`, `faqSection` |
| Journal `/blog/` | `blog/english/-index.mdx` | `blogListSection`, `newsletterSection` |
| Journal post | `blog/english/<post>.mdx` | `relatedPostsSection` |
| Text pages (legal) | `pages/english/<page>.mdx` | `contentPage` (a notice above the text) |

Service pages are built from the fields of each service file (its process, related projects, and questions), not from section blocks. See [Collections](/margo/customization/collections/). Project pages are covered in [Projects](/margo/customization/projects/).

The section order on each page is set in its route file in `src/pages/[...lang]/`. See [Homepages](/margo/customization/homepages/) and [Pages](/margo/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](/margo/customization/section-layouts/).

#### Work And Story
| Section (component) | Content file | Page block | Used on |
| --- | --- | --- | --- |
| Hero (`HeroSection`) | `hero-section.md` | `heroSection` | The three homepages |
| Projects (`ProjectsSection`) | `projects-section.md` | `projectsSection` | The three homepages, `/projects/`, `/archive/`, and the related work on service pages. The projects themselves come from `src/content/projects/` |
| Gallery (`GallerySection`) | `gallery-section.md` | `gallerySection` | Photographer homepage, and the images of each project page |
| Next project (`NextProjectSection`) | `next-project-section.md` | `nextProjectSection` | The end of each project page |
| Quote (`QuoteSection`) | `quote-section.md` | `quoteSection` | Studio and photographer homepages, and the client quote on project pages |
| About (`AboutSection`) | `about-section.md` | `aboutSection` | Solo designer homepage, `/about/` |
| Experience (`ExperienceSection`) | `experience-section.md` | `experienceSection` | Inside the about section: the work history under the text or the portrait |
| Stats (`StatsSection`) | `stats-section.md` | `statsSection` | Solo designer and studio homepages, `/about/`, `/testimonials/`, and the results on project pages |
| Team (`TeamGridSection`) | `team-grid-section.md` | `teamGridSection` | Studio homepage, `/team/`, team member pages. The members come from `src/content/team/` |

#### Services And Prices
| Section (component) | Content file | Page block | Used on |
| --- | --- | --- | --- |
| Services (`ServicesSection`) | `services-section.md` | `servicesSection` | Solo designer and studio homepages, `/services/`, `/about/`. The services come from `src/content/services/` |
| Tools (`ToolsSection`) | `tools-section.md` | `toolsSection` | Inside the services `split` layout, as small icon tiles. Service pages take each tool's icon from this file |
| Steps (`StepsSection`) | `steps-section.md` | `stepsSection` | Studio homepage, `/services/`, and the process on service pages |
| Pricing (`PricingSection`) | `pricing-section.md` | `pricingSection` | Solo designer and photographer homepages, `/pricing/` |
| FAQ (`FaqSection`) | `faq-section.md` | `faqSection` | Solo designer homepage, `/faq/`, `/contact/`, `/pricing/`, `/services/`, and the questions on service pages |

#### Proof
| Section (component) | Content file | Page block | Used on |
| --- | --- | --- | --- |
| Testimonials (`TestimonialsSection`) | `testimonials-section.md` | `testimonialsSection` | The three homepages, `/about/`, `/testimonials/` |
| Logos (`LogosSection`) | `logos-section.md` | `logosSection` | The three homepages, `/about/`, `/projects/`, and project pages (not photo series) |

#### Contact, Journal, And Other Pages
| Section (component) | Content file | Page block | Used on |
| --- | --- | --- | --- |
| Call to action (`CallToAction`) | `call-to-action.md` | `ctaSection` | Above the footer on most pages, and on the studio and photographer homepages. Not on the solo designer homepage, `/contact/`, the journal list pages, `/elements/`, or the 404 page |
| Contact (`ContactSection`) | `contact-section.md` | `contactSection` | `/contact/` |
| Journal (`JournalSection`) | `journal-section.md` | `journalSection` | Solo designer and studio homepages |
| Journal list (`BlogListSection`) | `blog-list-section.md` | `blogListSection` | `/blog/`, its next pages, category and tag pages |
| Newsletter (`NewsletterSection`) | `newsletter-section.md` | `newsletterSection` | The journal list pages |
| Related posts (`RelatedPostsSection`) | `related-posts-section.md` | `relatedPostsSection` | Under each journal post |
| Not found (`NotFoundSection`) | `not-found-section.md` | `notFoundSection` | The 404 page |

Two names don't follow the pattern: the call to action is `CallToAction` / `call-to-action.md` / `ctaSection`, and the team is `TeamGridSection` / `team-grid-section.md` / `teamGridSection`.

The experience and tools sections appear inside other sections, so edit their section files. Their blocks (`experienceSection`, `toolsSection`) work only on a page that shows the section on its own, which no page does as shipped.

Two more files in `src/content/sections/` belong to site-wide parts: `footer.md`, the copy of every footer layout ([Footer](/margo/customization/footer/)), and `cookie-consent.md`, the cookie banner ([Cookies & Analytics](/margo/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: title, breadcrumbs, a small pill above the title, the line under it, buttons, an optional portrait, and its layout (`centered`, `left`, or `split`). See [Section Layouts](/margo/customization/section-layouts/) |
| `contentPage` | Text pages in `src/content/pages/` | `notice`: a note above the text, for example that a legal text is a template to adapt |
| `layoutGallery` | `pages/english/elements.mdx` | The copy around the `/elements/` previews |

A page's frontmatter can also set `headerLayout`, `footerLayout`, and `contactDock` for that page only. See [Header](/margo/customization/header/) and [Footer](/margo/customization/footer/).

### Add A Section To A Page
This is a small code edit in the page's route file in `src/pages/[...lang]/`. On a homepage, add a `<LayoutVariants section="..." content={...} />` line where you want the section: [Homepages](/margo/customization/homepages/#reorder-or-remove-sections) shows how. On any other page, import the component and place it inside `<Base>`:

```astro
---

const { statsSection } = entry?.data ?? {};
---
<StatsSection content={statsSection} />
```

Then add the block (for example `statsSection:`) to the page's content file in every language folder, or leave it out to use the section file as it is.

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
french and arabic folders. Don't edit src/content/sections/. Then run npm run astro-check.
```

```text
Add the [SECTION, e.g. quote] section to [PAGE, e.g. the main homepage] after the [OTHER]
section. Follow SKILLS.md: on a homepage, add a LayoutVariants line to the route file and take
the block from the content file; then add the block to the page's content file in every
language folder if it needs its own text.
```