# Section Layouts

## Section Layouts

**Skill level:** Beginner · **Time:** 1 minute per section

19 Margo sections can be drawn in more than one way (52 layouts in total, counting each default), and the page header has 3 layouts. You pick one with a single line, and the section keeps its copy, so you can try every option without rewriting anything.

```yaml
options:
  layout: "index"
```

### Where To Set A Layout
| Set it in…                                                         | It applies to…                   |
| ------------------------------------------------------------------ | -------------------------------- |
| The section file, `src/content/sections/<language>/<section>.md`   | Every page that uses the section |
| A page block, for example `projectsSection:` in a page file        | That page only                   |

Set it in every language folder: `english/`, `french/`, and `arabic/`.

Copy the value from the comment next to `layout:` in the file, or from the catalog below. Without a `layout` value, a section uses the first value of its list. The shipped section files set a value for every section, so check the file before you assume the default.

<Aside type="caution" title="Check misspelled values by eye">
  The section files, and the page files of the contact, FAQ, and pricing
  pages, have no schema. `npm run astro-check` doesn't report a misspelled
  layout there. Open the page after the change. In the other page files,
  `astro-check` reports a value that isn't in the list.
</Aside>

### Preview Layouts Before You Choose
`/elements/` shows every layout of the sections that have more than one, and of the page header, each with the line to copy. The page is hidden from search engines, the sitemap, and site search (`robots`, `excludeFromSitemap`, and `excludeFromSearch` in `src/content/pages/english/elements.mdx`). Keep it as a reference while you build. Before launch, delete `elements.mdx` in each language folder of `src/content/pages/`, `src/pages/[...lang]/elements.astro`, and the links to `/elements/` in each `src/config/menu.<language>.json`, or keep it unlisted.

`config.toml` also has a `[settings.layoutSwitcher]` table. It is a demo feature of the theme's own preview site. Keep `enable = false` on your site.

### Layout Catalog
The first value of each list is the section's default when `layout` is empty.

#### Hero
File: `hero-section.md` · Block: `heroSection`

| Layout     | What it looks like                                                                                 |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `stack`    | Large heading, buttons, and a ruled row with the rating and logos, beside a deck of 4 project cards (`cards`) |
| `panel`    | Heading and a row of figures (`meta`) above a wide 16:9 image or video (`media`)                    |
| `photo`    | A full-bleed photo (`media.image`) with light text and a caption row (`caption`)                    |
| `centered` | Text only, centered, with the rating under the buttons                                             |
| `masthead` | The heading set very large across the page, then the text and a mosaic of the first three `cards` projects |

`options.webgl` adds an animated background to `stack` and `panel`: `dots`, `flow`, or `none`.

#### Page Header
Block: `pageHeader` in a page file. The title comes from the page's `title`, or from `pageHeader.title`.

| Layout     | What it looks like                                                    |
| ---------- | --------------------------------------------------------------------- |
| `centered` | A centered column: pill, title, line, buttons                         |
| `left`     | The column on the left: breadcrumbs, title, the page's facts, line, buttons |
| `split`    | Title on the left; the line and buttons, or a portrait (`image`), on the right |

`options.titleSize` is `display` (large) or `title` (smaller). Project, service, team, journal, and text pages use `left` unless their own `pageHeader` block says otherwise. See [Pages](/margo/customization/pages/).

#### Projects
File: `projects-section.md` · Block: `projectsSection`. See [Projects](/margo/customization/projects/).

| Layout  | What it looks like                                                                           |
| ------- | -------------------------------------------------------------------------------------------- |
| `grid`  | Two columns of project cards                                                                 |
| `index` | Ruled rows (year, project, client, services); the cover follows the mouse pointer            |
| `wall`  | Image rows of different widths. Without `category` or `items`, it shows the photo series     |
| `stack` | Large cards that stick under the header and pile up as you scroll. Best with up to 6 projects |

`options.filters: true` adds category chips above `grid` and `index`.

#### Services
File: `services-section.md` · Block: `servicesSection`. The rows come from the services collection. See [Collections](/margo/customization/collections/).

| Layout  | What it looks like                                                         |
| ------- | -------------------------------------------------------------------------- |
| `split` | Heading and craft tiles on the left, icon rows on the right                |
| `list`  | Ruled rows that open on the deliverables                                   |
| `cards` | Three columns of cards with the starting price                             |
| `ruled` | The same content in a ruled grid                                           |
| `tabs`  | A segmented control, one panel per service with its deliverables           |

#### Pricing
File: `pricing-section.md` · Block: `pricingSection`. See [Pricing & FAQ](/margo/customization/pricing-faq/).

`subscription` (steps row, a feature card, the plan card, and a one-off project band) · `rates` (package rows with starting prices, and a strip of open and booked months) · `cards` (every plan as a card, with a monthly and yearly toggle).

#### FAQ
File: `faq-section.md` · Block: `faqSection`

