For AI agents: a documentation index is available at /llms.txt — every docs page also has a markdown twin (append .md to the page URL).
Hugo → PDF with makesPDF
Hugo gets a recipe, not a plugin: there is no Hugo module to install. Copy makespdf-pdf.sh into your site repo and run it after hugo. Each content page is posted to POST /api/v1/md on the makesPDF hosted API — one billed render per page — and the PDF lands next to the published HTML (content/guide.md → public/guide.pdf).
MkDocs sites should use the makespdf[mkdocs] Python extra and Docusaurus sites the @makespdf/docusaurus-plugin npm package instead: both add per-page pdf-template routing (stored-template renders), which this recipe deliberately does not cover.
Setup
export MAKESPDF_API_KEY=... # mint at https://makespdf.com/settings/api-keys?ref=hugo-recipe
curl -O https://makespdf.com/docs/integrations/hugo/makespdf-pdf.sh
hugo
./makespdf-pdf.sh content public
# public/guide.pdf, public/combined.pdf, ...Environment:
| Variable | Default | Meaning |
|---|---|---|
| MAKESPDF_API_KEY | — (required) | Bearer key for the hosted API |
| MAKESPDF_BASE_URL | https://makespdf.com | API host override |
| MAKESPDF_PAGE_SIZE | A4 | /md pageSize option |
| MAKESPDF_COMBINED | combined.pdf | Empty string disables the combined PDF |
The script
curl -O downloads the script from https://makespdf.com/docs/integrations/hugo/makespdf-pdf.sh. The full listing is below so you can review it before running it:
#!/usr/bin/env bash
# Render Hugo content pages to PDF via the makesPDF hosted API.
# Recipe companion to https://makespdf.com/docs/integrations/hugo — copy
# into your site repo and run after `hugo`. One billed POST /api/v1/md
# render per page.
#
# Usage: MAKESPDF_API_KEY=... ./makespdf-pdf.sh [content_dir] [publish_dir]
# Env: MAKESPDF_API_KEY (required), MAKESPDF_BASE_URL (default prod),
# MAKESPDF_PAGE_SIZE (default A4), MAKESPDF_COMBINED (default
# combined.pdf; empty disables the combined PDF).
set -euo pipefail
CONTENT_DIR="${1:-content}"
PUBLISH_DIR="${2:-public}"
BASE_URL="${MAKESPDF_BASE_URL:-https://makespdf.com}"
PAGE_SIZE="${MAKESPDF_PAGE_SIZE:-A4}"
COMBINED="${MAKESPDF_COMBINED-combined.pdf}"
if [ -z "${MAKESPDF_API_KEY:-}" ]; then
echo "makespdf-pdf: MAKESPDF_API_KEY is not set (mint one at https://makespdf.com/settings/api-keys?ref=hugo-recipe)" >&2
exit 1
fi
# The key is handed to curl in a quoted config line; these would break it.
case "$MAKESPDF_API_KEY" in
*[\"\\$'\r\n']*)
echo "makespdf-pdf: MAKESPDF_API_KEY contains a quote, backslash or line break; re-copy the key" >&2
exit 1
;;
esac
if ! curl --help all 2>/dev/null | grep -q -- --fail-with-body; then
echo "makespdf-pdf: needs curl 7.76 or later (found: $(curl --version 2>/dev/null | head -1))" >&2
exit 1
fi
# Scratch files, reused per page and removed on any exit.
combined_tmp="$(mktemp)"
body_file="$(mktemp)"
payload_file="$(mktemp)"
out_tmp="$(mktemp)"
trap 'rm -f "$combined_tmp" "$body_file" "$payload_file" "$out_tmp"' EXIT
# Print the body of $1 (front-matter stripped), or nothing when skipped.
# Skip rules: `pdf: false` in the front-matter block, or `draft: true`.
page_body() {
awk '
NR == 1 && $0 == "---" { fm = 1; next }
fm && $0 == "---" { fm = 0; next }
fm { block = block $0 "\n"; next }
{ body = body $0 "\n" }
END {
if (tolower(block) ~ /(^|\n)pdf:[ \t]*(false|no|off)/) exit 10
if (tolower(block) ~ /(^|\n)draft:[ \t]*true/) exit 10
printf "%s", body
}
' "$1"
}
render_md() {
# $1 = markdown file (body only), $2 = output pdf path
# The payload goes by file (--data-binary @file) so a large page cannot hit
# the OS argv limit, and the key goes by stdin config (--config -) so it is
# never in curl's argv. --fail-with-body keeps the API's error JSON; with -o
# it lands in the output file, so print it to stderr on failure.
python3 -c 'import json,sys; json.dump({"markdown": sys.stdin.read(), "options": {"pageSize": sys.argv[1]}}, sys.stdout)' "$PAGE_SIZE" < "$1" > "$payload_file"
mkdir -p "$(dirname "$2")"
if ! printf 'header = "Authorization: Bearer %s"\n' "$MAKESPDF_API_KEY" |
curl -sS --fail-with-body --config - -X POST "$BASE_URL/api/v1/md" \
-H "Content-Type: application/json" \
-H "Accept: application/pdf" \
--data-binary "@$payload_file" -o "$out_tmp"; then
echo "makespdf-pdf: render failed for $2:" >&2
cat "$out_tmp" >&2
echo >&2
return 1
fi
# Not a plain mv: mktemp files are 0600 and a published PDF must not be.
# Write beside the target, then rename, so a reader never sees half a PDF.
cat "$out_tmp" > "$2.tmp"
mv -f "$2.tmp" "$2"
}
: > "$combined_tmp"
rendered=0
while IFS= read -r src; do
rel="${src#"$CONTENT_DIR"/}"
dest="$PUBLISH_DIR/${rel%.md}.pdf"
if ! body="$(page_body "$src")"; then
echo "makespdf-pdf: skip $rel"
continue
fi
printf "%s" "$body" > "$body_file"
render_md "$body_file" "$dest"
printf "%s\n\n" "$body" >> "$combined_tmp"
rendered=$((rendered + 1))
echo "makespdf-pdf: $rel -> ${dest#"$PUBLISH_DIR"/}"
done < <(find "$CONTENT_DIR" -name '*.md' | sort)
if [ -n "$COMBINED" ] && [ "$rendered" -gt 0 ]; then
render_md "$combined_tmp" "$PUBLISH_DIR/$COMBINED"
echo "makespdf-pdf: combined ($rendered pages) -> $COMBINED"
fiPer-page opt-out
---
title: Internal
pdf: false
---Pages with pdf: false in the front-matter block are skipped (no PDF, no bill). Drafts (draft: true) are skipped too — they have no published HTML to sit next to. Only --- YAML front-matter is recognised: pages using +++ TOML front-matter always render (their delimiters are sent as markdown).
Combined mode
All rendered bodies are concatenated into one extra PDF (public/combined.pdf by default). Set MAKESPDF_COMBINED= to disable it.
Cost and limits
One billed render per page, plus one more for the combined PDF. Requires bash, curl 7.76 or later, and python3 (JSON escaping only — no packages). No offline rendering: every call is a hosted API call, so billing matches the web app and CLI.