Fetch and verify Git LFS assets before Hugo builds

.devcontainer/devcontainer.json

@@ -2,7 +2,7 @@
   "name": "Drasi Docs Dev Container",
   "image": "hugomods/hugo:node-git",
   "remoteUser": "root",
-  "postCreateCommand": "cd docs && git submodule update --init --recursive",
+  "postCreateCommand": "git lfs install && git lfs pull && ./scripts/verify-lfs-assets.sh && cd docs && git submodule update --init --recursive",
   "postStartCommand": "cd docs/themes/docsy && npm install && cd ../../ && hugo server --bind 0.0.0.0 --baseURL=http://localhost:1313",
   "portsAttributes": {
     "1313": {

.github/workflows/test.yaml

@@ -22,6 +22,10 @@ jobs:
         uses: actions/checkout@v5
         with:
           submodules: true
+          lfs: true
+
+      - name: Verify Git LFS assets
+        run: ./scripts/verify-lfs-assets.sh
 
       - name: Get Release ID by Tag
         id: get_release

.github/workflows/website.yaml

@@ -32,6 +32,8 @@ jobs:
         with:
           submodules: true
           lfs: true
+      - name: Verify Git LFS assets
+        run: ./scripts/verify-lfs-assets.sh
       - name: Setup Node
         uses: actions/setup-node@v5
         with:

Makefile

@@ -20,7 +20,7 @@ VERSION ?= latest
 # render uncommitted/untagged tutorial changes via a Hugo module replacement.
 TUTORIALS_LOCAL ?= ../learning-drasi-server
 
-.PHONY: help update-tutorials tidy serve preview-tutorials preview-docs build
+.PHONY: help update-tutorials tidy serve preview-tutorials preview-docs build lfs check-lfs
 
 help: ## Show this help.
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
@@ -34,13 +34,21 @@ update-tutorials: ## Pin the tutorials module to VERSION (default: latest tag) a
 tidy: ## Tidy Hugo module requirements (go.mod / go.sum).
 	cd $(HUGO_DIR) && hugo mod tidy
 
-serve: ## Run the local Hugo server against the pinned module version.
+lfs: ## Download the Git LFS assets (e.g. the homepage explainer video) into the working tree.
+	git lfs install --local
+	git lfs pull
+	./scripts/verify-lfs-assets.sh
+
+check-lfs: ## Fail (with instructions to run 'make lfs') if any Git LFS asset is still a pointer file.
+	./scripts/verify-lfs-assets.sh
+
+serve: check-lfs ## Run the local Hugo server against the pinned module version.
 	cd $(HUGO_DIR) && hugo server --disableFastRender
 
-preview-tutorials: ## Run the local Hugo server using a local checkout of the tutorials repo (TUTORIALS_LOCAL).
+preview-tutorials: check-lfs ## Run the local Hugo server using a local checkout of the tutorials repo (TUTORIALS_LOCAL).
 	cd $(HUGO_DIR) && HUGO_MODULE_REPLACEMENTS="$(TUTORIALS_MODULE) -> $(abspath $(TUTORIALS_LOCAL))" hugo server --disableFastRender
 
 preview-docs: preview-tutorials ## Alias of preview-tutorials.
 
-build: ## Build the static site into docs/public.
+build: check-lfs ## Build the static site into docs/public.
 	cd $(HUGO_DIR) && hugo

readme.md

@@ -27,10 +27,24 @@ Alternatively, you can follow the instructions below to setup and run a local Hu
 - [Hugo extended](https://gohugo.io/)
 - [Go](https://go.dev/) (required for Hugo modules)
 - [Node.js](https://nodejs.org/en/)
+- [Git LFS](https://git-lfs.com/) (required for media assets such as the homepage explainer video)
 
 ### Setup Hugo and Docsy
 
 1. Clone the [drasi-project/docs](https://github.com/drasi-project/docs) repo
+1. Media assets (`*.mp4`, `*.mov`) are stored with Git LFS. Without Git LFS these files are checked out as small text pointer files and the site will render an unplayable video. From the root of the repo run:
+
+    ```
+    git lfs install
+    git lfs pull
+    ```
+
+    Or run `make lfs`, which does both and then verifies the result. You can check the assets are real files (and not pointers) at any time, without network access, with:
+
+    ```make check-lfs```
+
+    The `make serve`, `make preview-tutorials`, `make preview-docs` and `make build` targets run this check first and fail with instructions if an asset is still a pointer file.
+
 1. The Docsy theme is configured as a submodule which needs to be pulled. From the root of the drasi-project/docs repo (where this readme is located) run: 
 
     ```git submodule update --init --recursive```

scripts/verify-lfs-assets.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+#
+# Verify that every Git LFS tracked asset (for example the homepage explainer
+# video in docs/assets/video) has been materialized in the working tree.
+#
+# When a repository is cloned without Git LFS, tracked files are left on disk as
+# small text pointer files. Hugo happily copies those pointers into the
+# generated site, which produces a page that references an unplayable "video".
+# Running this check before Hugo makes that failure loud instead of silent.
+#
+# Usage: scripts/verify-lfs-assets.sh
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if ! command -v git >/dev/null 2>&1; then
+  echo "verify-lfs-assets: git is not installed." >&2
+  exit 1
+fi
+
+if ! git lfs version >/dev/null 2>&1; then
+  echo "verify-lfs-assets: Git LFS is not installed." >&2
+  echo "Install it from https://git-lfs.com and run 'git lfs install && git lfs pull'." >&2
+  exit 1
+fi
+
+# 'git lfs ls-files' marks each entry with '*' when the real object is checked
+# out and '-' when only the pointer file is present.
+pointers="$(git lfs ls-files | awk '$2 == "-" { sub(/^[^ ]+ [^ ]+ /, ""); print }')"
+
+if [ -n "$pointers" ]; then
+  echo "verify-lfs-assets: the following Git LFS assets are still pointer files:" >&2
+  echo "$pointers" | sed 's/^/  - /' >&2
+  echo >&2
+  echo "Fetch the real content before building the site:" >&2
+  echo "  make lfs" >&2
+  echo "or, without make:" >&2
+  echo "  git lfs install && git lfs pull" >&2
+  exit 1
+fi
+
+echo "verify-lfs-assets: all Git LFS assets are checked out."