feat(pdf): drop node+puppeteer deps

Author: iamgio

.dockerignore

@@ -1,5 +1,6 @@
 build/
 **/build/
+**/node_modules/
 .git/
 .github/
 .run/

.github/actions/setup-environment/action.yml

@@ -29,27 +29,11 @@ runs:
     - name: Setup Gradle
       uses: gradle/actions/setup-gradle@v3
 
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-
     - name: Setup Chrome
       uses: browser-actions/setup-chrome@v1
       id: setup-chrome
 
-    - name: Set Puppeteer's executable path
-      run: |
-        echo "PUPPETEER_EXECUTABLE_PATH=${{ steps.setup-chrome.outputs.chrome-path }}" >> $GITHUB_ENV
-      shell: bash
-
-    - name: Set npm environment variables
-      run: |
-        mkdir -p $HOME/.npm-global/lib
-        echo "QD_NPM_PREFIX=$HOME/.npm-global/lib" >> $GITHUB_ENV
-        echo "NODE_PATH=$HOME/.npm-global/lib/node_modules" >> $GITHUB_ENV
-      shell: bash
-
-    - name: Install Puppeteer
+    - name: Set browser path
       run: |
-        export PUPPETEER_SKIP_DOWNLOAD=true
-        npm install puppeteer --prefix ${{ env.QD_NPM_PREFIX }}
+        echo "QD_CHROME_PATH=${{ steps.setup-chrome.outputs.chrome-path }}" >> $GITHUB_ENV
       shell: bash

.github/workflows/docker-image-test.yml

@@ -22,6 +22,14 @@ jobs:
     steps:
     - uses: actions/checkout@v4
 
+    - name: Check Chrome version pin is in sync
+      run: |
+        VERSION=$(cat quarkdown-html-pdf/scripts/chrome-version.txt)
+        if ! grep -q "HEADLESS_SHELL_VERSION=$VERSION" Dockerfile; then
+          echo "ERROR: Dockerfile HEADLESS_SHELL_VERSION is out of sync with quarkdown-html-pdf/scripts/chrome-version.txt ($VERSION)"
+          exit 1
+        fi
+
     - name: Build Docker image
       run: docker build -t quarkdown:test .
 

.github/workflows/generate-pdf.yml

@@ -1,4 +1,4 @@
-name: PDF generation via Puppeteer
+name: PDF generation
 
 on:
   push:
@@ -18,10 +18,6 @@ jobs:
     steps:
     - uses: iamgio/quarkdown/.github/actions/setup-environment@main
 
-    - name: Setup Chrome
-      uses: browser-actions/setup-chrome@v1.7.3
-      id: setup-chrome
-
     - name: Build distribution
       uses: burrunan/gradle-cache-action@v3
       with:

.gitignore

@@ -111,4 +111,5 @@ nb-configuration.xml
 .claude/*
 !.claude/skills/
 *.log
-**/_test/
+**/_test/
+docs/superpowers/

CHANGELOG.md

@@ -21,6 +21,14 @@ The new `callouts` argument of the `.code` function attaches numbered markers to
 
 ### Changed
 
