Add embed tool for embedding files in markdown

Signed-off-by: Lennart Jern <[email protected]>

Author: lentzi90

Makefile

@@ -12,14 +12,15 @@ MDBOOK_BIN := $(TOOLS_BIN_DIR)/mdbook
 export PATH := $(PATH):$(TOOLS_BIN_DIR)
 
 ## ------------------------------------
-## Resolve placeholders as tags
+## mdbook plugins
 ## ------------------------------------
 RELEASETAGS := $(TOOLS_BIN_DIR)/mdbook-releasetags
 $(RELEASETAGS): $(TOOLS_DIR)/go.mod
 	cd $(TOOLS_DIR); go build -tags=tools -o $(TOOLS_BIN_DIR)/mdbook-releasetags ./releasetags
 
-.PHONY: releasetags
-releasetags: $(RELEASETAGS)
+MDBOOK_EMBED := $(TOOLS_BIN_DIR)/mdbook-embed
+$(MDBOOK_EMBED): $(TOOLS_DIR)/go.mod
+	cd $(TOOLS_DIR); go build -tags=tools -o $(TOOLS_BIN_DIR)/mdbook-embed sigs.k8s.io/cluster-api/hack/tools/mdbook/embed
 
 ## ------------------------------------
 ## Documentation tooling for Netlify
@@ -32,7 +33,7 @@ $(MDBOOK_BIN): # Download the binary
 	curl -L $(MDBOOK_RELEASE_URL) | tar xvz -C $(TOOLS_BIN_DIR)
 
 .PHONY: netlify-build
-netlify-build: $(RELEASETAGS) $(MDBOOK_BIN)
+netlify-build: $(MDBOOK_EMBED) $(RELEASETAGS) $(MDBOOK_BIN)
 	$(MDBOOK_BIN) build $(SOURCE_PATH)
 
 

docs/Dockerfile

@@ -1,4 +1,4 @@
-ARG BUILD_IMAGE=docker.io/golang:1.21.9@sha256:7d0dcbe5807b1ad7272a598fbf9d7af15b5e2bed4fd6c4c2b5b3684df0b317dd
+ARG BUILD_IMAGE=docker.io/golang:1.25.3@sha256:6ea52a02734dd15e943286b048278da1e04eca196a564578d718c7720433dbbe
 FROM $BUILD_IMAGE AS builder
 WORKDIR /workspace
 
@@ -21,11 +21,13 @@ COPY hack/tools/releasetags/ releasetags/
 ARG ARCH=amd64
 RUN CGO_ENABLED=0 GOOS=linux GOARCH=${ARCH} \
   go build -tags=tools -a -ldflags '-extldflags "-static"' \
-  -o mdbook-releasetags ./releasetags
+  -o mdbook-releasetags ./releasetags && \
+  go build -tags=tools -a -ldflags '-extldflags "-static"' \
+  -o mdbook-embed sigs.k8s.io/cluster-api/hack/tools/mdbook/embed
 ARG MDBOOK_RELEASE_URL="https://github.com/rust-lang/mdBook/releases/download/v0.4.52/mdbook-v0.4.52-x86_64-unknown-linux-gnu.tar.gz"
 RUN curl -L "${MDBOOK_RELEASE_URL}" \
   | tar xvz -C /workspace
 
 FROM netlify/build:noble
 WORKDIR /workdir
-COPY --from=builder /workspace/mdbook-releasetags /workspace/mdbook /usr/bin/
+COPY --from=builder /workspace/mdbook* /usr/bin/

docs/user-guide/book.toml

@@ -6,6 +6,9 @@ title = "Metal³ user-guide"
 
 [preprocessor.releasetags]
 
+[preprocessor.embed]
+command = "mdbook-embed"
+
 [output.html]
 git-repository-url = "https://github.com/metal3-io/"
 smart-punctuation = true

hack/tools/go.mod

@@ -1,8 +1,12 @@
 module metal3-io/metal3-docs/hack/tools
 
-go 1.21
+go 1.24.0
 
 require (
 	github.com/blang/semver v3.5.1+incompatible
 	sigs.k8s.io/kubebuilder/docs/book/utils v0.0.0-20240216033807-8afeb403549f
 )
+
+require sigs.k8s.io/cluster-api/hack/tools v0.0.0-20251020054008-0978f70c29b1 // indirect
+
+tool sigs.k8s.io/cluster-api/hack/tools/mdbook/embed

hack/tools/go.sum

@@ -1,4 +1,6 @@
 github.com/blang/semver v3.5.1+incompatible h1:cQNTCjp13qL8KC3Nbxr/y2Bqb63oX6wdnnjpJbkM4JQ=
 github.com/blang/semver v3.5.1+incompatible/go.mod h1:kRBLl5iJ+tD4TcOOxsy/0fnwebNt5EWlYSAyrTnjyyk=
+sigs.k8s.io/cluster-api/hack/tools v0.0.0-20251020054008-0978f70c29b1 h1:FxcZZdIxGOHIgl4ETvsuSYR3eKozMZTKCarNRI/Ix74=
+sigs.k8s.io/cluster-api/hack/tools v0.0.0-20251020054008-0978f70c29b1/go.mod h1:l26LNezuh0r/oQ492SQqIGpTCxkmSwymKnvXjCPz6hE=
 sigs.k8s.io/kubebuilder/docs/book/utils v0.0.0-20240216033807-8afeb403549f h1:0rbnCuTF/IIxfwoJR/p7zTB5+AA0RaBwB0lqjBUs/28=
 sigs.k8s.io/kubebuilder/docs/book/utils v0.0.0-20240216033807-8afeb403549f/go.mod h1:4CGoZGcqb7Bes5d0qgb4SIHqk+XjUfoxesbbTmpVl6s=