whatap-docs-prince-pdf

v1.2.4

Published

10 months ago

Extract rendered data from Docusaurus and generate PDF, the hard way

0High
0Medium
0Low

kj.im

Docusaurus Prince PDF Generator

Extract rendered data from Docusaurus/Fumadocs/etc and generate PDF, the hard way

Demo/Examples

You can download it in GitHub Actions artifacts section to see the result.

This project is using the method 1 (see below) for generating PDF. You must have Prince installed on your local machine.

Usage

Install Prince first.

Run the following commands to generate PDF:

# Genrate PDF from specific site under `docs` scope
npx docusaurus-prince-pdf -u https://docusaurus.io/docs

# Change generating scope to `/docs/cli/`
npx docusaurus-prince-pdf -u https://docusaurus.io/docs/cli

# Custom working (output) directory
npx docusaurus-prince-pdf -u https://openbayes.com/docs --dest ./pdf-output

# Custom output file name
npx docusaurus-prince-pdf -u https://openbayes.com/docs --output docs.pdf

To generate PDF from a local Docusaurus instance. You need to first build the site locally:

# Build the site
(npm|bun|yarn|pnpm) build

# Serve built site locally
(npm|bun|yarn|pnpm) serve

# Generate PDF from local Docusaurus instance
npx docusaurus-prince-pdf -u http://localhost:4000/docs # Change port to your serving port

Docker

You can run this program with Docker image:

docker run --rm -it --init \
  -v $(pwd)/pdf:/app/pdf \
  openbayes/docusaurus-prince-pdf \
  -u https://docusaurus.io/docs/

If you need Asiatic languages support like Chinese and Japanese. You can mount your custom fonts directory to Docker image:

docker run --rm -it --init \
  -v $(pwd)/pdf:/app/pdf \
  -v $(pwd)/fonts:/root/.fonts \
  openbayes/docusaurus-prince-pdf \
  -u https://docusaurus.io/docs/

GitHub Actions

You can also run this program inside GitHub Actions:

jobs:
  build:
    # prerequisites...

    - name: Install Prince
      run: |
        curl https://www.princexml.com/download/prince-14.2-linux-generic-x86_64.tar.gz -O
        tar zxf prince-14.2-linux-generic-x86_64.tar.gz
        cd prince-14.2-linux-generic-x86_64
        yes "" | sudo ./install.sh

    - name: Build PDF
      run: npx docusaurus-prince-pdf -u https://docusaurus.io/docs/

    - name: Upload results
      uses: actions/upload-artifact@v3
      with:
        name: result
        # The output filename can be specified with --output option
        path: pdf/docusaurus.io-docs.pdf
        if-no-files-found: error

    # ...other steps

You can also run prince with prebuilt Prince Docker image:

jobs:
  build:
    # prerequisites...

    - name: Build PDF
      run: docker run --rm -it -v $(pwd)/pdf:/app/pdf openbayes/docusaurus-prince-pdf -u https://docusaurus.io/docs/

    # ...other steps

Development

You need to have Bun installed first. This can also let you run latest code on your local machine.

bun run index.ts -u http://localhost:4000/docs

Options

--url (-u): Base URL, should be the baseUrl of the Docusaurus instance (e.g. https://docusaurus.io/docs/)
--selector (-s): CSS selector to find the link of the next page
--dest (-d): Working directory. Default to ./pdf
--file (-f): Change default list output filename
--output (-o): Change PDF output filename
--include-index: Include passed URL in generated PDF
--prepend: Prepend additional pages, split with comma
--append: Append additional pages, split with comma
--prince-args: Additional options for Prince. ie. --prince-args="--page-size='210mm 297mm'" or --prince-args "\\-\\-page\\-size='210mm 297mm'"
--prince-docker: Use external Prince docker image to generate PDF. See https://github.com/sparanoid/docker-prince for more info
--list-only: Fetch list without generating PDF
--pdf-only: Generate PDF without fetching list. Ensure list exists
--cookie: Specify the cookie with the domain part, e.g. --cookie="token=123456; domain=example.com;"

How it works

Like mr-pdf, this package looks for the next pagination links on generated Docusaurus site. Collect them in a list and then pass the list to Prince to generate the PDF.

You can specify the CSS selector if you're using custom Docusaurus theme:

npx docusaurus-prince-pdf -u https://openbayes.com/ --selector 'nav.custom-pagination-item--next > a'

Does it work with Fumadocs or other static site/docs generators?

It should work with any static site/docs generators that have consistent pagination links.

For Fumadocs, you can use the same method to generate the PDF using custom selector like this:

npx docusaurus-prince-pdf -u https://fumadocs.vercel.app/docs/ui --selector '#nd-page > article > div.grid.grid-cols-2.gap-4.pb-6 a:last-child'

The Tailwind-styled selector is not elegant but it works.

Why this package?

I made a comparison list for the two methods of generating PDF from Docusaurus.

Method 1: Prince

The good:

Best font subsetting support
Text can be selected and copy/paste correctly
Fancy Table of Contents

The bad:

Watermark on first page of generated PDF make it hard to handle in CI/CD environments
Doesn't work with some CSS syntax (e.g. mask-image)
Doesn't work with some HTML features (e.g. srcset)
Commercial license is expensive ($3,800)

The ugly:

None

Method 2: mr-pdf (not used in this project)