[docs] Add PDF/DOCX export pipeline (#232)

* [docs] Add PDF/DOCX export pipeline

- Introduce multi-stage werf build for print artefacts using a
  dedicated base image with WeasyPrint, Pandoc, and Node tooling;
  the print-artifacts stage renders HTML via a local server, runs
  the export script per locale, and feeds results into the web
  image so downloads are served at deploy time
- Add a make target that builds the print-artifacts image and
  extracts the generated files locally; refactor the help system
  to use self-documenting inline comments with awk-based parsing
  and add ARM platform detection for cross-compilation
- Enable the print output format and downloads shortcode in both
  EN/RU documentation landing pages; configure per-language PDF
  titles and the global pdf toggle in the site parameters
- Bump hugo-web-product-module from v0.1.17 to v0.1.20

* [docs] Add PDF/DOCX export pipeline

- Introduce multi-stage werf build for print artefacts using a
  dedicated base image with WeasyPrint, Pandoc, and Node tooling;
  the print-artifacts stage renders HTML via a local server, runs
  the export script per locale, and feeds results into the web
  image so downloads are served at deploy time
- Add a make target that builds the print-artifacts image and
  extracts the generated files locally; refactor the help system
  to use self-documenting inline comments with awk-based parsing
  and add ARM platform detection for cross-compilation
- Enable the print output format and downloads shortcode in both
  EN/RU documentation landing pages; configure per-language PDF
  titles and the global pdf toggle in the site parameters
- Bump hugo-web-product-module from v0.1.17 to v0.1.21

Author: z9r5

Makefile

@@ -1,72 +1,91 @@
 # Makefile for the Hugo website
 
+PLATFORM_NAME := $(shell uname -p)
+ifneq ($(filter arm%,$(PLATFORM_NAME)),)
+	export WERF_PLATFORM=linux/amd64
+endif
+
+.DEFAULT_GOAL := help
+
 # Tools / variables (can be overridden on the command line)
 HUGO ?= hugo
 BIND ?= 0.0.0.0
 SERVE_FLAGS ?= --cleanDestinationDir --bind=$(BIND)
 HUGOFLAGS ?= --minify
 MARKDOWNLINT_VERSION ?= v0.45.0
+WERF ?= werf
 WERF_PLATFORM ?= linux/amd64
 
 CURRENT_UID ?= $(shell id -u)
 CURRENT_GID ?= $(shell id -g)
 PORTS_TO_FREE ?= 80 1313 1314
 
-.PHONY: help serve build down lint-markdown lint-markdown-fix mod
-.PHONY: help serve build down lint-markdown lint-markdown-fix mod free-ports
-
-help:
-	@echo "Usage: make [target]"
-	@echo
-	@echo "Common targets:"
-	@echo "  up               Start documentation (available at http://localhost and http://ru.localhost)"
-	@echo "  serve            Start Hugo dev server (hugo serve --cleanDestinationDir)"
-	@echo "  build            Build the site to ./public"
-	@echo "  down             Stop and remove documentation containers"
-	@echo "  lint-markdown    Lint markdown files"
-	@echo "  lint-markdown-fix Fix markdown files automatically"
-	@echo "  mod              Clean up Hugo modules (hugo mod tidy)"
-	@echo "  help             Show this help"
-	@echo
-	@echo "Variables (can be overridden):"
-	@echo "  HUGO=$(HUGO)"
-	@echo "  PORT=$(PORT)"
-	@echo "  BIND=$(BIND)"
-	@echo "  BASEURL=$(BASEURL)"
-	@echo "  MARKDOWNLINT_VERSION=$(MARKDOWNLINT_VERSION)"
-
-up:
+PRODUCT_CODE ?= $(shell awk '/^  productCode:/ {print tolower($$2); exit}' config/_default/hugo.yaml)
+
+##@ Main
+
+up: ## Start documentation (available at http://localhost and http://ru.localhost)
 	@$(MAKE) down
 	@$(MAKE) free-ports
 	@UID=$(CURRENT_UID) GID=$(CURRENT_GID) docker compose up
 
-free-ports:
-	@containers="$$(for port in $(PORTS_TO_FREE); do docker ps -q --filter "publish=$$port"; done | sort -u)"; \
-	if [ -n "$$containers" ]; then \
-		echo "Stopping containers using ports $(PORTS_TO_FREE): $$containers"; \
-		docker stop $$containers; \
-	fi
-
-down:
-	docker compose rm -f
-	docker compose down --remove-orphans
-
-serve:
+serve: ## Start Hugo dev server (hugo serve --cleanDestinationDir)
 	$(HUGO) serve $(SERVE_FLAGS)
 
-build:
+build: ## Build the site to ./public
 	@echo "Building site to ./public..."
 	$(HUGO) $(HUGOFLAGS)
 
-lint-markdown:
+pdf: ## Build the site and generate PDF+DOCX exports via werf
+	##~ Output: public/{en,ru}/documentation/downloads/print/<productCode>.{pdf,docx}
+	##~ Need external registry (e.g. export WERF_REPO=localhost:4999/docs) to run.
+	@echo "Building print-artifacts via werf..."
+	@$(WERF) build print-artifacts
+	@echo "Extracting PDF/DOCX ($(PRODUCT_CODE)) to ./public/{en,ru}/documentation/downloads/print/..."
+	@IMG=$$($(WERF) stage image print-artifacts) && \
+	  CID=$$(docker create $$IMG) && \
+	  trap "docker rm $$CID >/dev/null" EXIT && \
+	  mkdir -p ./public/en/documentation/downloads/print ./public/ru/documentation/downloads/print && \
+	  docker cp $$CID:/out/en/documentation/downloads/print/. ./public/en/documentation/downloads/print/ && \
+	  docker cp $$CID:/out/ru/documentation/downloads/print/. ./public/ru/documentation/downloads/print/
+	@echo "Done. Files: public/{en,ru}/documentation/downloads/print/$(PRODUCT_CODE).{pdf,docx}"
+
+down: ## Stop and remove documentation containers
+	docker compose rm -f
+	docker compose down --remove-orphans
+
+##@ Linters
+
+lint-markdown: ## Lint markdown files
 	@echo "Linting markdown files..."
 	@docker run --rm -v "$(PWD):/workdir" -w /workdir ghcr.io/igorshubovych/markdownlint-cli:$(MARKDOWNLINT_VERSION) "**/*.md" -c markdownlint.yaml
 
-lint-markdown-fix:
+lint-markdown-fix: ## Lint and auto-fix markdown files
 	@echo "Fixing markdown files..."
 	@docker run --rm -v "$(PWD):/workdir" -w /workdir ghcr.io/igorshubovych/markdownlint-cli:$(MARKDOWNLINT_VERSION) "**/*.md" -c markdownlint.yaml --fix
 
-mod:
+##@ Helpers
+
+mod: ## Clean up Hugo modules (hugo mod tidy)
 	@echo "Cleaning up Hugo modules..."
 	$(HUGO) mod tidy
 
+free-ports: ## Stop containers using known dev ports ($(PORTS_TO_FREE))
+	@containers="$$(for port in $(PORTS_TO_FREE); do docker ps -q --filter "publish=$$port"; done | sort -u)"; \
+	if [ -n "$$containers" ]; then \
+		echo "Stopping containers using ports $(PORTS_TO_FREE): $$containers"; \
+		docker stop $$containers; \
+	fi
+
+help: ## Show this help message
+	@echo 'Usage: make [target]'
+	@echo ''
+	@echo 'Available targets:'
+	@awk 'BEGIN {\
+		FS = ":.*?## "; \
+	} \
+	/^##@/                    { printf "\n%s\n", substr($$0, 5) } \
+	/^[a-zA-Z0-9_-]+:.*?## / { printf "  %-20s %s\n", $$1, $$2 } \
+	/^.?.?##~/              { printf "  %-20s %s\n", "", substr($$1, 6) }' $(MAKEFILE_LIST)
+
+.PHONY: help up serve build pdf down lint-markdown lint-markdown-fix mod free-ports

README.md

@@ -17,3 +17,18 @@ To run locally:
    ```
 
 1. Open `http://localhost/products/development-platform/documentation/` in your browser (for the english version) or `http://ru.localhost/products/development-platform/documentation/` (for the russian version).
+
+## Generating PDF/DOCX exports
+
+Run `make pdf` — the werf `print-artifacts` image is built and the resulting files are
+extracted into `public/{en,ru}/documentation/downloads/print/development-platform.{pdf,docx}`.
+On deploy the same image is imported into `web`, so the site serves them under the same URL.
+
+This project enables PDF/DOCX through:
+
+- `params.pdf: true` in `config/_default/hugo.yaml`;
+- `outputs: [HTML, search, print]` in the front matter of `content/documentation/_index.{md,ru.md}`;
+- sidebar download links (rendered automatically by the module theme).
+
+For the full description of the pipeline (werf stages, requirements, how to enable/disable
+for a new product website) see the [PDF/DOCX exports section in the module README](https://github.com/deckhouse/hugo-web-product-module/blob/main/README.md#pdfdocx-exports).

config/_default/hugo.yaml

@@ -69,6 +69,9 @@ params:
   # Enable Lunr.js offline search
   offlineSearch: true
 
+  # Enable PDF/DOCX documentation exports (generated in CI, downloadable from sidebar).
+  pdf: true
+
   # Global relevant links.
   links:
 
@@ -104,10 +107,12 @@ languages:
     baseURL: https://deckhouse.io/products/development-platform/
     params:
       description: ""
+      pdfTitle: "Deckhouse Development Platform Documentation"
   ru:
     disabled: false
     weight: 1
     title: Deckhouse Development Platform
     baseURL: https://deckhouse.ru/products/development-platform/
     params:
       description: ""
+      pdfTitle: "Документация Deckhouse Development Platform"

content/documentation/_index.md

@@ -7,11 +7,14 @@ params:
 outputs:
   - HTML
   - search
+  - print
 cascade:
   params:
     simple_list: true
 ---
 
+{{< downloads >}}
+
 Deckhouse Development Platform (DDP) is a comprehensive solution for managing all stages of development through a single interface.
 
 The platform helps IT professionals work more efficiently — it automates operations related to the service lifecycle and provides tools to assess the overall system performance.

content/documentation/_index.ru.md

@@ -7,11 +7,14 @@ params:
 outputs:
   - HTML
   - search
+  - print
 cascade:
   params:
     simple_list: true
 ---
 
+{{< downloads >}}
+
 Deckhouse Development Platform (DDP) — это комплексное решение для управления всеми этапами разработки через единое окно. Платформа автоматизирует операции, связанные с жизненным циклом сервисов, и предоставляет инструменты для оценки работы всей системы.
 
 ## Основные возможности

go.mod

@@ -4,4 +4,4 @@ module github.com/deckhouse/website-development-platform
 
 go 1.24.2
 
-require github.com/deckhouse/hugo-web-product-module v0.1.17 // indirect
+require github.com/deckhouse/hugo-web-product-module v0.1.21 // indirect

go.sum

@@ -1,2 +1,2 @@
-github.com/deckhouse/hugo-web-product-module v0.1.17 h1:HZ9xxXlUYo7geiTyaZTXk0JFvT0xOkXfYaOeXdUmzVE=
-github.com/deckhouse/hugo-web-product-module v0.1.17/go.mod h1:iLVlLSCkbOoi7RjYm5RjwAQi+Whs6DjSumhaH1GBjqw=
+github.com/deckhouse/hugo-web-product-module v0.1.21 h1:Dxjcd45jRa1EKaCMUnhWjauZnkGlRVa3l/8S9YeSUew=
+github.com/deckhouse/hugo-web-product-module v0.1.21/go.mod h1:iLVlLSCkbOoi7RjYm5RjwAQi+Whs6DjSumhaH1GBjqw=

werf.yaml

@@ -18,10 +18,75 @@ git:
   stageDependencies:
     setup: ['**/*']
 ---
+image: print-base
+from: ubuntu:24.04
+final: true
+shell:
+  beforeInstall:
+  - export DEBIAN_FRONTEND=noninteractive DEBCONF_NOWARNINGS=yes
+  - apt-get update -qq
+  - apt-get install -y -qq --no-install-recommends apt-utils
+  - apt-get install -y -qq --no-install-recommends weasyprint pandoc poppler-utils fonts-dejavu-core fonts-liberation ca-certificates curl gnupg git
+  - curl -fsSL https://deb.nodesource.com/setup_24.x 2>/dev/null | bash - >/dev/null 2>&1
+  - apt-get install -y -qq --no-install-recommends nodejs
+  - mkdir -p /deps && cd /deps && npm init -y >/dev/null
+  - cd /deps && npm install --silent --no-audit --no-fund cheerio http-server jszip
+  - apt-get autoclean && apt-get clean
+---
+image: print-artifacts
+fromImage: print-base
+final: false
+import:
+- image: web-artifacts
+  add: /out
+  to: /site
+  before: setup
+  stage: setup
+git:
+- add: /
+  to: /src
+  includePaths:
+    - go.mod
+    - config/
+  stageDependencies:
+    setup: ['**/*']
+shell:
+  setup:
+  - |
+    set -e
+    PDF_ENABLED=$(awk '/^  pdf:/ {print tolower($2); exit}' /src/config/_default/hugo.yaml)
+    mkdir -p /out
+    if [ "$PDF_ENABLED" != "true" ]; then
+      echo "params.pdf is not true — skipping PDF/DOCX generation."
+      cp -a /site/. /out/
+      exit 0
+    fi
+    git config --global advice.detachedHead false
+    export NODE_PATH=/deps/node_modules
+    export PUBLIC_DIR=/site
+    HUGO_TEMPLATE_VER=$(awk -v m='github.com/deckhouse/hugo-web-product-module' \
+      '{for(i=1;i<=NF;i++) if($i==m && $(i+1) ~ /^v/) {print $(i+1); exit}}' /src/go.mod)
+    export PRODUCT_CODE=$(awk '/^  productCode:/ {print tolower($2); exit}' /src/config/_default/hugo.yaml)
+    test -n "$HUGO_TEMPLATE_VER" || { echo "ERROR: cannot parse hugo-web-product-module version from go.mod"; exit 1; }
+    test -n "$PRODUCT_CODE"      || { echo "ERROR: cannot parse params.productCode from config/_default/hugo.yaml"; exit 1; }
+    git clone --depth=1 --filter=blob:none --sparse \
+      --branch "$HUGO_TEMPLATE_VER" \
+      https://github.com/deckhouse/hugo-web-product-module.git /tmp/tpl
+    git -C /tmp/tpl sparse-checkout set .github/scripts
+    mv /tmp/tpl/.github/scripts /scripts
+    rm -rf /tmp/tpl
+    (cd /site && /deps/node_modules/.bin/http-server -p 8088 -s >/tmp/http.log 2>&1 &)
+    for i in $(seq 1 30); do curl -sf http://localhost:8088/ >/dev/null && break; sleep 1; done
+    node /scripts/print-export.js en http://localhost:8088
+    node /scripts/print-export.js ru http://localhost:8088
+    cp -a /site/. /out/
+---
 image: web
 fromImage: nginx:1.29.3-alpine
+final: true
 import:
-- image: web-artifacts
+- image: print-artifacts
   add: /out
   to: /app
   before: setup
+  stage: setup