Skip to content

Docker way to convert Docsify pages to PDF (with Puppeteer)

Notifications You must be signed in to change notification settings

bvantagelimited/docker-docsify-pdf

 
 

Repository files navigation

Docker Docsify PDF

Workflow

This project is based on meff34/docsify-to-pdf-converter repository.

Features

  • Custom icons
  • Codeblocks
  • Table of contents (auto-generated)
  • Multilingual support (multiple sidebars)
  • PDF cover page
  • PlantUML (.puml) diagrams
  • SVG support

All improvements and fixes from original repository are here.

Screenshots

Screenshot 1

Screenshot 2

img.png

Usage

First, create a documentation in a docs directory (like the repository example).
You need a _sidebar.md1.

Pull the image and create output directory :

docker pull ghcr.io/kernoeb/docker-docsify-pdf:latest
mkdir -p $(pwd)/pdf

Run the container (volumes are mandatory) :

docker run --rm -it \
  --cap-add=SYS_ADMIN \
  --user $(id -u):$(id -g) \
  -v $(pwd)/docs:/home/node/docs:ro \
  -v $(pwd)/pdf:/home/node/pdf:rw \
  -v $(pwd)/resources/covers/cover.pdf:/home/node/resources/cover.pdf:ro \
  -e "PDF_OUTPUT_NAME=DOCUMENTATION.pdf" \
  ghcr.io/kernoeb/docker-docsify-pdf:latest

And voilà ! 🎉


You can use zx to generate the PDF in one command : zx README.md.

You can also add custom js files (plugins) :

-v $(pwd)/resources/js/thing.js:/home/node/resources/js/thing.js:ro

All the resources can be replaced (images, css, js, ...) as well
It can be useful if you want to change the CSS theme

The PDF cover is optional : just remove the mapping on the command.

Differences from original repository

  • Fix :
    • Slugify / internal URL (some URLs were not properly encoded)
    • localhost links are now disabled
    • Codeblocks (some code blocks were sliced)
    • Better margins in the final PDF
    • Page breaks between sections
    • If an image was used multiple times in the same section, it was not working
  • Security / performance :
    • Update dependencies (Puppeteer, Docsify, ...)
    • Docker container is running with current user rights (optional)
  • Feats :
    • Table of content (based on sidebar)
    • Custom cover PDF page
    • Docker way to generate PDF
    • Highlight code blocks (with PrismJS)
    • Multilingual support
    • Font Awesome icons support, example : {{fa cog}}
    • PlantUML diagrams support (see the example in docs directory)
    • SVG support
  • Chore :
    • Migration to pnpm (no more npm)
    • Clean code with standard ESLint
    • Remove useless stuff

Troubleshooting

If you have this error : System limit for number of file watchers reached or Error: EMFILE: too many open files :

echo fs.inotify.max_user_watches=1048576 | sudo tee -a /etc/sysctl.conf && sudo sysctl --system
echo fs.inotify.max_user_instances=512 | sudo tee -a /etc/sysctl.conf && sudo sysctl --system

cf. StackOverflow

Footnotes

  1. To change _sidebar.md location (e.g for multi-language support), add -v $(pwd)/docs/de/_sidebar.md:/home/node/docs/_sidebar.md:ro to the command

About

Docker way to convert Docsify pages to PDF (with Puppeteer)

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 88.4%
  • Dockerfile 6.6%
  • HTML 3.4%
  • Shell 1.6%