README.md

@@ -11,6 +11,21 @@ docker compose up -d
 
 to spin up a local environment. Preview available on <http://localhost:8000>.
 
+## Embedding Videos
+
+Put video files in `docs/assets/videos/` and embed them with Markdown image
+syntax, using a path relative to the page:
+
+```markdown
+![Introduction to OpenEM](./assets/videos/OpenEM_compressed.mp4)
+```
+
+The [`hooks/video.py`](hooks/video.py) hook turns any image that points at an
+`.mp4`, `.webm` or `.ogv` file into an HTML5 `<video>` player with a download
+link. The description in square brackets becomes the player's accessible label.
+Prefer this over writing `<video>` tags by hand: the strict build fails if the
+file is missing, and MkDocs corrects the path for each page.
+
 ## Style Guide
 
 Pull requests enforce [markdownlint](https://github.com/DavidAnson/markdownlint) checks.

docs/index.md

@@ -13,6 +13,12 @@ principles](https://force11.org/info/the-fair-data-principles/).
 - See published datasets at [doi.psi.ch](https://doi.psi.ch)
 - Read the [Ingestor Manual](scicat/ingestorManual.md) to get started adding your datasets
 
+## Introductory Video
+
+![Introduction to SciCat at PSI](assets/videos/SciCat_Introduction_PSI_compressed.mp4)
+
+## Announcements
+
 !!! info "January 2026 Upgrade"
     In January 2026 the catalog was upgraded to use SciCat v4. This was a major upgrade
     that required client changes. For details, please refer to the [upgrade

docs/openem/user/introduction.md

@@ -11,6 +11,10 @@ The instructions cover uploading, transferring and downloading data with OpenEM.
 If you have questions or encounter a problem, contact the person listed under
 [Support](../../support.md) for your institution.
 
+## Introductory Video
+
+![Introduction to OpenEM](../../assets/videos/OpenEM_compressed.mp4)
+
 ## OpenEM from the user's point of view
 
 The entry point for users is the [PSI SciCat instance](https://discovery.psi.ch).

hooks/video.py

@@ -0,0 +1,37 @@
+"""Render Markdown images that point at video files as HTML5 <video> elements.
+
+Usage: ![Description of the video](../assets/videos/example.mp4)
+
+Using image syntax (rather than a raw <video> tag) means MkDocs validates that
+the file exists and rewrites the path relative to the page, like any other
+image.
+"""
+
+import re
+
+VIDEO_TYPES = {".mp4": "video/mp4", ".webm": "video/webm", ".ogv": "video/ogg"}
+
+IMG_RE = re.compile(r"<img\b[^>]*>")
+ATTR_RE = re.compile(r'(?<![\w-])(src|alt)="([^"]*)"')
+
+
+def _replace(match: re.Match) -> str:
+    attrs = dict(ATTR_RE.findall(match.group(0)))
+    src = attrs.get("src", "")
+    path = src.split("#")[0].split("?")[0].lower()
+    ext = next((e for e in VIDEO_TYPES if path.endswith(e)), None)
+    if ext is None:
+        return match.group(0)
+    alt = attrs.get("alt")
+    label = f' aria-label="{alt}"' if alt else ""
+    link_text = f"Download: {alt}" if alt else "Download the video"
+    return (
+        f'<video controls preload="metadata" style="width: 100%"{label}>'
+        f'<source src="{src}" type="{VIDEO_TYPES[ext]}">'
+        f'<a href="{src}">{link_text}</a>'
+        "</video>"
+    )
+
+
+def on_page_content(content: str, **kwargs) -> str:
+    return IMG_RE.sub(_replace, content)

mkdocs.yml

@@ -76,6 +76,9 @@ nav:
   - Support: support.md
   - FAQ: faq.md
 
+hooks:
+  - hooks/video.py
+
 plugins:
   - search
   - redirects: