Skip to content
New: Customize your theme with an AI assistant. Read the guide

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

AddressWhat 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.xmlThe 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). The file name is the address.

---
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
---
FieldWhat it does
image, imageAlt, imageCaptionThe cover photo, its description, and the caption line under it
locationWhere the story happens, shown on the card. Without it, the card shows the first topic
date, updatedThe publish date, and the date of the last real change (shown as “Updated”)
authorA name that matches the title of a file in src/content/author/<language>/
categoriesTopics. They make the topic links and pages
tagsSmaller labels with their own pages
causeA cause file name. The story links to that cause at the end, and the donate box gives to it
featuredtrue 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.

---
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:

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.
  • 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.

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

  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.

Do It With AI

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.
Type something to search...