`split` (questions on the left, a sticky booking card on the right) · `single` (one centered column) · `two-column` (heading on the left, questions on the right).

#### Call To Action
File: `call-to-action.md` · Block: `ctaSection`. Inner pages show it above the footer.

`card` (rating, heading, line, one button) · `band` (heading, line, and two buttons on a dark band; `options.webgl` works here too) · `split` (heading on the left, contact rows on the right).

#### Contact
File: `contact-section.md` · Block: `contactSection`. See [Contact & Booking](/margo/customization/contact-booking/).

`form` (the form beside your contact details) · `booking` (the form beside a booking card).

#### Other Sections
| Section       | File and block                                          | Layouts                                         |
| ------------- | ------------------------------------------------------- | ----------------------------------------------- |
| Quote         | `quote-section.md`, `quoteSection`                      | `centered` · `statement` (left-aligned, larger) |
| Tools         | `tools-section.md`, `toolsSection`                      | `tiles` (a wrapping row) · `marquee` (one slow moving row) |
| Stats         | `stats-section.md`, `statsSection`                      | `row` · `cards` · `ruled`                       |
| About         | `about-section.md`, `aboutSection`                      | `portrait` · `statement`                        |
| Experience    | `experience-section.md`, `experienceSection`            | `list` (rows that open) · `table`               |
| Steps         | `steps-section.md`, `stepsSection`                      | `row` (icons, no numbers) · `timeline` (numbered rows) |
| Logos         | `logos-section.md`, `logosSection`                      | `marquee` · `grid`                              |
| Testimonials  | `testimonials-section.md`, `testimonialsSection`        | `grid` · `marquee` · `spotlight` (one large quote at a time) |
| Journal       | `journal-section.md`, `journalSection`                  | `featured` · `grid` · `list`                    |
| Team          | `team-grid-section.md`, `teamGridSection`               | `grid` · `strip` (4 portraits in a row)         |
| Gallery       | `gallery-section.md`, `gallerySection`                  | `horizontal` · `masonry`                        |
| Next project  | `next-project-section.md`, `nextProjectSection`         | `banner` · `cards`                              |

These sections have one layout: the journal list (`blog-list-section.md`, `grid`), related posts (`rows`), newsletter (`split`), and the 404 section (`default`).

#### Page Templates And Site-Wide Layouts
| What                     | Where it is set                                                       | Values                                  |
| ------------------------ | --------------------------------------------------------------------- | --------------------------------------- |
| Project page template    | `options.layout` in a project entry in `src/content/projects/`        | `default` · `gallery` · `split`         |
| Header                   | `[settings.layout] header` in `config.toml`, or `headerLayout` on a page | `pill` · `bar` · `overlay`           |
| Footer                   | `[settings.layout] footer` in `config.toml`, or `footerLayout` on a page | `wordmark` · `columns` · `email`     |

See [Projects](/margo/customization/projects/), [Header](/margo/customization/header/), and [Footer](/margo/customization/footer/).

### Combinations On The Demo Homepages
The three homepages show combinations that suit each kind of portfolio. Their page files are in `src/content/homepage/english/`. See [Homepages](/margo/customization/homepages/).

| Section      | Solo designer (`/`) | Studio (`/home-studio/`) | Photographer (`/home-photo/`) |
| ------------ | ------------------- | ------------------------ | ----------------------------- |
| Hero         | `masthead`          | `panel`                  | `photo`                       |
| Projects     | `stack`             | `index`                  | `wall`                        |
| Quote        | –                   | `statement`              | `statement`                   |
| Services     | `ruled`             | `list`                   | –                             |
| Stats        | `ruled`             | `cards`                  | –                             |
| About        | `statement`         | –                        | –                             |
| Pricing      | `cards`             | –                        | `rates`                       |
| FAQ          | `two-column`        | –                        | –                             |
| Logos        | `grid`              | `marquee`                | `grid`                        |
| Testimonials | `spotlight`         | `marquee`                | `spotlight`                   |
| Journal      | `grid`              | `list`                   | –                             |
| Call to action | – (hidden)        | `band`                   | `split`                       |
| Header       | `bar` (site default) | `bar`                   | `overlay`                     |
| Footer       | `email` (site default) | `columns`             | `email`                       |

The studio homepage also shows steps (`timeline`) and the team (`strip`), and the photographer homepage a gallery (`horizontal`). A section left out of a homepage's route file doesn't show on that page, even if its page file has a block for it.

### Do It With AI
```text
Change the layout of the [SECTION] section to "[LAYOUT]" [on every page | on the PAGE page only].
For every page, set options.layout in src/content/sections/<language>/[FILE].md; for one page,
set it in that page's named block (copy the block name from sectionsSchema in
src/sections.schema.ts). Use only a value listed in the comment next to layout:. Make the same
change in the english, french, and arabic folders. Then run npm run astro-check and tell me
which page to open to check it.
```