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

Writing Content

Skill level: Beginner · Used in: stories, cause and event pages, legal and text pages

Every content file has two parts: the frontmatter between the two --- lines at the top (settings and short texts, written in YAML), and the body below it (longer text, written in Markdown). Files that end in .mdx can also use shortcodes: small components such as callouts, checklists, and buttons.

---
title: "Donation and refund policy" # frontmatter: YAML
description: "How we use your gift, and how to ask for a refund."
date: 2026-09-01
draft: false
---
## Restricted gifts ← body: Markdown
A gift made to one cause is spent on that cause.

In Givo, stories (src/content/blog/) and the /components/ page are .mdx files. Causes, events, and the legal and text pages are .md files, so they can use Markdown and the organization tokens below, but not shortcodes.

Frontmatter Basics

  • Keep the keys exactly as they are; change only the values.
  • Put text in double quotes: title: "Clean water wells". Write a quote inside text as \", or use single quotes around the text.
  • Dates are YYYY-MM-DD: deadline: 2027-04-30. Event times add the time: start: 2026-11-15T09:00:00.
  • Amounts are plain numbers with no currency sign and no commas: goal: 75000.
  • Lists start each item with - (or use ["a", "b"]), and nested keys are indented with two spaces. Copy the indentation of the item above.
  • src/content/_file_format.md lists the common page fields with a comment on each.

File Formats explains YAML, Markdown, and TOML for beginners.

The# sampleComments

Text after # on a YAML line is a comment: the site ignores it. Givo uses comments in two ways:

  • To list options. layout: "grid" # grid | featured | list tells you the allowed values.

  • To mark sample facts. Values you must replace before launch end with # sample:

    goal: 75000 # sample
    raised: 48900 # sample

Search the project for # sample to find every sample goal, amount, donor count, date, quote, registration number, and promise. Replace the value and delete the comment once the fact is yours. If you can’t confirm a figure, remove the item instead of keeping an invented number.

Markdown Basics

## A section heading
### A smaller heading
Plain text. **Bold**, _italic_, and [a link](/causes/).
- A list item
- Another item
1. A numbered step
2. Another step
> A quote from a volunteer.
| Item | Cost |
| ------------- | ---- |
| School kit | $25 |
  • Start headings at ##: the page title is already the # heading. Stories get a table of contents from their headings ([settings.markup.tableOfContents] in config.toml).
  • Links to other sites open in a new tab automatically.
  • Code blocks with three backticks get syntax colours and a copy button; [settings.markup.codeBlocks] theme is auto (follows light and dark mode) or dark.

Heading Sizes

Add a class in square brackets at the end of a heading to set its size without changing its level:

## What one backpack holds [.h4]
### Before the packing day [.h5]

The heading stays an h2 or h3 for search engines and screen readers, but is drawn at the h4 or h5 size.

Organization Details In Text

In .md files, these tokens are replaced with your details from [organization] in config.toml, so you never type them twice:

TokenBecomes
{name}The organization name
{phone}The phone number as shown (phoneDisplay)
{email}The email address
{address}The address
{hours}The office hours
{registration}The registration number
To change a monthly gift, email {email} or call {phone}.

In .mdx files, { starts code, so the tokens don’t work there: write the details out, or put the text in a .md file. Several section fields (form messages, the donate fine print, the impact page facts) also accept them, as noted in their comments. See Organization Info.

Images In The Body

  • Frontmatter image fields such as image read src/assets/images/: "/images/photos/cause-water-tap.jpg" is src/assets/images/photos/cause-water-tap.jpg, and it is optimized when the site is built.
  • In the body, the ImageList shortcode below takes the same kind of path.
  • A plain Markdown image with a path that starts with / points to the public/ folder and is served as it is: ![Alt text](/images/gallery/1.jpg) is public/images/gallery/1.jpg.

See Icons & Images.

Shortcodes

These shortcodes work in every .mdx file without an import. The list is src/lib/shortcodes.ts, and the /components/ page shows each one with its code (source: src/content/pages/english/components.mdx).

Callout: a tip or a warning pulled out of the text. type is note (default), tip, warning, or danger. Without a title, the type name is shown. The older name <Notice> still works.

<Callout type="tip" title="Label the boxes before you fill them">
One label per box saves an hour at the end of the packing day.
</Callout>

Steps: numbers the headings inside it. Each ## or ### heading starts a step.

<Steps>
### Survey the site
A geologist marks the two or three best points.
### Drill and test
The water is tested by an independent lab before handover.
</Steps>

ListCheck: turns a Markdown list into a checklist. columns={2} shows two columns on wider screens.

<ListCheck columns={2}>
- **Backpack**: one per child, with a name tag.
- **Notebooks**: four, ruled.
</ListCheck>

Button: a theme button, with the same options as buttons in content files (label, url, variant: fill, accent, gold, soft, outline, link, fill-white, or text).

<Button label="Donate" url="/donate/" />
<Button variant="outline" label="Contact us" url="/contact/" />

Accordion: a question that opens. Rows with the same group close each other; expanded="true" opens one on load.

<Accordion label="Do I need experience to help on a packing day?" group="packing" expanded="true">
No. A team leader shows you what to do when you arrive.
</Accordion>

Tabs: content in tabs.

<Tabs>
<Tab name="Primary">What a primary school kit holds.</Tab>
<Tab name="Secondary">What a secondary school kit holds.</Tab>
</Tabs>

ImageList and ImageItem: photos in a grid with an optional caption. width="1/2" or "1/3" sets the share of the row; videoSrc adds a play button.

<ImageList>
<ImageItem imageSrc="/images/photos/event-packing-day.jpg" imageAlt="Volunteers handing sacks across a table of supplies" caption="The packing tables at nine in the morning." />
</ImageList>

VideoInline: a video in the text. provider is youtube (the video id), vimeo, or html5 (a file in public/videos/). YouTube videos use the privacy-friendly youtube-nocookie.com player.

<VideoInline src="rFVpSwgCkCo" provider="youtube" />

Drafts

draft: true in the frontmatter keeps a page or entry out of the built site, the lists, the sitemap, and llms.txt. It still shows in npm run dev, so you can keep working on it. A draft: true in a collection’s -index.md hides the whole collection.

updated: 2026-10-01 marks the last meaningful edit: stories show it as “Updated”, and it is used in structured data and the sitemap.

Do It With AI

Rewrite the body of src/content/pages/english/donation-policy.md for my organization from these
facts: [FACTS]. Keep the frontmatter, use ## headings, write {name}, {email}, and {phone} instead
of typing my details, and invent nothing. Then update the same file in every other language
folder of src/content/pages/.
Type something to search...