# Stories (Blog)

## Stories (Blog)

**Files:** `src/content/blog/<language>/`, `src/content/author/<language>/` · **Skill level:** Beginner

Givo's blog is called **Stories** in the menus and on the page: reports from the field, appeal updates, and event recaps. It lives at `/blog/`, with one page per story, topic pages, an author box, related stories, a donate box after each story, and an RSS feed.

### What You Get
| Address | What it shows |
| --- | --- |
| `/blog/` | Topic links, a lead story, then dated cards, six per page (`blogPagination` in `[settings]` of `config.toml`; the lead story is not counted) |
| `/blog/<file-name>/` | The story: photo with caption, the text with a table of contents, the author box, share links, a donate box, and related stories |
| `/blog/category/<topic>/` | Every story in one topic |
| `/blog/tag/<tag>/` | Every story with one tag |
| `/blog/rss.xml` | The RSS feed, one per language (`/fr/blog/rss.xml`) |

Topic and tag pages with fewer than two stories are marked `noindex`, so search engines don't list thin pages.

### A Story File
Stories are `.mdx` files, so they can use shortcodes (see [Writing Content](/givo/customization/writing-content/)). The file name is the address.

```yaml
---
title: "How a village well is built, step by step"
description: "From the first survey to the water test: the six steps behind every well we fund."
image: "/images/photos/hero-water-pump.jpg" # no readable text
imageAlt: "A boy pumping water at a village hand pump"
imageCaption: "Dry north · A new hand pump in its first week · Photo: sample credit" # sample
location: "Dry north" # sample place: card meta "date · place · reading time"
date: 2026-08-30
author: "Samuel Okafor"
categories: ["How we work"]
tags: ["water", "transparency"]
cause: "clean-water-wells" # cause id in src/content/causes/
featured: false
draft: false
---
```

| Field | What it does |
| --- | --- |
| `image`, `imageAlt`, `imageCaption` | The cover photo, its description, and the caption line under it |
| `location` | Where the story happens, shown on the card. Without it, the card shows the first topic |
| `date`, `updated` | The publish date, and the date of the last real change (shown as "Updated") |
| `author` | A name that matches the `title` of a file in `src/content/author/<language>/` |
| `categories` | Topics. They make the topic links and pages |
| `tags` | Smaller labels with their own pages |
| `cause` | A cause file name. The story links to that cause at the end, and the donate box gives to it |
| `featured` | `true` makes it the lead story on `/blog/`. Without one, the newest story leads |

The sample stories, their places, and their figures are samples. Write about your own work, and delete the sample files you don't keep, in every language.

### Authors
An author is a file in `src/content/author/<language>/`. The story's `author` name is turned into a file name: "Peter Ansah" finds `peter-ansah.md`.

```yaml
---
title: "Peter Ansah"
role: "Communications officer"
# image: "" # optional photo; without it the note shows no avatar
description: "Writes our news and appeal updates, and edits the stories our teams send in from the field."
---
```

The author box under the story shows the name, role, and description. Without an `image`, it shows no avatar rather than a placeholder face.

### Topics
The topic links above the list come from `src/content/sections/<language>/blog-list-section.md`:

```yaml
filter:
  enable: true
  categories: ["Field stories", "News", "How we work", "Events recap"] # display order
```

A topic no story uses is hidden. A topic a story uses but that is missing here is added at the end. Each link goes to `/blog/category/<topic>/`, so the filter works without JavaScript. Topic names are translated in each language's stories, so write this list in each language too.

### The Stories Page And The Story Page
`src/content/blog/<language>/-index.md` holds the page header and the blocks for the list and for every story:

- `relatedPostsSection`: "More stories" under each story. Stories that share a topic come first, then the newest. `layout: "default"` shows dated cards; `news` shows the newest story large beside dated rows (the homepage uses `news`).
- `storyArticle.share`: the copy-link and email share links.
- The **Copy page** menu under the byline (copy the story as Markdown, or ask an AI assistant about it) is set in `[settings.pageActions]` in `config.toml`: see [AI Links & llms](/givo/features/ai-links-llms/).
- `storyArticle.donate`: the donate box after each story. `{cause}` is the story's cause; a story without a cause uses `descriptionGeneral`. Set `enable: false` to remove the box.
- `newsletterSection`: the newsletter signup at the end of the list and of every story. It sends to Mailchimp: see [Forms](/givo/customization/forms/).

### The Blog Folder Name
The folder and the address are `blog`, set by `blogFolder` in `[settings]` of `config.toml`. To use another word in the address, the comment there lists the three places to change with it: the folder in `src/content/`, the folder in `src/pages/[...lang]/`, and the collection in `src/content.config.ts`. Changing only the menu label to "News" or "Journal" is simpler: edit the menu item in every `src/config/menu.<language>.json`.

### Add A Story
<Steps>

1. Copy a story in `src/content/blog/english/` and rename it, for example `first-month-at-the-new-clinic.mdx`.

2. Change the frontmatter: title, description, photo and its alt text, caption, place, date, author, topics, tags, and cause. Write the text below it, starting headings at `##`.

3. Copy the file to every other language folder with the same name and translate it.

4. Run `npm run dev` and open `/blog/` and the new story.

</Steps>

<Aside type="tip">
  A story about one appeal is the best place to report on it: what the money
  bought, with photos and numbers. Set `cause` so readers can give to it from
  the end of the story.
</Aside>

### Do It With AI
```text
Write a story for my Givo site about [TOPIC] as an .mdx file in src/content/blog/english/. Match
the frontmatter of the other stories (title, description, image, imageAlt, imageCaption, location,
date, author, categories, tags, cause, featured, draft). Use the author [NAME] from
src/content/author/english/ and the cause [CAUSE FILE NAME]. Use ## headings and only the facts I
give you: [FACTS]. Keep it under [N] words. Then write the same story in every other language
folder with the same file name.
```