+#### PDF export without Node.js [ecosystem breaking change]
+
+Exporting to PDF no longer requires Node.js, npm, and Puppeteer. Quarkdown now communicates directly with a Chromium-family browser, which makes PDF generation faster to start and much simpler to set up.
+
+Package manager installations download a headless Chrome shell automatically. If you installed Quarkdown manually, download it from the [Chrome for Testing](https://googlechromelabs.github.io/chrome-for-testing/) page, or point Quarkdown to an existing Chromium-family installation with the new `--chrome-path` option or the `QD_CHROME_PATH` environment variable.
+
+> Migration note: the `--node-path` and `--npm-path` options, along with the `QD_NPM_PREFIX` and `NODE_PATH` environment variables, are no longer used. `quarkdown doctor env` now reports the browser's status.
+
 #### Reflectionless function calls
 
 Calling a native function no longer involves JVM reflection, improving performance (the official wiki now compiles 10% faster) on function-heavy documents and opening the door to future optimizations.

CLAUDE.md

@@ -5,7 +5,7 @@ This is the Quarkdown project. Quarkdown is a:
 - Typesetting system, as an alternative to LaTeX, with high-quality typography and layout customization
 - Compiler, parser and renderer to:
   - HTML
-  - PDF (via Puppeteer)
+  - PDF (via a headless Chromium browser)
   - Plain text
 - CLI tool
 
@@ -294,7 +294,7 @@ After the Kotlin extension renders the Quarkdown AST to HTML elements,
 the front-end TypeScript code takes care of interactivity and dynamic features,
 while SCSS files handle styling and layout.
 
-Additionally, Puppeteer is used to generate PDF output from the HTML rendering.
+Additionally, a Chromium-family browser (`chrome-headless-shell`), driven from the JVM over the Chrome DevTools Protocol, is used to generate PDF output from the HTML rendering.
 This lives in the separate, JVM-only [quarkdown-html-pdf](quarkdown-html-pdf) module,
 which decorates the HTML post-renderer and relies on the webserver, located in [quarkdown-server](quarkdown-server).
 
@@ -333,7 +333,7 @@ A layout or color theme can ship sibling assets (e.g. fonts) that travel with it
 
 ## Server
 
-[quarkdown-server](quarkdown-server) is a Ktor-based web server that serves the HTML rendering and allows PDF generation via Puppeteer. The `/preview/<path>` endpoint, used in combination with the CLI's `--preview` and `--watch` options, serves the HTML through a double iframe buffer, allowing for live preview during editing.
+[quarkdown-server](quarkdown-server) is a Ktor-based web server that serves the HTML rendering and allows PDF generation via a headless Chromium browser. The `/preview/<path>` endpoint, used in combination with the CLI's `--preview` and `--watch` options, serves the HTML through a double iframe buffer, allowing for live preview during editing.
 
 ## Testing
 

Dockerfile

@@ -1,3 +1,7 @@
+# Version of the headless browser bundle used for PDF export.
+# To keep in sync with quarkdown-html-pdf/scripts/chrome-version.txt, the version shared with the installers.
+ARG HEADLESS_SHELL_VERSION=151.0.7922.109
+
 # Build stage via Gradle
 FROM gradle:8.14.3-jdk17 AS builder
 
@@ -25,13 +29,20 @@ WORKDIR build/distributions
 RUN unzip quarkdown.zip && rm quarkdown.zip
 
 # Run stage
-FROM ghcr.io/puppeteer/puppeteer:24.15.0 AS runner
+FROM docker.io/chromedp/headless-shell:${HEADLESS_SHELL_VERSION} AS runner
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates fontconfig fonts-liberation \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m quarkdown
+USER quarkdown
 
-ENV QD_NPM_PREFIX="/home/pptruser" \
-    NODE_PATH="/home/pptruser/node_modules" \
-    PUPPETEER_CACHE_DIR="/home/pptruser/.cache/puppeteer"
+ENV QD_CHROME_PATH="/headless-shell/headless-shell" \
+    QD_NO_SANDBOX="true"
 
-USER pptruser
 WORKDIR /app
 COPY --from=builder /app/build/distributions/quarkdown quarkdown
 ENV PATH="/app/quarkdown/bin:${PATH}"

README.md

@@ -287,7 +287,7 @@ curl -fsSL https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/h
 ```
 
 Root privileges let the script install Quarkdown into `/opt/quarkdown` and its wrapper script into `/usr/local/bin/quarkdown`.  
-If missing, Node.js will be installed automatically using the system's package manager.
+The browser required for PDF export is installed automatically.
 
 For more installation options, check out [get-quarkdown](https://github.com/quarkdown-labs/get-quarkdown).
 
@@ -324,7 +324,7 @@ or build it with `gradlew installDist`.
 Optionally, adding `<install_dir>/bin` to your `PATH` allows you easier access Quarkdown.
 
 Requirements:
-- (Only for PDF export) Node.js, npm, Puppeteer. See [*PDF export*](https://quarkdown.com/wiki/pdf-export) for details.
+- (Only for PDF export) A Chromium-family browser, such as `chrome-headless-shell`. See [*PDF export*](https://quarkdown.com/wiki/pdf-export) for details.
 
 </details>
 

build.gradle.kts

@@ -413,6 +413,16 @@ distributions.main {
             }
             includeEmptyDirs = false
         }
+        // Browser installation scripts, invoked by package managers and installers.
+        into("scripts") {
+            from(project(":quarkdown-html-pdf").file("scripts")) {
+                include("*.sh", "*.ps1")
+                filePermissions { unix("rwxr-xr-x") }
+            }
+            from(project(":quarkdown-html-pdf").file("scripts")) {
+                include("chrome-version.txt")
+            }
+        }
     }
 }