feat: support PDF toc page (#9356)

* feat: support PDF toc page

* test(snapshot): update snapshots for eee69ff

---------

Co-authored-by: yufeih <yufeih@users.noreply.github.com>

Author: yufeih

samples/seed/docfx.json

@@ -81,7 +81,8 @@
       "_appTitle": "docfx seed website",
       "_appName": "Seed",
       "_enableSearch": true,
-      "pdf": true
+      "pdf": true,
+      "pdfTocPage": true
     },
     "output": "_site",
     "exportViewModel": true,

src/Docfx.App/PdfBuilder.cs

@@ -6,9 +6,11 @@
 using System.Text;
 using System.Text.Json;
 using System.Text.RegularExpressions;
+using Docfx.Build;
 using Docfx.Plugins;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.Logging;
 using Microsoft.Playwright;
 using Spectre.Console;
@@ -19,6 +21,8 @@
 using UglyToad.PdfPig.Outline.Destinations;
 using UglyToad.PdfPig.Writer;
 
+using static Docfx.Build.HtmlTemplate;
+
 #nullable enable
 
 namespace Docfx.Pdf;
@@ -34,6 +38,7 @@ class Outline
         public bool pdf { get; init; }
         public string? pdfFileName { get; init; }
         public string? pdfCoverPage { get; init; }
+        public bool pdfTocPage { get; init; }
     }
 
     public static Task Run(BuildJsonConfig config, string configDirectory, string? outputDirectory = null)
@@ -47,8 +52,8 @@ public static Task Run(BuildJsonConfig config, string configDirectory, string? o
 
     public static async Task CreatePdf(string outputFolder)
     {
-        var pdfTocs = GetPdfTocs().ToArray();
-        if (pdfTocs.Length == 0)
+        var pdfTocs = GetPdfTocs().ToDictionary(p => p.url, p => p.toc);
+        if (pdfTocs.Count == 0)
             return;
 
         AnsiConsole.Status().Start("Installing Chromium...", _ => Program.Main(new[] { "install", "chromium" }));
@@ -58,10 +63,14 @@ public static async Task CreatePdf(string outputFolder)
         builder.Logging.ClearProviders();
         builder.WebHost.UseUrls("http://127.0.0.1:0");
 
+        Uri? baseUrl = null;
+
         using var app = builder.Build();
         app.UseServe(outputFolder);
+        app.MapGet("/_pdftoc/{*id}", (string id) => Results.Content(TocHtmlTemplate(new Uri(baseUrl!, id), pdfTocs[id]).ToString(), "text/html"));
         await app.StartAsync();
-        var baseUrl = new Uri(app.Urls.First());
+
+        baseUrl = new Uri(app.Urls.First());
 
         using var playwright = await Playwright.CreateAsync();
         var browser = await playwright.Chromium.LaunchAsync();
@@ -73,7 +82,7 @@ public static async Task CreatePdf(string outputFolder)
             await CreatePdf(browser, new(baseUrl, url), toc, outputPath);
         }
 
-        IEnumerable<(string, Outline)> GetPdfTocs()
+        IEnumerable<(string url, Outline toc)> GetPdfTocs()
         {
             var manifestPath = Path.Combine(outputFolder, "manifest.json");
             var manifest = Newtonsoft.Json.JsonConvert.DeserializeObject<Manifest>(File.ReadAllText(manifestPath));
@@ -141,6 +150,13 @@ await Parallel.ForEachAsync(pages, async (item, CancellationToken) =>
                     yield return (GetFilePath(url), url, new() { href = outline.pdfCoverPage });
             }
 
+            if (outline.pdfTocPage)
+            {
+                var href = $"/_pdftoc{outlineUrl.AbsolutePath}";
+                var url = new Uri(outlineUrl, href);
+                yield return (GetFilePath(url), url, new() { href = href });
+            }
+
             if (!string.IsNullOrEmpty(outline.href))
             {
                 var url = new Uri(outlineUrl, outline.href);
@@ -229,7 +245,7 @@ PdfAction HandleUriAction(UriAction url)
                     AnsiConsole.MarkupLine($"[yellow]Failed to resolve named dest: {name}[/]");
                 }
 
-                return new GoToAction(new(pageNumbers[pages[0].node], ExplicitDestinationType.XyzCoordinates, ExplicitDestinationCoordinates.Empty));
+                return new GoToAction(new(pageNumbers[pages[0].node], ExplicitDestinationType.FitHorizontally, ExplicitDestinationCoordinates.Empty));
             }
         }
 
@@ -249,7 +265,7 @@ IEnumerable<BookmarkNode> CreateBookmarks(Outline[]? items, int level = 0)
                 {
                     yield return new DocumentBookmarkNode(
                         item.name, level,
-                        new(nextPageNumber, ExplicitDestinationType.XyzCoordinates, ExplicitDestinationCoordinates.Empty),
+                        new(nextPageNumber, ExplicitDestinationType.FitHorizontally, ExplicitDestinationCoordinates.Empty),
                         CreateBookmarks(item.items, level + 1).ToArray());
                     continue;
                 }
