pdf support - Githubissues

catherine-leung commented 2 years ago

One of the early conversations we had about using docusaurus was that it had pdf support but we do not seem to have added this.

I have tried pdf-prince plugn and it does not seem to work for our version of the notes... so something is not quite working right. However, I cannot figure out what it is.

The error is that there is no "next" link .. but there clearly is a next link. at the html level it looks the same as that on docusaurus site.. has anyone else tried this?

catherine-leung commented 2 years ago

updating to docusaurus version 21 (latest) seems to solve this problem. Tried this when trying to fix #13

catherine-leung commented 2 years ago

I think the solution to this should involve automatic pdf generation in the deployment script... This will at least allow us to have a link to it. A better way is to have a link to the pdf as part of what we generate in docusaurus.

CameronGray1210 commented 2 years ago

@catherine-leung : we hit a snag on the PDF generation which is why I left it out of the template until a fix can be found. We had it was set up to auto generate the PDF when publishing the site (workflow action), however, it failed to generate images correctly (mostly it missed most of them - it seems to be a bug in the pre-caching of the images or a timeout in the generation of them in the injection into the PDF). The 3rd party module used was Mr. PDF (https://www.npmjs.com/package/mr-pdf) which supports a beta version for Docusaurus 2.0.

You can review the "Intro2C" repo (workflow) to see where/how this was done.

I'm not familiar with the PDF tool you mentioned - It sounds more promising. This needs to be further investigated. If the add-on you tried supports Docusaurus 2.0, then that is probably a better one to consider - but it needs to be tested on a built out OER (like Intro2C) to determine if it renders the images in a larger sample.

Upgrading Docusaurus to build 21 shouldn't be an issue - but also requires testing to know for sure - if you did this update with the Template an nothing broke, then I'd say it should be fine (and I'd like to keep it as up-to-date as possible anyway). If we can keep the Template up-to-date, it will likely have better support for newer 3rd party add-ons. We don't have a lot of add-ons and we must be mindful to keep this to a minimum this way when we do these kinds of upgrades, testing shouldn't be too extensive to know if it breaks anything.

catherine-leung commented 2 years ago

@CameronGray1210 that is not the plugin I used because it said that it doesn't work with docusaurus 2.0+. Instead I used prince-pdf which also looked better.

https://github.com/signcl/docusaurus-prince-pdf

I just tried using it on the docusaurus site and it looked like images was properly created. But yes, I agree we should test it out before we make it official. we can do this without adding it to deployment but docusaurus must be upgraded to latest version for it to work. Did not work on OERTemplate site until I did upgrade.

Also... I think the testing thing is something we should consider addressing in the template repo itself. We should add a test page. See #15

CameronGray1210 commented 2 years ago

@catherine-leung : That sounds very encouraging - David's student's came up with the using of Mr. PDF I suppose other plugins were not stating any support for V2.0 so they suggested the usage of Mr. PDF since it at least has a beta for V2.0.

If your testing seems to work than that is very encouraging. I'll have to test it though with IPC's OER to see if it get's through the images. I know the TOC in the prince-PDF is handled much better (I truly disliked Mr. PDF's!). So I hope it will work. I'll try to test it sometime in the next 2-weeks and let you know.

YES: definitely a good idea to create a single test page for future testing. It should address most testing (except the PDF thing since It seems it's more volume and number of images that I need to test for that).

catherine-leung commented 2 years ago

@CameronGray1210

Did some more digging. To use prince-pdf, we must use prince locally. A non commercial license will work and it is free (as in beer). However, we must put a link to prince back to its site, and add them to any sort of partners list we have (perhaps contributor list?)

Here is the relevant section from the Prince site:

Is the Prince Non-commercial License really free?

    Yes.
Can be used on a server?

    Yes.
So what's the catch?

    There's a logo in the upper right corner on the first page of generated PDF files. You are not allowed to remove the logo (e.g., by removing the first page of the PDF file) or assist or encourage others to remove it.

    Also, you must place prominent links to http://www.princexml.com/ on your Web site, at the places the PDF documents are served and in a page listing your partners. If you send the PDF documents in email, the message body must contain our URL.

    Prince and the Generated PDFs must be used for non-commercial purposes (see follow up questions).
Does my organization qualify for the Non-commercial License?

    The license doesn't distinguish between commercial and non-commercial organizations. Instead, it distinguishes between commercial and non-commercial purposes. This is the key sentence from the license:

        "Non-commercial Purposes" means the production of documents (a) for which no fees are charged, and (b) which are not part of a monetary transaction system (such as, but not limited, to invoices and receipts), and (c) for which no other income (such as, but not limited to, subscription fees, income from advertising, or sale of consumables) is generated. 

So, even commercial organizations can use the Non-commercial License as long as they use it for non-commercial purposes?

    Correct. For example, a newspaper may offer PDF versions of their articles using the Non-commercial License; as long as the articles are offered at no cost without any advertising.

It looks like this describes us because we are not generating any fees out of the notes, nor is it something they can access only via being enrolled in the course. I don't see big problem with watermark and putting a link up seems reasonable to me. Let me know what you think.

CameronGray1210 commented 2 years ago

Yes - I noticed this before when first looking at it - we are definitely good to use it and I also don't see any issue with promoting the product - it is after all the only contender that seems to work!
Including in contributors.md is good too.

catherine-leung commented 2 years ago

I've been thinking about how to automate this with deployment. Here are my thoughts: 1) We need a place in pages for the pdf, we can link to it from the intro.md table of contents page. As long as the pdf is generated and placed in same place each time, the link should continue to work 2) We need to automate deployment to generate the pdf... this will require more research as I've only ever done this locally.

catherine-leung commented 1 year ago

I have a working solution for this on my data structures repo now. The following steps were added to the gh-release action:

pull the gh-pages branch
generate the pdf
push pdf into gh-pages branch

Other than that:

To the front of page add a link that will link the pdf (the path will be static as the new pdf will be placed in the same place in each build
Add link to the pdf generator as per their non-commercial license

I'd like to add this to the template... but wondering about the implications of this.

Seneca-ICTOER / OERTemplate

pdf support #12