Putting a PDF cover and TOC in the right order

[scott-ainsworth]

I have been trying to build a PDF, but cannot find a way to put the cover page and table of contents (TOC) in the right order, that is: cover, TOC, ...

This challenge stems from that fact that the cover page needs to be available on the generated web site and also included as the first item in the toc.yml file. For example:

items:
  - name: Cover
    href: cover.md
  - name: Chapter 1
    href: chapter-1.md

Things I have tried:

• Generating the PDF with pdfTocPage: true, yields this page order: TOC, Cover, Chapter 1, which places cover and TOC are out of order.

• Generating the PDF with pdfTocPage: true and pdfCoverPage: cover.html, yields this page order: Cover, TOC, Cover, Chapter 1, duplicating Cover.

• Using CSS to hide the second cover page is possible, but yields an undesired blank page.

• Finally, removing the cover from the generated toc.json file produces the desired page order: Cover, TOC, Chapter 1.

Questions:

1. What other solutions have you used to order PDF pages?

2. Is it worth considering an extension to the Docfx schema that allows items to be tagged for a particular purpose? For example:

items:
  - name: Cover
    href: cover.md
    xxxx: pdfOnly
  - name: Chapter 1
    href: chapter-1.md

3. Or, how about a Docfx schema extension that says, "put the TOC here". This would also allow placing additional front matter ahead of the TOC. For example:

items:
  - name: Cover
    href: cover.md
  - name: Forward
    href: forward.md
  - xxxx: put-toc-here
  - name: Chapter 1
    href: chapter-1.md

Of course, #2 and #3 will impact toc.json. Either the consuming code will need to be modified for the changes, or a second, pdf-specific equivalent (pdf.json?) would be required.

Edits: correct grammar and typos

[yufeih]

The pdfCoverPage property should do the trick, see this example.

[scott-ainsworth]

@yufeih: Unfortunately, while pdfcoverPage adds the cover page, since the cover page is also in toc.yml, it shows up twice in the PDF. Once before the TOC and again after. (I indicated this in my original post, but dropped an accent grave (`), so it kind of got lost.
Tx, Scott

[scott-ainsworth]

I found a workaround. after running docfx build, A short script

• removes the cover pages form the toc.json files,
• builds the PDFs,
• puts the cover pages back.