@@ -268,13 +284,33 @@ IEnumerable<BookmarkNode> CreateBookmarks(Outline[]? items, int level = 0)
                     nextPageNumber = nextPageNumbers[item];
                     yield return new DocumentBookmarkNode(
                         item.name, level,
-                        new(pageNumbers[item], ExplicitDestinationType.XyzCoordinates, ExplicitDestinationCoordinates.Empty),
+                        new(pageNumbers[item], ExplicitDestinationType.FitHorizontally, ExplicitDestinationCoordinates.Empty),
                         CreateBookmarks(item.items, level + 1).ToArray());
                 }
             }
         }
     }
 
+    static HtmlTemplate TocHtmlTemplate(Uri baseUrl, Outline node)
+    {
+        return Html($"""
+            <!DOCTYPE html>
+            <html>
+            <head>
+              <link rel="stylesheet" href="/public/docfx.min.css">
+              <link rel="stylesheet" href="/public/main.css">
+            </head>
+            <body class="pdftoc">
+            <h1>Table of Contents</h1>
+            <ul>{node.items?.Select(TocNode)}</ul>
+            </body>
+            </html>
+            """);
+
+        HtmlTemplate TocNode(Outline node) => string.IsNullOrEmpty(node.name) ? default :
+            Html($"<li><a href='{(string.IsNullOrEmpty(node.href) ? null : new Uri(baseUrl, node.href))}'>{node.name}</a>{(node.items?.Length > 0 ? Html($"<ul>{node.items.Select(TocNode)}</ul>") : null)}</li>");
+    }
+
     /// <summary>
     /// Adds hidden links to headings to ensure Chromium saves heading anchors to named dests
     /// for cross page bookmark reference.

templates/modern/src/docfx.scss

@@ -79,3 +79,7 @@ article {
     margin: .4in;
   }
 }
+
+.pdftoc ul {
+  list-style: none;
+}

test/docfx.Snapshot.Tests/SamplesTest.Seed/api/BuildFromAssembly.Class1.html.view.verified.json

@@ -825,6 +825,7 @@
   "_appTitle": "docfx seed website",
   "_enableSearch": true,
   "pdf": true,
+  "pdfTocPage": true,
   "_key": "obj/api/BuildFromAssembly.Class1.yml",
   "_navKey": "~/toc.yml",
   "_navPath": "toc.html",

test/docfx.Snapshot.Tests/SamplesTest.Seed/api/BuildFromAssembly.html.view.verified.json

@@ -116,6 +116,7 @@
   "_appTitle": "docfx seed website",
   "_enableSearch": true,
   "pdf": true,
+  "pdfTocPage": true,
   "_key": "obj/api/BuildFromAssembly.yml",
   "_navKey": "~/toc.yml",
   "_navPath": "toc.html",

test/docfx.Snapshot.Tests/SamplesTest.Seed/api/BuildFromCSharpSourceCode.CSharp.html.view.verified.json

@@ -742,6 +742,7 @@
   "_appTitle": "docfx seed website",
   "_enableSearch": true,
   "pdf": true,
+  "pdfTocPage": true,
   "_key": "obj/api/BuildFromCSharpSourceCode.CSharp.yml",
   "_navKey": "~/toc.yml",
   "_navPath": "toc.html",

test/docfx.Snapshot.Tests/SamplesTest.Seed/api/BuildFromCSharpSourceCode.html.view.verified.json

@@ -112,6 +112,7 @@
   "_appTitle": "docfx seed website",
   "_enableSearch": true,
   "pdf": true,
+  "pdfTocPage": true,
   "_key": "obj/api/BuildFromCSharpSourceCode.yml",
   "_navKey": "~/toc.yml",
   "_navPath": "toc.html",

test/docfx.Snapshot.Tests/SamplesTest.Seed/api/BuildFromProject.Class1.IIssue8948.html.view.verified.json

@@ -309,6 +309,7 @@
   "_appTitle": "docfx seed website",
   "_enableSearch": true,
   "pdf": true,
+  "pdfTocPage": true,
   "_key": "obj/api/BuildFromProject.Class1.IIssue8948.yml",
   "_navKey": "~/toc.yml",
   "_navPath": "toc.html",

test/docfx.Snapshot.Tests/SamplesTest.Seed/api/BuildFromProject.Class1.Issue8665.html.view.verified.json

@@ -1922,6 +1922,7 @@
   "_appTitle": "docfx seed website",
   "_enableSearch": true,
   "pdf": true,
+  "pdfTocPage": true,
   "_key": "obj/api/BuildFromProject.Class1.Issue8665.yml",
   "_navKey": "~/toc.yml",
   "_navPath": "toc.html",

test/docfx.Snapshot.Tests/SamplesTest.Seed/api/BuildFromProject.Class1.Issue8696Attribute.html.view.verified.json

@@ -2743,6 +2743,7 @@
   "_appTitle": "docfx seed website",
   "_enableSearch": true,
   "pdf": true,
+  "pdfTocPage": true,
   "_key": "obj/api/BuildFromProject.Class1.Issue8696Attribute.yml",
   "_navKey": "~/toc.yml",
   "_navPath": "toc.html",