# Homepage

Live preview: <https://travio.themeupstudio.com/>

This guide explains how the homepage is built, which settings control each block, and how to customize each element.

### How homepage is composed

Homepage is rendered from `home.hbs` (route `/` with data: `page.home`) in this order:

1. Hero
2. Optional ribbons
3. Destinations section
4. Experiences section
5. Latest Articles section
6. Optional custom tag sections
7. Optional mid-page CTA (banner-alt) after the 2nd custom tag section
8. Final CTA (banner)

***

### Control map (Setting → Homepage Element)

| Setting / Content Source                                                                                                             | Controls (Homepage Element/Section)                                   |
| ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| <p><code>@custom.show\_home\_ribbons</code><br>Setting in Ghost Admin</p>                                                            | Turns ribbons block on/off                                            |
| <p><code>@custom.destinations</code><br>Setting in Ghost Admin</p>                                                                   | Destination tag pools for hero/nav/ribbons/destination cards/filters  |
| <p><code>@custom.experiences</code><br>Setting in Ghost Admin</p>                                                                    | Experience tag pools for hero badges/ribbons/experience cards/filters |
| <p><code>@custom.tag\_slugs\_to\_show\_on\_home</code><br>Setting in Ghost Admin</p>                                                 | Additional homepage tag sections                                      |
| <p><code>page.home</code> → title<br>Title of page with slug <code>home</code></p>                                                   | Hero headline                                                         |
| <p><code>page.home</code> → custom excerpt<br>Custom Excerpt of page with slug <code>home</code></p>                                 | Hero subtitle text                                                    |
| <p><code>page.home</code> → feature image<br>Feature Image of page with slug <code>home</code></p>                                   | Hero main image (highest priority)                                    |
| <p><code>@site.cover\_image</code><br>Publication cover image</p>                                                                    | Hero image fallback if Home page feature image is empty               |
| <p><code>page.home</code> → content images<br>Single images/Gallery images in content of page with slug <code>home</code></p>        | Hero slideshow sources                                                |
| <p><code>page.home</code> → featured toggle<br>Featured toggle of page with slug <code>home</code></p>                               | Shows/hides hero destination + experience CTA cards                   |
| <p><code>page.show\_title\_and\_feature\_image</code><br>Show title and feature image toggle of page with slug <code>home</code></p> | Controls hero newsletter form block rendering                         |
| posts (latest 15)                                                                                                                    | Latest Articles cards                                                 |
| <p><code>page.banner</code><br>Page with slug <code>banner</code></p>                                                                | Final homepage CTA section                                            |
| <p><code>page.banner-alt</code><br>Page with slug <code>banner-alt</code></p>                                                        | Optional alternate CTA shown after 2nd custom tag section             |

***

### Required/Recommended Content Setup

For a complete homepage, create and maintain:

1. A page with slug `home` (used by route data).
2. Destination tags and Experience tags.
3. Theme settings with correct slug lists for `destinations` and `experiences`.
4. Optional page with slug `banner` for final CTA.
5. Optional page with slug `banner-alt` for mid-page CTA.
6. Optional pages with slugs `destinations` and `experiences` (used by hero mini-CTA cards when Home page is featured).

***

### Block-by-Block Customization

#### 1. Hero Section

**1.1 Headline and Subtext**

* Source: Home page Title + Custom Excerpt.
* Action: Edit the home page content in Ghost Admin.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FNBjep5aTo4MWAS46Y0zw%2Fimage.png?alt=media&#x26;token=8d3196c6-1e10-4f3f-9e74-3a39f1334038" alt=""><figcaption><p>Homepage Hero elements</p></figcaption></figure></div>

**1.2 Hero Image Priority**

1. `home` page feature image.
2. Site cover image (Brand settings) if Home feature image is missing.
3. No media layout if both are missing.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2Fr3IbTJj47cMfr81Nc0zU%2Fimage.png?alt=media&#x26;token=da09a626-b207-4f4b-ab66-20113b1f195d" alt=""><figcaption><p>Homepage feature image</p></figcaption></figure></div>

