feat: Added pdfPrintBackground setting (#9742)

Added pdfPrintBackground setting to include background graphics as part of pdf printing. Fixes #9740 #9730
dotnet · Feb 28, 2024 · bebcd35 · bebcd35
1 parent 0f4456d
commit bebcd35
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 8 deletions.
diff --git a/docs/docs/pdf.md b/docs/docs/pdf.md
@@ -79,6 +79,10 @@ Indicates whether to include a "Table of Contents" pages at the beginning.
 
 A path to an HTML page relative to the root of the output directory. The HTML page will be inserted at the beginning of the PDF file as cover page.
 
+### `pdfPrintBackground`
+
+Indicates whether to include background graphics when rendering the pdf.
+
 ### `pdfHeaderTemplate`
 
 HTML template for the print header. Should be valid HTML markup with following HTML elements used to inject printing values into them:
@@ -126,7 +130,7 @@ See [this example](https://raw.githubusercontent.com/dotnet/docfx/main/samples/s
 ![Alt text](./media/pdf-cover-page.png)
 
 ### Customize TOC Page
- 
+
 When `pdfTocPage` is `true`, a Table of Content page is inserted at the beginning of the PDF file.
 
 ![Alt text](media/pdf-toc-page.png)

diff --git a/src/Docfx.App/PdfBuilder.cs b/src/Docfx.App/PdfBuilder.cs
@@ -39,6 +39,7 @@ class Outline
         public bool pdf { get; init; }
         public string? pdfFileName { get; init; }
         public bool pdfTocPage { get; init; }
+        public bool pdfPrintBackground { get; init; }
         public string? pdfCoverPage { get; init; }
 
         public string? pdfHeaderTemplate { get; init; }
@@ -139,7 +140,7 @@ IResult TocPage(string url)
             return Results.Content(TocHtmlTemplate(new Uri(baseUrl!, url), pdfTocs[url], pageNumbers).ToString(), "text/html");
         }
 
-        async Task<byte[]?> PrintPdf(Uri url)
+        async Task<byte[]?> PrintPdf(Outline outline, Uri url)
         {
             await pageLimiter.WaitAsync();
             var page = pagePool.TryTake(out var pooled) ? pooled : await context.NewPageAsync();
@@ -164,7 +165,7 @@ IResult TocPage(string url)
                     Logger.LogWarning($"Timeout waiting for page to load, generated PDF page may be incomplete: {url}");
                 }
 
-                return await page.PdfAsync();
+                return await page.PdfAsync(new PagePdfOptions { PrintBackground = outline.pdfPrintBackground });
             }
             finally
             {
@@ -215,7 +216,7 @@ static string ExpandTemplate(string? pdfTemplate, int pageNumber, int totalPages
     }
 
     static async Task CreatePdf(
-        Func<Uri, Task<byte[]?>> printPdf, Func<Outline, int, int, Task<byte[]>> printHeaderFooter, ProgressTask task,
+        Func<Outline, Uri, Task<byte[]?>> printPdf, Func<Outline, int, int, Task<byte[]>> printHeaderFooter, ProgressTask task,
         Uri outlineUrl, Outline outline, string outputPath, Action<Dictionary<Outline, int>> updatePageNumbers)
     {
         var tempDirectory = Path.Combine(Path.GetTempPath(), ".docfx", "pdf", "pages");
@@ -233,7 +234,7 @@ static async Task CreatePdf(
         await Parallel.ForEachAsync(pages, async (item, _) =>
         {
             var (url, node) = item;
-            if (await printPdf(url) is { } bytes)
+            if (await printPdf(outline, url) is { } bytes)
             {
                 lock (pageBytes)
                     pageBytes[node] = bytes;
@@ -283,13 +284,13 @@ await Parallel.ForEachAsync(pages, async (item, _) =>
             if (!string.IsNullOrEmpty(outline.pdfCoverPage))
             {
                 var href = $"/{outline.pdfCoverPage}";
-                yield return (new(outlineUrl, href), new() { href = href });
+                yield return (new(outlineUrl, href), new() { href = href, pdfPrintBackground = outline.pdfPrintBackground });
             }
 
             if (outline.pdfTocPage)
             {
                 var href = $"/_pdftoc{outlineUrl.AbsolutePath}";
-                yield return (new(outlineUrl, href), new() { href = href });
+                yield return (new(outlineUrl, href), new() { href = href, pdfPrintBackground = outline.pdfPrintBackground  });
             }
 
             if (!string.IsNullOrEmpty(outline.href))
@@ -322,7 +323,7 @@ async Task MergePdf()
                 {
                     // Refresh TOC page numbers
                     updatePageNumbers(pageNumbers);
-                    bytes = await printPdf(url);
+                    bytes = await printPdf(outline, url);
                 }
 
                 using var document = PdfDocument.Open(bytes);