# Events & Add To Calendar

## Events & Add To Calendar

**Files:** `src/content/events/<language>/` · **Skill level:** Beginner

Charity runs, dinners, packing days, and online sessions. Each event is one Markdown file. The theme lists upcoming events by month on `/events/`, gives every event its own page with a register button, and builds an add-to-calendar file for each one.

### Where Events Appear
| Where | What it shows |
| --- | --- |
| `/events/` | Upcoming events grouped by month, category filters, and a list of past events. Settings in `src/content/events/<language>/-index.md` |
| `/events/<file-name>/` | The event page: photo, date and time, place with a map link, ticket price, places, register button, add to calendar, share links, and related events |
| `/events/<file-name>.ics` | The calendar file of the event |
| Events section | "Upcoming events" on the homepage and `/home-community/`, from `src/content/sections/<language>/events-section.md` |

### An Event File
The file name is the address: `riverside-charity-run.md` becomes `/events/riverside-charity-run/`.

```yaml
---
title: "Riverside charity run"
description: "A 5 km and 10 km run along the river. Every entry fee buys school supplies for one child."
image: "/images/photos/event-charity-run.jpg"
imageAlt: "Runners crossing a bridge in the early morning"
imageCaption: "Riverside park · The 10 km field crossing the north bridge last year · Photo: sample credit" # sample
category: "fundraiser" # id from `categories:` in -index.md
start: 2026-11-15T09:00:00 # sample
end: 2026-11-15T13:00:00
timezone: "" # empty: [organization] timezone in config.toml
venue: "Riverside park, north gate" # sample
address: "River Road, Springfield" # sample
online: false
capacity: 600 # sample
price: 25 # sample; 0 = free
registerUrl: "" # empty: the register button goes to /contact/?topic=events
featured: true
draft: false
---

What to expect on the day, in Markdown.
```

| Field | What it does |
| --- | --- |
| `category` | An `id` from `categories` in the events `-index.md` (`fundraiser`, `volunteer`, `online` in the sample) |
| `start`, `end` | Date and time, written as `YYYY-MM-DDTHH:MM:SS`: the time on the clock where the event happens. Without `end`, the event counts as one hour long |
| `timezone` | The time zone of `start` and `end`, such as `"Europe/Paris"`. Empty uses `timezone` in `[organization]` of `config.toml` |
| `venue`, `address` | The place and its street address. The address is shown under the venue, opens a map search on OpenStreetMap, and goes into the calendar file |
| `online` | `true` for an online event: it shows "Online" instead of a place, with the note "We email the link the day before." |
| `capacity` | Number of places, shown as "600 places". Remove it if places are not limited |
| `price` | Ticket price as a plain number in the donate currency. `0` or no value shows "Free" |
| `registerUrl` | Your ticketing or sign-up page. Empty sends visitors to the contact form with the "An event" topic chosen (`/contact/?topic=events`) |
| `featured` | Lets a section show only featured events (`featuredOnly: true`) |

<Aside type="caution" title="The sample events are samples">
  The dates, places, capacities, and prices are marked `# sample`. Replace them
  with your own events, or delete the sample files, before you launch.
</Aside>

### Upcoming And Past Events
An event moves from "upcoming" to "past" once its end time is over. Like the days left on causes, this is decided **when the site is built**. Rebuild the site once a day (a scheduled deploy) so a finished event leaves the upcoming list. See [Deployment](/givo/deployment/).

On a past event's page, the register button is replaced by "This event has ended" (`endedLabel` in `event-hero-section.md`). The page and its calendar file stay online, so old links keep working. `/events/` lists past events in a closed list under the upcoming ones (`past` in `event-listing-section.md`, with `limit: 12`).

### Add To Calendar
Every event page has an **Add to calendar** box with two links:

- **Apple, Outlook (.ics)**: downloads `/events/<file-name>.ics` (`/fr/events/<file-name>.ics` in French). Calendar apps open it and add the event.
- **Google Calendar**: opens Google Calendar with the event filled in.

The theme reads `start` and `end` in the event's time zone and writes the real moment into the file, so each person's calendar shows the event at the right time in their own zone. The file also holds the title, the description, the place and address (or "Online"), your organization's email as organizer, and a link back to the event page. That link is built from `baseUrl` in `[site]` of `config.toml`, so set your domain before you publish events.

The labels are in the `calendar` block of `src/content/sections/<language>/event-hero-section.md`. Set `enable: false` there to hide the box.

### Event Page Text
`src/content/sections/<language>/event-hero-section.md` holds the words around every event: the register button label, "Online", "This event has ended", `{count} places`, the share links, the details labels (Date, Time, Where, Ticket, Places, Organizer), the calendar box, and the related events below. The organizer is your organization name from `[organization]`. An event file can change any of these for itself with an `eventHeroSection:` block.

### The Events Page
`src/content/events/<language>/-index.md` holds the page header, the categories, and the closing call to action:

```yaml
categories:
  - id: "fundraiser"
    label: "Fundraiser"
  - id: "volunteer"
    label: "Volunteer day"
  - id: "online"
    label: "Online"
```

The filter buttons follow this order. `/events/?category=online` opens the page with one category selected. Keep the ids the same in every language and translate the labels. Without JavaScript, every event shows.

The list itself is `src/content/sections/<language>/event-listing-section.md`: the title, `filter: true` for the category buttons, the message shown when a category is empty, and the past events list.

### The Events Section
```yaml
# src/content/sections/english/events-section.md
title: "Upcoming events"
limit: 3 # upcoming events shown; 0 = every upcoming event
featuredOnly: false # only events with featured: true
link:
  enable: true
  label: "All events"
  url: "/events/"
options:
  layout: "list" # list | agenda
```

`list` shows dated rows with the time, place, and a register link. `agenda` groups events by month in compact rows with no photos. A page changes these with an `eventsSection:` block.

### Search Engines
Each event page carries `Event` structured data: the name, dates, place or online link, price, and organizer. Search engines can show it in event listings. Keep dates and prices true; see [SEO & AI Visibility](/givo/customization/seo-ai-visibility/).

### Add An Event
<Steps>

1. Copy an event file in `src/content/events/english/` and rename it, for example `autumn-quiz-night.md`.

2. Set the title, description, photo, category, `start`, `end`, and either `venue` and `address` or `online: true`. Add `registerUrl`, `capacity`, and `price` if they apply. Write the details below the frontmatter.

3. Copy the file to every other language folder with the same name. Translate the text and keep the dates and numbers.

4. Run `npm run dev` and open `/events/`, the new page, and its **Add to calendar** links.

</Steps>

### Do It With AI
```text
Add an event to my Givo site: [TITLE], on [DATE] from [START TIME] to [END TIME] ([TIME ZONE] or
my organization's time zone), at [VENUE, ADDRESS | online], [PRICE or free], [CAPACITY or no
limit], register at [URL or our contact form]. Copy an existing file in src/content/events/english/,
set every field, and write a short description from these facts only: [FACTS]. Create the same
file in every other language folder with the text translated and the dates unchanged.
```