diff --git a/.tool/curver.go b/.tool/curver.go
new file mode 100644
index 000000000..e4252cd79
--- /dev/null
+++ b/.tool/curver.go
@@ -0,0 +1,26 @@
+// Copyright 2025 The Linux Foundation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"fmt"
+
+	"github.com/opencontainers/image-spec/specs-go"
+)
+
+// This package is intended to be executed using "go run .tool/curver.go".
+func main() {
+	fmt.Println(specs.Version)
+}
diff --git a/.tool/genheader.go b/.tool/genheader.go
deleted file mode 100644
index 6d1e1767d..000000000
--- a/.tool/genheader.go
+++ /dev/null
@@ -1,54 +0,0 @@
-// Copyright 2017 The Linux Foundation
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package main
-
-import (
-	"bytes"
-	"fmt"
-	"os"
-	"os/exec"
-	"strings"
-	"text/template"
-
-	specs "github.com/opencontainers/image-spec/specs-go"
-)
-
-var headerTemplate = template.Must(template.New("gen").Parse(`<title>image-spec {{.Version}}</title>
-<base href="https://raw.githubusercontent.com/opencontainers/image-spec/{{.Branch}}/">`))
-
-type Obj struct {
-	Version string
-	Branch  string
-}
-
-func main() {
-	obj := Obj{
-		Version: specs.Version,
-		Branch:  specs.Version,
-	}
-	if strings.HasSuffix(specs.Version, "-dev") {
-		cmd := exec.Command("git", "log", "-1", `--pretty=%H`, "HEAD")
-		var out bytes.Buffer
-		cmd.Stdout = &out
-		cmd.Stderr = os.Stderr
-		if err := cmd.Run(); err != nil {
-			fmt.Fprintln(os.Stderr, err)
-			os.Exit(1)
-		}
-
-		obj.Branch = strings.Trim(out.String(), " \n\r")
-	}
-	headerTemplate.Execute(os.Stdout, obj)
-}
diff --git a/Makefile b/Makefile
index ef825617a..72cce275d 100644
--- a/Makefile
+++ b/Makefile
@@ -8,18 +8,17 @@ GOPATH:=$(shell go env GOPATH)
 OUTPUT_DIRNAME	?= output
 DOC_FILENAME	?= oci-image-spec
 
-PANDOC_CONTAINER ?= ghcr.io/opencontainers/pandoc:2.9.2.1-8.fc33.x86_64@sha256:5d81ff930a043295a557be8b003ece2a33d14e91b28c50d368413b83372f8d28
+# pinned to a 3.1 release due to a regression, see https://github.com/jgm/pandoc/issues/10952 before upgrading
+PANDOC_CONTAINER ?= docker.io/pandoc/latex:3.1@sha256:1cf54d9214a9b52de2f58cf5895cc596a5960711a54d7938dc72f2b23473caf3
 ifeq "$(strip $(PANDOC))" ''
 	ifneq "$(strip $(DOCKER))" ''
 		PANDOC = $(DOCKER) run \
 			--rm \
-			-v $(shell pwd)/:/input/:ro \
-			-v $(shell pwd)/$(OUTPUT_DIRNAME)/:/$(OUTPUT_DIRNAME)/ \
-			-u $(shell id -u) \
-			--workdir /input \
+			-v "$(CURDIR)/:/workdir/:ro" \
+			-v "$(CURDIR)/$(OUTPUT_DIRNAME)/:/workdir/$(OUTPUT_DIRNAME)/" \
+			-u "$(shell id -u):$(shell id -g)" \
+			--workdir /workdir \
 			$(PANDOC_CONTAINER)
-		PANDOC_SRC := /input/
-		PANDOC_DST := /
 	endif
 endif
 
@@ -55,24 +54,22 @@ fmt: ## format the json with indentation
 docs: $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html ## generate a PDF/HTML version of the OCI image specification
 
 ifeq "$(strip $(PANDOC))" ''
-$(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) $(FIGURE_FILES)
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).%: $(DOC_FILES) $(FIGURE_FILES)
 	$(error cannot build $@ without either pandoc or docker)
 else
 $(OUTPUT_DIRNAME)/$(DOC_FILENAME).pdf: $(DOC_FILES) $(FIGURE_FILES)
 	@mkdir -p $(OUTPUT_DIRNAME)/ && \
-	$(PANDOC) -f gfm -t latex --pdf-engine=xelatex -V geometry:margin=0.5in,bottom=0.8in -V block-headings -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
-	ls -sh $(realpath $@)
+	version="v$$(go run .tool/curver.go)" && \
+	$(PANDOC) -f gfm -t latex -o $@ --metadata "title=image-spec $${version}" --standalone --file-scope --pdf-engine=xelatex -V geometry:margin=0.5in,bottom=0.8in -V block-headings $(DOC_FILES)
+	ls -sh $@
 
-$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: header.html $(DOC_FILES) $(FIGURE_FILES)
+$(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES) $(FIGURE_FILES)
 	@mkdir -p $(OUTPUT_DIRNAME)/ && \
-	cp -ap img/ $(shell pwd)/$(OUTPUT_DIRNAME)/&& \
-	$(PANDOC) -f gfm -t html5 -H $(PANDOC_SRC)header.html --standalone -o $(PANDOC_DST)$@ $(patsubst %,$(PANDOC_SRC)%,$(DOC_FILES))
-	ls -sh $(realpath $@)
+	version="v$$(go run .tool/curver.go)" && \
+	$(PANDOC) -f gfm -t html5 -o $@ --metadata "title=image-spec $${version}" --standalone --file-scope --embed-resources -V "maxwidth:95%" $(DOC_FILES)
+	ls -sh $@
 endif
 
-header.html: .tool/genheader.go specs-go/version.go
-	go run .tool/genheader.go > $@
-
 .PHONY: validate-examples
 validate-examples: schema/schema.go ## validate examples in the specification markdown files
 	cd schema && go test -run TestValidate .