Skip to content

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 image

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

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

markdown
![Alt text describing the image](/images/investigations/het-leven-van-een-varken/cramped-pens.jpg)

You can also place images inline within paragraphs:

markdown
The pigs were kept in small pens.
![Pigs in cramped conditions](/images/investigations/het-leven-van-een-varken/cramped-pens.jpg)
The conditions were clearly unacceptable.

Adding New Images ​

Step 1: Prepare the image ​

Before adding an image:

  • Format: Use .jpg or .webp for photos, .png for 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 image

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

yaml
# 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: Foto

Tips 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 ​

ContextRecommended widthAspect ratio
Investigation cover1200-1600px16:9 or 3:2
Chapter header1200-1600px16:9 or 3:2
Inline content800-1200pxAny
Animal icons200-400px1: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.

yaml
# 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 language

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

  1. On the website — shown as the page header image
  2. 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 ​

  1. Check the path: Must start with /images/ and be exact (case-sensitive)
  2. Check the file exists: Look in public/images/investigations/<slug>/ (or relevant subdirectory)
  3. Check the extension: Must match exactly (.jpg vs .jpeg vs .png)
  4. Clear browser cache: Hard refresh with Ctrl+Shift+R

Image loads slowly ​

  • Compress it with Squoosh or TinyPNG
  • Consider converting to WebP format
  • Reduce dimensions if the image is larger than needed