**1.3 Hero Slideshow**

* Source: `<img>` tags inside `home` page content.
* Behavior: Theme extracts content images and rotates them as background layers over the hero image.
* Tip: Add 3–6 high-quality images in Home page content for smoother visual rotation.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2Fk5voUOQK3zObvwafXWp9%2Fimage.png?alt=media&#x26;token=b98fc67a-6315-46fb-9944-d50b8a46c086" alt=""><figcaption><p>Homepage hero image slideshow</p></figcaption></figure></div>

**1.4 Hero Floating Experience Badges**

* Source: tags listed in `@custom.experiences` (up to 12 queried).
* Behavior: Randomized badges with parallax/drag interaction.
* If tag has no feature image, initials placeholder is used.
* If no experiences are configured, this layer is not rendered.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FZlUe2JsE33FNapOLFu5j%2Fimage.png?alt=media&#x26;token=5e597b50-f188-4adb-902a-f40f1ea08c1a" alt=""><figcaption><p>Homepage floating badges. These are randomised and are randomly selected.</p></figcaption></figure></div>

**1.5 Hero Newsletter Form**

* Rendered under heading/subtext only when page option check passes (`@page.show_title_and_feature_image` in template logic).
* Uses Ghost Members subscribe flow (`data-members-form="subscribe"`).
* Includes all newsletters as hidden inputs.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2Fz54wwiLHhy6bb5oOzkKc%2Fimage.png?alt=media&#x26;token=a0bd3934-f9a4-4a6f-a986-e088d248196d" alt=""><figcaption><p>Hide/show Subscribe form in homepage hero</p></figcaption></figure></div>

**1.6 Hero Destination/Experience Mini-CTAs**

* Only rendered if `home` page is marked **Featured**.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FcXlT4oNIgzsAHgPPNHNC%2Fimage.png?alt=media&#x26;token=0aaed3a7-d9aa-4737-8be4-8b0285d927e4" alt=""><figcaption><p>Hide/show homepage hero CTA buttons</p></figcaption></figure></div>

* Pulls content from pages with slugs:
  * `destinations`
  * `experiences`
* Card content mapping:
  * Card title = page title
  * Card description = page excerpt
  * Card image = page feature image
  * Link = page URL

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FvKyUnVQWysq8mehRovfd%2Fimage.png?alt=media&#x26;token=77ff512d-18ef-42b0-bec4-843813e0b153" alt=""><figcaption><p>Homepage CTA buttons' content</p></figcaption></figure></div>

**1.7 Ribbons Section**

* Toggle:
  * Controlled by `@custom.show_home_ribbons` setting in Ghost Admin.
  * If false, entire ribbons block is skipped.
* Data Source:
  * Uses tags from:
    * Both `destinations` + `experiences` if both are set
    * Only one set if only one is configured
  * Ribbon items are shuffled client-side for variation.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FFwr64Y10FCxMhkj2PIvv%2Fimage.png?alt=media&#x26;token=37af1135-0c1b-47e6-9614-3515b97e3bce" alt=""><figcaption><p>Homepage hero ribbon</p></figcaption></figure></div>

***

#### 2. Destinations Section

**2.1 Data Source**

* Tag slugs from `@custom.destinations`.
* Max 10 tags shown.
* Card shows:
  * Tag feature image or initials fallback
  * Tag name
  * Post count (`count.posts`)

**2.2 Link Target**

* Section header “View all destinations” goes to `/destinations/`.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FZC16hOfl6RGpkdA93qaC%2Fimage.png?alt=media&#x26;token=c63ad191-27c1-4708-ba2b-d920e3244aa6" alt=""><figcaption><p>Homepage destinations section</p></figcaption></figure></div>

***

#### 3. Experiences Section

