kernoeb / docker-docsify-pdf Goto Github PK

View Code? Open in Web Editor NEW

19.0 2.0 5.0 2.1 MB

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

JavaScript 88.54% HTML 3.45% Dockerfile 6.36% Shell 1.64%

pdf markdown docsify toc table-of-contents docker

docker-docsify-pdf's Introduction

Docker Docsify PDF

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

Usage

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

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

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 ↩

docker-docsify-pdf's People

Contributors

Stargazers

Watchers

Forkers

harish879 optimisticquan fishros bvantagelimited

docker-docsify-pdf's Issues

hi , why do you need to put this plugin in the docker?

hi , why do you need to put this plugin in the docker?
can it work like a original plugin?

SVG image files are not displayed.

The following text fails to load the image. This approach is apparently required for displaying SVG files.

### High-Level System Landscape

### Sequence
<img src="_generated/wsd/svg/structurizr-1-Taxonomy.svg" />

await puppeteer.launch freezes

I was not able to generate a PDF.

After some debug, I found out that puppeteer.launch was freezing (src/render.js).

The work around is to add args: ['--single-process'] to the options (as pointed out in puppeteer/puppeteer#1409 (comment)).

  const browser = await puppeteer.launch({
    args: ['--single-process'],
    defaultViewport: {
      width: 1200,
      height: 1000,
    }

Should this be added to the troubleshooting section?

Fell free to close the issue. Maybe it is just my setup. But it will be here if others have the same problem.

Why latest docker image isn't the main ?

All is in the title 😄

Export a subset of the documentation

Hello,

Is there a way to export only a subset of the documentation ?
I think it could be interesting to have a file listing which pages to exclude (a docsify-pdf.ignore for example)

PlantUML (puml) files are not displayed

My command:

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)/pdf/my-cover.pdf:/home/node/resources/cover.pdf:ro \
 -e "PDF_OUTPUT_NAME=my-doc.pdf" \
 ghcr.io/kernoeb/docker-docsify-pdf:main

If I remove following line it's OK:

[do_make_fdisp](./plantuml/do_make_fdisp.puml ':include :type=code plantuml')

Originally posted by @EchoPouet in #1 (comment)

Included files cause blank PDF

Hi,
I have the following line in my markdown file:
[filename](ressources/diagrams/my_markdown.md ':include')

ressources/diagrams/my_markdown.md file exist under docs folder
docsify serve command work well
Site is displayed without issue
When docker-docsify-pdf is launched the docker to create a blank PDF (juste the cover)
When i remove the line, the PDF generation is back to normal (no problem)

I followed this documentation:
https://docsify.js.org/#/embed-files

Link in the document are broken in the PDF

Hi,
Another issue i just found

On docsify with serve we specify the link for example:
[My link](/messages?id=test) to access #test title
On the pdf i neet to put:
[My link](#test) for the link to work

Do you have an idea how i can write this same link on both format ? It is an issue ?

File not found in subdirectory

Hello, I think that the subdirectories aren't supported.

My _sidebar.md is:

<!-- docs/_sidebar.md -->

* [Home](/)
* [Tutorials](/Tutorials/)
  * [Documentation](/Tutorials/Documentation/Contribute.md)
* [Installation](/Installation/)
  * [Docker setup](/Installation/Docker-setup.md)
  * [Mount the sources](/Installation/Mount-the-sources.md)
* [Contact](/Contact.md)
* [Doxygen](/Doxygen.md)

And the convertor's result is:

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
fixuid: fixuid should only ever be used on development systems. DO NOT USE IN PRODUCTION
fixuid: updating user 'node' to UID '977293986'
fixuid: updating group 'node' to GID '977273345'
fixuid: recursively searching path /home/node/pdf
fixuid: recursively searching path /home/node/.static
fixuid: chown /home/node/.static
fixuid: recursively searching path /home/node/resources
fixuid: chown /home/node/resources
fixuid: chown /home/node/resources/css
fixuid: chown /home/node/resources/css/vue.css
fixuid: chown /home/node/resources/js
fixuid: chown /home/node/resources/js/docsify.js
fixuid: chown /home/node/resources/js/icons.js
fixuid: chown /home/node/resources/js/prism-bash.min.js
fixuid: chown /home/node/resources/js/prism-json.min.js

INFO:
/home/node/resources/js/docsify.js,/home/node/resources/js/icons.js,/home/node/resources/js/prism-bash.min.js,/home/node/resources/js/prism-json.min.js


INFO:
Build with settings:

{
  pathToStatic: '.static',
  mainMdFilename: 'main.md',
  pathToPublic: 'pdf/DOCUMENTATION.pdf',
  contents: 'docs/_sidebar.md',
  pathToDocsifyEntryPoint: '.',
  cover: 'resources/cover.pdf'
}



ERROR:
combineMarkdowns

Error: file /Tutorials/Documentation/Contribute.md is not exist, but listed in docs/_sidebar.md



ERROR:
run error

Error: file /Tutorials/Documentation/Contribute.md is not exist, but listed in docs/_sidebar.md

Also, [Tutorials](/Tutorials/) hasn't file name because by default the README.md file is taken (/Tutorials/README.md).