Adding Media and Resources

In this lesson, you will learn how to enhance your course by adding various types of media and resources. This includes images, videos, and downloadable files that can help illustrate concepts and provide additional value to your learners.

Course Media Folder

The easiest way to add media to your course is using a _media/ folder at your course root. This keeps all your course media organized in one place.

Setting up the `_media/` folder

Create a _media/ folder in your course directory:

content/en/courses/your-course-name/
├── _index.md
├── _media/
│   └── index.md
├── 10-getting-started/
└── ...

Create an index.md file inside _media/ with this frontmatter:
```
---
title: "Course Media"
build:
  render: never
  list: never
  publishResources: true
---
```
Why is this file needed? Hugo treats a folder with an index.md as a leaf bundle — a content unit that owns its resources (images, PDFs, etc.). The build settings tell Hugo to not render a page for this bundle (render: never), not list it alongside your lessons (list: never), but still publish the files inside it so they are available via URL (publishResources: true). Without this file, Hugo would ignore the media files entirely.

Drop your media files in the _media/ folder. You can place files directly in the root or optionally organize them into subfolders (e.g. by lesson name):

_media/
├── index.md
├── course-thumbnail.png          ← shared files at root level
├── introduction/                  ← optional subfolder per lesson
│   ├── image1.png
│   └── image2.png
├── getting-started/
│   ├── image1.png
│   ├── image2.png
│   └── cheat-sheet.pdf
└── advanced-topics/
    └── image1.png

Subfolders are entirely optional — you can keep all files flat in _media/ if you prefer. Subfolders are helpful when multiple lessons use files with the same name (e.g. image1.png).

Using media from `_media/`

Once set up, reference media using filenames or relative paths:

Files in root of _media/:

![Thumbnail](course-thumbnail.png)
image: course-thumbnail.png

Files in lesson subfolders:

![First image](introduction/image1.png)
![Second image](getting-started/image2.png)
[Download cheat sheet](getting-started/cheat-sheet.pdf)

The system automatically resolves these paths from your _media/ folder.

Adding Videos

Videos can be particularly useful for demonstrating processes or explaining complex concepts. Use external video hosting platforms for best performance:

Specify the video source in the front matter of your lesson. Recommended options:

---
video:
  youtube: dQw4w9WgXcQ                # YouTube video ID (recommended)
  # vimeo: 123456789                  # Vimeo video ID
  # tibav: 42061                      # TIB AV-Portal ID
  # external: https://.../video.mp4   # External video URL
  # embed: "<iframe ...></iframe>"    # Any embed code
---

The video will automatically be displayed at the top of your lesson page.

Important: Use external video platforms (YouTube, Vimeo, TIB AV-Portal) instead of storing video files in the repository.

Captions and alternatives

A video with speech or meaningful sound needs captions. If the picture shows something the narration does not say, learners who cannot see it need that information in text or audio. Upload a proofread caption file in the provider’s player; the TIB AV-Portal accepts WebVTT and SRT. Automatic captions are a starting point, not a result.

For a video file that another server hosts (external), add WebVTT caption tracks to the front matter. The video file itself is never added to this repository. The caption files are small text files: put them in static/resources/courses/your-course-name/ and use the root-relative path as src.

video:
  external: https://media.example-university.de/courses/intro.mp4
  tracks:
    - src: /resources/courses/your-course-name/intro.en.vtt
      srclang: en
      label: English
      default: true

Each track needs src and srclang. kind is captions unless you set subtitles, descriptions or chapters, and only one track per kind may be default. Provider embeds ignore tracks. A caption file on another server is loaded by browsers only if that server sends CORS headers and the video element has a crossorigin attribute, which the template does not set, so keep the files in static/.

Keep the lesson text a complete route through the topic. Learners who decline the third-party player, cannot use video or need more than captions still get everything. A transcript alone does not replace captions, and it does not replace audio description when important content is only visible.

Adding Downloadable Resources

You can provide additional resources for your learners to download, such as PDF guides, code examples, or practice files.

Place files in your _media/ folder (optionally in a lesson subfolder)

Link with the relative path:

[Download practice files](getting-started/practice-files.zip)
[Download cheat sheet](getting-started/cheat-sheet.pdf)

Best Practices for Using Media

Use relevant media: Ensure that all media included directly supports your lesson content.
Optimize file sizes: Large files can slow down page load times. Compress images and videos wherever possible.
Provide alternative text: Always include descriptive alternative text for images to improve accessibility.
Balanced use of media: While media can enhance learning, avoid overuse. Find a balance between text and media content.

Exercise: Enhance Your Lesson with Media

Add at least one image to the lesson you wrote in the previous exercise.
If applicable, include a short video demonstration in your lesson.
Create a simple downloadable resource (e.g., a PDF cheat sheet) and add a link to it in your lesson.

In the next lesson, we will cover how to preview and test your course locally before submitting it.