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

bash
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:

VariableDefaultMeaning
MAKESPDF_API_KEY— (required)Bearer key for the hosted API
MAKESPDF_BASE_URLhttps://makespdf.comAPI host override
MAKESPDF_PAGE_SIZEA4/md pageSize option
MAKESPDF_COMBINEDcombined.pdfEmpty 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:

bash
#!/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"
fi

Per-page opt-out

markdown
---
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.