# Writing Content (Markdown, MDX & Shortcodes)

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

```md
---
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](/givo/beginner/file-formats/) explains YAML, Markdown, and TOML for beginners.

### The `# sample` Comments
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`:

  ```yaml
  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
```md
## 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:

```md
## What one backpack holds
### Before the packing day
```

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:

| Token | Becomes |
| --- | --- |
| `{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 |

```md
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](/givo/customization/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](/givo/customization/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.

```mdx
<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.

```mdx
<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.

```mdx
<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`).

```mdx
<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.

```mdx
<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.

```mdx
<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.

```mdx
<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.

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

<Aside type="caution" title="MDX is stricter than Markdown">
  In `.mdx` files, `{`, `}`, and `<` have a special meaning. If a build fails
  on a line with one of them in normal text, put the text in backticks or
  write `\{` and `&lt;`. Plain `.md` files don't have this rule, but can't use
  shortcodes.
</Aside>

### 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
```text
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/.
```