PDF on Chromium

[yufeih]

The wkhtmltopdf based PDF solution is flawed in many areas:

• PDF template out of sync with the site template: [Bug] separatePages member layout not well supported by PDF  #9331, [Bug] Overwrite files not applied to pdf export #9204, docfx pdf does not generate api docs #8148, Conceptual markdown pages not in generated PDF #7027, PDF generation doesn't consume notes #3446
• Quality issues with the tool: In generated PDF, TOC and cross-reference links often go to the middle of a section instead of top #2446, PDF file dosn't generated correctly because URLs is doesn't decoded #1785, [Bug] no Unicode in PDF? #9329

This is a new PDF solution based on Chromium, by printing PDF files out of HTML pages using the HTML template for ordinary build.

• PDF builder using chrome
• PDF link to bookmarks
• Command integration
• Print media style adjustment
• Download PDF button
• Print cover page
• Config cover page as source path
• TOC page
• TOC page numbers Is there any way to show page numbers in TOC generated in PDF? #7386
• Page numbers PDF: add support for footers and TOC with page numbers #2003
• Optimize Playwright binary size?
• wkhtmltopdf deprecation
• PDF generation perf tune
• Test on default template
• Update docs

[paulushub]

About wkhtmltopdf: This repository has been archived by the owner on Jan 2, 2023. It is now read-only.

Edited: (wanted to verify it myself): Is the Playwright packaged with the releases?

[yufeih]

Playwright isn't packaged today, it is only for testing. If packaged, it would increase the size of published zip releases of each platform from ~60MB to ~100MB, and increase the size of the docfx tool package to 300MB due to redistribution of NodeJS runtime for many platforms.

Dependency on NodeJS isn't a bad thing as we probably need it for #661 and to replace JINT. We can probably set NodeJS as a pre-requisite instead of redistributing it if size is a concern.

[paulushub]

Dependency on NodeJS isn't a bad thing as we probably need it for #661 and to replace JINT.

Actually waiting for this for my solution. The release v2.72.1 does not include the usual binary. Is this intentional?

[yufeih]

Dependency on NodeJS isn't a bad thing as we probably need it for #661 and to replace JINT.

Actually waiting for this for my solution. The release v2.72.1 does not include the usual binary. Is this intentional?

No, there are some problems with NuGet.org's signing key setup causing publish failures that I need to consult their support. Obviously, they work on a different time-zone so it could take a while.

[filzrev]

If packaged, it would increase the size of published zip releases of each platform from ~60MB to ~100MB, and increase the size of the docfx tool package to 300MB due to redistribution of NodeJS runtime for many platforms.

I'm using Docfx.App NuGet package and it's undesirable to increasing package size.
(Though It might be possible to excluding playwright assets via PackageReference)

Is is hard to separate PDF generation functionality to separate docfx-pdf.exe process.
And docfx.exe's docfx pdf command operations are delegated to that process like dotnet-tools.

[yufeih]

It only affect the size of the docfx package not the size of Docfx.App.

[filzrev]

It only affect the size of the docfx package not the size of Docfx.App.
I've intended output bin size that referencing Docfx.App NuGet package.
It increase bin size about ~60MB to ~100MB as noted above.

It's desirable to use pre-installed node runtime.
(It's planned at microsoft/playwright-dotnet#1850)

Additionally latest docfx main branch build consume twice as much disk space as before. (about 5GB increased)
Because .playwright resources are separately included by following output combinations.

• Projects
  • docfx
  • docfx.App
  • docfx.Tests
  • docfx.Snapshot.Tests
• TargetFrameworks
  • net6.0
  • net7.0
  • net8.0
• Configuration
  • Debug
  • Release

Note:
It might not be a problem on Dev Drive environment.
Because CopyOnWrite feature exists.

[paulushub]

Issue: API Page
Namespace links points to localhost.

[yufeih]

Issue: API Page Namespace links points to localhost.

Seems to be caused by 404s on the pages themselves.

[paulushub]

Task: Optimize Playwright binary size?
Since DocFX is plugin based, will it be possible to only install the playwright when needed?

[yufeih]

The biggest size factor is the redistrbution of NodeJS for 4 platforms in Playwright dotnet: microsoft/playwright-dotnet#1850

At this moment, I tend to leaning on Playwright team fixing the issue using approaches such as using system-wide NodeJS or dynamically install NodeJS

[paulushub]

We know this is going to be difficult. For MS (on GitHub and Azure), more time used is better business.
For developers we need to cut this time also for better business.
Hope tools like DocFX make the right choice to avoid fragmentation.

Since this playwright is bringing in quiet a baggage, defining the PDF build interfaces with implementations
through Playwright and others might be a good compromise in my view.
I am looking at other options including WeasyPrint, but will also require NodeJs
for the conversion of mermaid-js graphics. WeasyPrint depends on GTK, no simple road but having a choice
is better.

Here are samples pdf output of the MkDocs's pdf-plugin using the WeasyPrint:

• https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs-material/document.pdf
• https://github.com/orzih/mkdocs-with-pdf/blob/master/samples/mkdocs/document.pdf

Not that bad in my view!