PDF: add support for a cover page

[bitbonk]

It would really helpful if there way any way to define custom html for a cover page (that is not the TOC).
It should be put before the TOC and not be included in the page count.
wkhtmltopdf supports this with the cover object.

[vicancy]

Current idea: use naming convention to find cover page cover.html in template. Change logic in https://github.com/dotnet/docfx/blob/dev/src/Microsoft.DocAsCode.HtmlToPdf/ConvertWrapper.cs#L133

[bitbonk]

Looks good to me. It would be cool if we could define custom margins just for the cover page. Not sure if wkhtmltopdf support this (wkhtmltopdf/wkhtmltopdf#3635).

[bitbonk]

If (once) wkthmltopdf supports custom margins for the cover page, the easiest way to support this in docfx is to set the magines for the cover page to 0. This would allow the user to fully control the margins via CSS.

[arthurnardy]

Hello there,

Currently working on a documentation using DocFx and PDF generator. The feature here asked for would be helpful to me. Was it implemented yet ? I see the topic is still set to "open".

Kind regards.

[superyyrrzz]

FYI @partychen

[icnocop]

I created PR #4342 which implements this feature request.

Basically, if cover.md is found in a folder (included as a Content file in docfx.json), it will be rendered as the cover page.

It doesn't get passed as the cover to wkhtmltopdf, it just gets put before all the other HTML files during processing.

There's currently no support for setting the margins of the page here, but this is what I'm currently doing after the PDF is generated by DocFx:

1. Run the following command to generate a PDF of just the cover page:
   wkhtmltopdf.exe -B 0mm -L 0mm -R 0mm -T 0mm cover.html cover.pdf
2. Replace the cover page in the PDF generated by DocFx with the new cover page generated without margins using PDFSharp:

        private static void ReplaceCoverPage(
            string inputPdfFilePath,
            string newPdfFilePath,
            string outputFilePath)
        {
            PdfDocument inputPdfDocument = PdfReader.Open(inputPdfFilePath);
            PdfDocument coverPdfDocument = PdfReader.Open(newPdfFilePath, PdfDocumentOpenMode.Import);

            // get the new page
            PdfPage newCoverPage = coverPdfDocument.Pages[0];

            // remove old cover page
            inputPdfDocument.Pages.RemoveAt(0);

            // insert new cover page
            PdfPage coverPage = inputPdfDocument.InsertPage(0, newCoverPage);

            // update the page reference to the cover page in the document outline
            PdfOutlineCollection outlines = inputPdfDocument.Outlines;
            outlines[0].DestinationPage = coverPage;

            // save
            inputPdfDocument.Save(outputFilePath);
        }

This works for me because:

1. My cover page is only one page long.
2. There are no links to other pages in the cover page.

[icnocop]

PR #4342 was merged and so I think this issue should be closed.

cover.html.primary.tmpl was added to the default pdf template which is simplistic but can easily be customized.

To use the default cover template, here's a sample cover.md that needs to be placed alongside toc.yml:

---
documentType: cover
---
# My custom cover page title

The generated cover.html doesn't get passed to wkhtmltopdf using the cover parameter.

For new feature requests like having custom margins only for the cover page, it would be best to create a new issue.