New PDF Engine does not seem to work

[groogiam]

Describe the bug
I am attempting to follow the documentation for the new PDF engine here gttps://dotnet.github.io/docfx/docs/pdf.html. The documentation references a "Download PDF" but after following the instructions and updating my docfx.json file one does not appear after rebuilding.

To Reproduce
Steps to reproduce the behavior:

Added to my docfx.json

{
  "build": {
    "globalMetadata": {
      "pdf": true
    }
  }
}

Then ran

docfx build docfx.json -s

The site builds with no errors and I can open it in my browser but there is no Download PDF button.

Expected behavior
The "Download PDF" button should show as per the documentation.

Context (please complete the following information):

• OS: Windows 10 Pro
• Docfx version: 2.73.1+1d7b96c23465e14eafbcb0dd765029a87b5312d4

Additional context
Add any other context about the problem here.

[groogiam]

After some playing around it does seem to be generating multiple pdf files in the background but still no links. I still have several other issues.

1. Is there a way to generate a single pdf document with all the content instead of a bunch of one off pdf's. The old engine had this support but it appears this was not accounted for in the new engine.
2. pdfCoverPage metadata does not seem to work. The documentation is a bit unclear. The old engine referenced a markdown file in the repository. This seems to reference something from the output but the any pdf title page I generate is not part of the output and I would not want it to show up there.
3. pdfTocPage seems to be adding numbers at the end of the text.

Thanks in advance for your help.

[yufeih]

The "Download PDF link" and TOC page styling is currently only applied to the modern template. Is it feasible to use that template instead?

[groogiam]

@yufeih Thanks for the reply. Using the modern template fixes the link issue and the formatting on the TOC page.

pdfCoverPage metadata does not seem to work. The documentation is a bit unclear. The old engine referenced a markdown file in the repository. This seems to reference something from the output but the any pdf title page I generate is not part of the output and I would not want it to show up there.

Update:

I was able to get this working.

Is there a way to generate a single pdf document with all the content instead of a bunch of one off pdf's. The old engine had this support but it appears this was not accounted for in the new engine.

This still does not seem to be supported and is main pdf use case I have. My documentation is separated into multiple guides that have their own TOC's and the current design does not seem to allow for generating a single documentation PDF that can be distributed offline. Is there any way to support this?

Also I am seeing some strangeness of how the top level pdf is generated. For my rest API section it generates the TOC page and the API docs for the first swagger spec but then all the others are in a different pdf under the rest API folder.

Thanks again for your guidance.

[yufeih]

Docfx builds one PDF per TOC, does it work to create a dedicated TOC for the main PDF and use Nested TOC to embed other TOCs into the main TOC?

[yufeih]

Also I am seeing some strangeness of how the top level pdf is generated

This is because each link in the TOC produces only the PDF for that link, the top level TOC contains only links to the first swagger spec.

[groogiam]

One more additional question is it possible to template the title page to include the some additional data from the toc. I have a generic title page but I would want to possible have a sub header in it to reference the actual guide the user is looking at. E.g. User Guide, Training Guide, API, etc? Thanks.

[yufeih]

By "title page" do you mean the "cover page" or the "TOC Page"? The "TOC Page" is currently not customizable, but other pages can be customized through HTML printing, I'm not so sure about your exact scenario, you might be able to hook up the beforePrint event to include some custom logic that changes the HTML DOM. In any case, you can preview and test your changes by opening the page in the browser and print the HTML page.

[groogiam]

Docfx builds one PDF per TOC, does it work to create a dedicated TOC for the main PDF and use Nested TOC to embed other TOCs into the main TOC?

I am using nested TOC's for my top level. It only generates the first article for the nested TOC's but not the rest. That is the strangeness I was talking about.

By "title page" do you mean the "cover page" or the "TOC Page"? The "TOC Page" is currently not customizable, but other pages can be customized through HTML printing, I'm not so sure about your exact scenario, you might be able to hook up the beforePrint event to include some custom logic that changes the HTML DOM. In any case, you can preview and test your changes by opening the page in the browser and print the HTML page.

Yes I mean the cover page. The issue I am running into is that since I am forced to generate multiple pdf's instead of one I need to have a specific sub cover for each one generated. As the default cover page is shared it only can have a generic title so it makes it hard to tell the various pdf's apart if I were to distribute them outside the html site. I suppose I could try and wire up beforePrint event and generate a title based on the page url, but that seems a little clunky. I'll give it a shot but it might be a nice feature to have some mechanism built into DocFX to that allows for some templating and parameter passing to the cover page outside of javascript.

Thanks again for your help.

[groogiam]

@yufeih

I looked into the beforePrint option and it does not look like it will work for my use case. There is no way to determine from the page which pdf is actually being generated. It seems like there should be a mechanism built into DocFX to configure the title page per generated document. Let me know your thoughts on this. Thanks.

[groogiam]

@yufeih Any thoughts on a mechanism which would allow customizing the title page for each PDF document. The beforePrint handler does not seem to be able to solve this. Thanks.

[bimCelum]

Hi, I am running into a similar issue as the original poster. I configured the "pdf": true option in global metadata and followed the instructions in https://dotnet.github.io/docfx/docs/pdf.html, but there is no "Download PDF" button in the final output.

I use a customized version of modern template, defined in docfx.json as follows:

"globalMetadata": {
      "_appName": "CELUM Cloud Help Centre",
      "_appFaviconPath": "images/favicon.ico",
      "_appTitle": "CELUM Cloud Help Centre",
      "_appFooter": "<span>© CELUM GmbH</span>",
      "_appLogoPath": "images/logo.png",
      "_appLogoUrl": "/index.html",
      "_disableContribution": "true",
      "_disableNextArticle": "true",
      "_enableSearch": "true",
      "pdf": true
    },
    "fileMetadataFiles": [],
    "template": [
      "default",
      "modern",
      "templates/modern_celum"
    ],

I'm using a bash script to generate a local docker deployment of the docfx project output and added the "docfx pdf command to it, but that produces an error in the script execution, so I removed it again. Here is the original build script:

rm -Rf generated
cd project-structure-multiple || exit
docfx build ./technical/docfx.json --debug
docfx build ./user/docfx.json --debug
docfx build ./docfx.json --debug
docker-compose up -d && docker exec docfx-nginx-1 nginx -s reload

The customized version contains CSS customizations in public/main.css and our devops engineer added login buttons for Azure AD and MS B2C to layout/_master.tmpl. Could these somehow overwrite/push out the PDF button?

The documentation gives no indication of where in the output page the PDF button should be shown. This could be made clearer.

[groogiam]

@bimCelum The Download PDF button should show on the bottom left.

[bimCelum]

thanks. I also noticed that neither the CSS class (pdf-link) nor the entire HTML element that is the "Download PDF" is mentioned anywhere in the docfx project's code (not in the templates or anywhere else) and also not in the docfx installation directory. Shouldn't the skeleton element already be there in the template somewhere and get enabled with the pdf: true property? Or how does that work?

[bimCelum]

My issue is resolved after updating docfx to version 2.75 and sorting out some other template issues. The PDF button now shows up properly.