Working with Images
Images are an essential part of the Ongehoord website — every investigation, chapter, and location needs visual content. This page explains where images live, how to add them, and best practices.
Where Images Are Stored
All images are stored in the public/images/ folder:
public/images/
├── investigations/<slug>/ # Per-investigation photos (hero.jpg + descriptive names)
├── pages/<page>/ # Page-level images (contact, doneren, onderzoek, over-ons)
├── shared/ # Photos used by multiple investigations
├── ui/ # Logos, animal markers, default video thumbnail
├── _unused/ # Files staged for deletion in a follow-up commit
└── og-image.png # Default social sharing imageEach investigation has its own folder under public/images/investigations/<slug>/. The article-level cover image lives at hero.<ext>; chapter heroes and inline images use descriptive kebab-case names derived from their content.
Referencing Images
In frontmatter
Use an absolute path starting with /images/:
---
image:
src: /images/investigations/het-leven-van-een-varken/hero.jpg
alt: Het leven van een varken
---WARNING
Always start the path with /images/ — not ./images/ or ../images/. The leading slash means "from the root of the website".
In Markdown content
Use standard Markdown image syntax:
You can also place images inline within paragraphs:
The pigs were kept in small pens.

The conditions were clearly unacceptable.Adding New Images
Step 1: Prepare the image
Before adding an image:
- Format: Use
.jpgor.webpfor photos,.pngfor graphics with transparency - Size: Aim for 1200-1600px wide for header/cover images, 800-1200px for inline content images
- File size: Keep under 500KB if possible — compress with TinyPNG or Squoosh
- Aspect ratio: Cover images should be roughly 16:9 or 3:2
Step 2: Name the file
Use lowercase, descriptive names with hyphens:
# Good
varken-in-kraamkooi.jpg
aalten-gendringseweg-stal.jpg
hero.jpg # The article-level cover imageAvoid generic camera filenames (IMG_1234.jpg), UUIDs, or content hashes — descriptive names are required for SEO.
Step 3: Place the file
Copy the image to public/images/investigations/<slug>/, where <slug> matches the investigation's content folder (without the numeric prefix). For example, the cover image for content/nl/onderzoek/2.het-leven-van-een-varken/index.md lives at public/images/investigations/het-leven-van-een-varken/hero.jpg.
Step 4: Reference it
Use the path /images/investigations/<slug>/your-filename.jpg in your frontmatter or Markdown.
Image Best Practices
Always write alt text
Alt text is essential for accessibility. It describes the image for screen readers and appears when images fail to load.
# Good alt text - descriptive
image:
src: /images/investigations/het-leven-van-een-varken/cramped-pens.jpg
alt: Varkens dicht op elkaar in een kleine stal zonder daglicht
# Bad alt text - vague
image:
src: /images/investigations/het-leven-van-een-varken/cramped-pens.jpg
alt: FotoTips for writing alt text:
- Describe what's in the image, not what you want people to feel
- Be concise but specific (5-15 words)
- Don't start with "Image of..." or "Photo of..." — screen readers already announce it as an image
- For decorative images, use an empty alt:
alt: ""
Image dimensions by context
| Context | Recommended width | Aspect ratio |
|---|---|---|
| Investigation cover | 1200-1600px | 16:9 or 3:2 |
| Chapter header | 1200-1600px | 16:9 or 3:2 |
| Inline content | 800-1200px | Any |
| Animal icons | 200-400px | 1:1 (square) |
Shared images across languages
Images are in public/ (not in content/), so they are shared across both languages. You only need to add an image once — both the Dutch and English versions reference the same file path.
# Both nl/ and en/ versions use the same image:
image:
src: /images/investigations/het-leven-van-een-varken/hero.jpg
alt: Het leven van een varken # Only the alt text differs per languageSocial Sharing Images (OG Images)
When someone shares a page on social media (Facebook, Twitter, WhatsApp), the cover image from the frontmatter is used as the preview image. The image.src field in your frontmatter serves double duty:
- On the website — shown as the page header image
- On social media — shown as the link preview image
For best results on social media, cover images should be:
- At least 1200x630px (ideal for Facebook/Twitter)
- Important content centered (edges may be cropped on some platforms)
Troubleshooting
Image not showing up
- Check the path: Must start with
/images/and be exact (case-sensitive) - Check the file exists: Look in
public/images/investigations/<slug>/(or relevant subdirectory) - Check the extension: Must match exactly (
.jpgvs.jpegvs.png) - Clear browser cache: Hard refresh with
Ctrl+Shift+R