**3.1 Data Source**

* Tag slugs from `@custom.experiences`.
* Max 12 tags shown.
* Card shows:
  * Tag feature image or initials fallback
  * Tag name
  * Post count badge

**3.2 Link Target**

* Section header “View all experiences” goes to `/experiences/`.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2F8dAsYMWZyyYSbQkim9Y6%2Fimage.png?alt=media&#x26;token=bf4da8a4-c66a-4dc7-a7ed-cf1199e51d19" alt=""><figcaption><p>Homepage experiences section</p></figcaption></figure></div>

***

#### 4. Latest Articles Section

**4.1 Data Source**

* Latest 15 posts (`published_at desc`).
* Mixed layout:
  * 3 large cards
  * 12 smaller cards in grouped columns

**4.2 What affects these cards**

* Post featured image (or placeholder fallback)
* Featured flag badge
* Membership access state badge
* Tags and destination chips
* Author profile images
* Reading time/date

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2F7DlwDjLMaraYFuyuC5Vk%2Fimage.png?alt=media&#x26;token=cfc6ab00-4ab5-4d69-b3bb-7c5dab98aaff" alt=""><figcaption><p>Homepage latest articles section</p></figcaption></figure></div>

***

#### 5. Custom Tag Sections

**5.1 Data Source**

* Theme setting: comma-separated tag slugs in `tag_slugs_to_show_on_home` setting.
* For each tag:
  * Header uses tag name + link to tag archive
  * Pulls latest 6 posts for that tag

**5.2 Mid-page CTA insertion rule**

* After the 2nd custom tag section, theme inserts `section-cta-alt` automatically.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FEFcOJesTcQ3XBaJRI1xy%2Fimage.png?alt=media&#x26;token=72106134-e49f-4522-9507-4c0a629695b1" alt=""><figcaption><p>Homepage tags section</p></figcaption></figure></div>

***

#### 6. CTAs

**6.1 Final CTA at bottom**

* Page slug required: `banner`
* Mapping:
  * Title → CTA heading
  * Content → CTA body
  * Feature image → visual background/media
  * Excerpt → button URL
  * Feature image caption → button label

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FpSoxkjSlBuc9cTAzqDRx%2Fimage.png?alt=media&#x26;token=d363fb2c-279a-42b2-bc31-b424c6fc4d55" alt=""><figcaption><p>Homepage Final CTA section</p></figcaption></figure></div>

**6.2 CTA after 2nd Tag Section**

* Page slug required: `banner-alt`
* Similar mapping as of Final CTA at bottom.
* If page has tags, they render as interactive floating badges around the CTA. Maximum of 4.

<div data-with-frame="true"><figure><img src="https://2866984845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0cwYRwvCWzidCNRA02jZ%2Fuploads%2FMqpsLpRicMJ4FoUsthht%2Fimage.png?alt=media&#x26;token=3aa0e30b-6f0f-4f8f-83aa-e4368b4b2a16" alt=""><figcaption><p>Homepage CTA section after 2nd tag section</p></figcaption></figure></div>

***

### Settings Checklist for Homepage

Set these in Customize → Theme:

* `destinations`: valid destination tag slugs
* `experiences`: valid experience tag slugs
* `show_home_ribbons`: true/false
* `tag_slugs_to_show_on_home`: optional additional tag slugs

Set these in Customize → Brand:

* Site cover image (hero fallback)
* Accent color (affects generated accent shades)

***

### Common Pitfalls

1. Home looks incomplete (or shows 404 error) because `home` page slug is missing.
2. Destination/experience sections empty because slug lists don’t match real tag slugs.
3. Hero mini-CTA cards missing because `home` page is not marked **Featured**, or `destinations`/`experiences` pages don’t exist.
4. CTA button not working because `banner`/`banner-alt` page excerpt is empty (excerpt is used as button URL).
5. Hero slideshow not rotating because Home page content has no images.