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). 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 textimageAlt: "A boy pumping water at a village hand pump"imageCaption: "Dry north · A new hand pump in its first week · Photo: sample credit" # samplelocation: "Dry north" # sample place: card meta "date · place · reading time"date: 2026-08-30author: "Samuel Okafor"categories: ["How we work"]tags: ["water", "transparency"]cause: "clean-water-wells" # cause id in src/content/causes/featured: falsedraft: 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.
---title: "Peter Ansah"role: "Communications officer"# image: "" # optional photo; without it the note shows no avatardescription: "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 orderA 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;newsshows the newest story large beside dated rows (the homepage usesnews).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]inconfig.toml: see AI Links & llms. storyArticle.donate: the donate box after each story.{cause}is the story’s cause; a story without a cause usesdescriptionGeneral. Setenable: falseto 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
-
Copy a story in
src/content/blog/english/and rename it, for examplefirst-month-at-the-new-clinic.mdx. -
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
##. -
Copy the file to every other language folder with the same name and translate it.
-
Run
npm run devand 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/. Matchthe frontmatter of the other stories (title, description, image, imageAlt, imageCaption, location,date, author, categories, tags, cause, featured, draft). Use the author [NAME] fromsrc/content/author/english/ and the cause [CAUSE FILE NAME]. Use ## headings and only the facts Igive you: [FACTS]. Keep it under [N] words. Then write the same story in every other languagefolder with the same file name.