feat(pdf): Add pdfTocSource option to generate TOC from document headings

Add new configuration options to control PDF Table of Contents source:
- pdfTocSource: 'toc' (default) or 'headings' to extract from document content
- pdfTocHeadingDepth: maximum heading level to include (1-6, default 3)

When pdfTocSource is set to 'headings', the PDF TOC is generated by
extracting h1-h6 headings from the rendered HTML pages instead of using
the toc.yml structure. This is particularly useful for print-style
publications using docfx for markdown-to-PDF generation, where the TOC
should reflect the document's internal heading structure rather than
website navigation.

Fixes #10994

Author: Thomas Sondergaard

docs/docs/pdf.md

@@ -75,6 +75,33 @@ Sets the PDF output file name. The default value is `toc.pdf`.
 
 Indicates whether to include a "Table of Contents" pages at the beginning.
 
+### `pdfTocSource`
+
+Controls the source for the PDF Table of Contents. Possible values:
+
+- `toc` (default): Generates TOC from the `toc.yml` structure.
+- `headings`: Generates TOC from headings (h1, h2, h3, etc.) extracted from document content.
+
+When set to `headings`, the TOC reflects the actual heading structure within each document rather than the navigation defined in `toc.yml`. This is useful for single-document or small documentation sets where you want the PDF TOC to show the internal sections of each document.
+
+```yaml
+pdf: true
+pdfTocPage: true
+pdfTocSource: headings
+items:
+- name: My Document
+  href: my-document.md
+```
+
+### `pdfTocHeadingDepth`
+
+Maximum heading level to include in the PDF TOC when `pdfTocSource` is `headings`. Default is `3`, which includes h1, h2, and h3 headings. Set to a higher value (up to 6) to include deeper heading levels.
+
+```yaml
+pdfTocSource: headings
+pdfTocHeadingDepth: 4  # Include h1-h4 headings
+```
+
 ### `pdfCoverPage`
 
 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.

schemas/toc.schema.json

@@ -106,6 +106,19 @@
           "type": "boolean",
           "default": false,
           "description": "If set to true, Child items are displayed as dropdown on top navigation bar."
+        },
+        "pdfTocSource": {
+          "type": "string",
+          "enum": ["toc", "headings"],
+          "default": "toc",
+          "description": "Source for PDF Table of Contents. 'toc' uses toc.yml structure (default), 'headings' extracts headings from document content."
+        },
+        "pdfTocHeadingDepth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 6,
+          "default": 3,
+          "description": "Maximum heading level to include in PDF TOC when pdfTocSource is 'headings'. For example, 3 includes h1, h2, and h3."
         }
       }
     },

src/Docfx.App/PdfBuilder.cs

@@ -37,6 +37,14 @@ static class PdfBuilder
 {
     private static readonly SearchValues<char> InvalidPathChars = SearchValues.Create(Path.GetInvalidPathChars());
 
+    class HeadingInfo
+    {
+        public string Text { get; init; } = "";
+        public string Id { get; init; } = "";
+        public int Level { get; init; }
+        public Uri PageUrl { get; init; } = null!;
+    }
+
     class Outline
     {
         public string name { get; init; } = "";
@@ -51,6 +59,9 @@ class Outline
 
         public string? pdfHeaderTemplate { get; init; }
         public string? pdfFooterTemplate { get; init; }
+
+        public string? pdfTocSource { get; init; }
+        public int pdfTocHeadingDepth { get; init; } = 3;
     }
 
     public static Task Run(BuildJsonConfig config, string configDirectory, string? outputDirectory = null, CancellationToken cancellationToken = default)
@@ -93,6 +104,8 @@ void onSignal(PosixSignalContext context)
 
         Uri? baseUrl = null;
         var pdfPageNumbers = new ConcurrentDictionary<string, Dictionary<Outline, int>>();
+        var pdfUrlPageNumbers = new ConcurrentDictionary<string, Dictionary<Uri, int>>();
+        var pdfHeadings = new ConcurrentDictionary<string, List<HeadingInfo>>();
 
         using var app = builder.Build();
         app.UseServe(outputFolder);
@@ -127,6 +140,8 @@ void onSignal(PosixSignalContext context)
                 await CreatePdf(
                     PrintPdf, PrintHeaderFooter, task, new(baseUrl, url), toc, outputFolder, pdfOutputPath,
                     pageNumbers => pdfPageNumbers[url] = pageNumbers,
+                    urlPageNumbers => pdfUrlPageNumbers[url] = urlPageNumbers,
+                    headings => pdfHeadings[url] = headings,
                     cancellationToken);
 
                 task.Value = task.MaxValue;
@@ -186,20 +201,23 @@ await CreatePdf(
         IResult TocPage(string url)
         {
             var pageNumbers = pdfPageNumbers.GetValueOrDefault(url);
-            return Results.Content(TocHtmlTemplate(new Uri(baseUrl!, url), pdfTocs[url], pageNumbers).ToString(), "text/html", Encoding.UTF8);
+            var urlPageNumbers = pdfUrlPageNumbers.GetValueOrDefault(url);
+            var headings = pdfHeadings.GetValueOrDefault(url);
+            return Results.Content(TocHtmlTemplate(new Uri(baseUrl!, url), pdfTocs[url], pageNumbers, urlPageNumbers, headings).ToString(), "text/html", Encoding.UTF8);
         }
 
-        async Task<byte[]?> PrintPdf(Outline outline, Uri url)
+        async Task<(byte[]? bytes, List<HeadingInfo> headings)> PrintPdf(Outline outline, Uri url, int headingDepth)
         {
             await pageLimiter.WaitAsync(cancellationToken);
             var page = pagePool.TryTake(out var pooled) ? pooled : await context.NewPageAsync();
+            var headings = new List<HeadingInfo>();
 
             try
             {
                 Uri beforeUri = new(page.Url);
                 var response = await page.GotoAsync(url.ToString(), new() { WaitUntil = WaitUntilState.DOMContentLoaded });
                 if (response?.Status is 404)
-                    return null;
+                    return (null, headings);
 
                 bool isSameUrlNavigation = response == null && beforeUri == url;
                 bool isHashFragmentNavigation = response == null
@@ -234,11 +252,19 @@ IResult TocPage(string url)
                     }
                 }
 
-                return await page.PdfAsync(new PagePdfOptions
+                // Extract headings from the page if needed
+                if (outline.pdfTocSource == "headings" && headingDepth > 0 && !IsTocPage(url) && !IsCoverPage(url, outputFolder, outline.pdfCoverPage))
+                {
+                    headings = await ExtractHeadingsFromPage(page, url, headingDepth);
+                }
+
+                var bytes = await page.PdfAsync(new PagePdfOptions
                 {
                     PreferCSSPageSize = true,
                     PrintBackground = outline.pdfPrintBackground,
                 });
+
+                return (bytes, headings);
             }
             finally
             {
@@ -247,6 +273,45 @@ IResult TocPage(string url)
             }
         }
 
+        async Task<List<HeadingInfo>> ExtractHeadingsFromPage(IPage page, Uri pageUrl, int maxDepth)
+        {
+            var headings = new List<HeadingInfo>();
+            var selector = string.Join(",", Enumerable.Range(1, maxDepth).Select(i => $"article h{i}, .content h{i}"));
+
+            try
+            {
+                var elements = await page.QuerySelectorAllAsync(selector);
+                foreach (var element in elements)
+                {
+                    var tagName = await element.EvaluateAsync<string>("e => e.tagName");
+                    var level = int.Parse(tagName[1].ToString());
+                    var id = await element.GetAttributeAsync("id") ?? "";
+                    var text = (await element.InnerTextAsync()).Trim();
+
+                    // Skip headings without id or text
+                    if (string.IsNullOrEmpty(id) || string.IsNullOrEmpty(text))
+                        continue;
+
+                    // Clean up text (remove source link icons, etc.)
+                    var cleanText = text.Split('\n')[0].Trim();
+
+                    headings.Add(new HeadingInfo
+                    {
+                        Text = cleanText,
+                        Id = id,
+                        Level = level,
+                        PageUrl = pageUrl
+                    });
+                }
+            }
+            catch (Exception ex)
+            {
+                Logger.LogWarning($"Failed to extract headings from {pageUrl}: {ex.Message}");
+            }
+
+            return headings;
+        }
+
         Task<byte[]> PrintHeaderFooter(Outline toc, int pageNumber, int totalPages, Page contentPage)
         {
             var headerTemplate = ExpandTemplate(GetHeaderFooter(toc.pdfHeaderTemplate), pageNumber, totalPages);
@@ -333,32 +398,51 @@ static string ExpandTemplate(string? pdfTemplate, int pageNumber, int totalPages
     }
 
     static async Task CreatePdf(
-        Func<Outline, Uri, Task<byte[]?>> printPdf, Func<Outline, int, int, Page, Task<byte[]>> printHeaderFooter, ProgressTask task,
-        Uri outlineUrl, Outline outline, string outputFolder, string pdfOutputPath, Action<Dictionary<Outline, int>> updatePageNumbers, CancellationToken cancellationToken)
+        Func<Outline, Uri, int, Task<(byte[]? bytes, List<HeadingInfo> headings)>> printPdf, Func<Outline, int, int, Page, Task<byte[]>> printHeaderFooter, ProgressTask task,
+        Uri outlineUrl, Outline outline, string outputFolder, string pdfOutputPath, Action<Dictionary<Outline, int>> updatePageNumbers, Action<Dictionary<Uri, int>> updateUrlPageNumbers, Action<List<HeadingInfo>> updateHeadings, CancellationToken cancellationToken)
     {
         var pages = GetPages(outline).ToArray();
         if (pages.Length == 0)
             return;
 
         var pageBytes = new Dictionary<Outline, byte[]>();
+        var pageHeadings = new Dictionary<Outline, List<HeadingInfo>>();
 
         // Make progress at 99% before merge PDF
         task.MaxValue = pages.Length + (pages.Length / 99.0);
 
         await Parallel.ForEachAsync(pages, new ParallelOptions { CancellationToken = cancellationToken }, async (item, _) =>
         {
             var (url, node) = item;
-            if (await printPdf(outline, url) is { } bytes)
+            var result = await printPdf(outline, url, outline.pdfTocHeadingDepth);
+            if (result.bytes is { } bytes)
             {
                 lock (pageBytes)
                     pageBytes[node] = bytes;
             }
+            if (result.headings.Count > 0)
+            {
+                lock (pageHeadings)
+                    pageHeadings[node] = result.headings;
+            }
             task.Increment(1);
         });
 
+        // Collect headings in document order:
+        // - Page order: preserved by iterating `pages` array (parallel processing loses this)
+        // - Within-page order: preserved by DOM order from QuerySelectorAllAsync
+        var allHeadings = pages
+            .Where(p => pageHeadings.ContainsKey(p.node))
+            .SelectMany(p => pageHeadings[p.node])
+            .ToList();
+
+        // Update headings before page numbers are calculated
+        updateHeadings(allHeadings);
+
         var pagesByNode = pages.ToDictionary(p => p.node);
         var pagesByUrl = new Dictionary<Uri, List<(Outline node, NamedDestinations namedDests)>>();
         var pageNumbers = new Dictionary<Outline, int>();
+        var urlPageNumbers = new Dictionary<Uri, int>();
         var numberOfPages = 0;
 
         foreach (var (url, node) in pages)
@@ -379,6 +463,7 @@ static async Task CreatePdf(
 
             pageBytes[node] = bytes;
             pageNumbers[node] = numberOfPages + 1;
+            urlPageNumbers[CleanUrl(url)] = numberOfPages + 1;
             numberOfPages += document.NumberOfPages;
         }
 
@@ -444,7 +529,10 @@ async Task MergePdf()
                 {
                     // Refresh TOC page numbers
                     updatePageNumbers(pageNumbers);
-                    bytes = await printPdf(outline, url);
+                    updateUrlPageNumbers(urlPageNumbers);
+                    updateHeadings(allHeadings);
+                    var result = await printPdf(outline, url, 0); // 0 = don't extract headings from TOC page
+                    bytes = result.bytes;
 
                     if (bytes == null)
                         continue;
@@ -607,8 +695,40 @@ IEnumerable<BookmarkNode> CreateBookmarksCore(Outline[]? items, int level)
         }
     }
 
-    static HtmlTemplate TocHtmlTemplate(Uri baseUrl, Outline node, Dictionary<Outline, int>? pageNumbers)
+    static HtmlTemplate TocHtmlTemplate(Uri baseUrl, Outline node, Dictionary<Outline, int>? pageNumbers, Dictionary<Uri, int>? urlPageNumbers, List<HeadingInfo>? headings)
     {
+        // If pdfTocSource is "headings" and we have headings, generate TOC from headings
+        if (node.pdfTocSource == "headings" && headings is { Count: > 0 })
+        {
+            var headingTocContent = BuildHeadingToc(baseUrl, headings, urlPageNumbers);
+            var cssStyles = Html($"""
+                <style>
+                  /* Indentation for heading levels */
+                  li[data-level="1"] {"{ padding-left: 0; }"}
+                  li[data-level="2"] {"{ padding-left: 1.5em; }"}
+                  li[data-level="3"] {"{ padding-left: 3em; }"}
+                  li[data-level="4"] {"{ padding-left: 4.5em; }"}
+                  li[data-level="5"] {"{ padding-left: 6em; }"}
+                  li[data-level="6"] {"{ padding-left: 7.5em; }"}
+                </style>
+                """);
+            return Html($"""
+                <!DOCTYPE html>
+                <html>
+                <head>
+                  <link rel="stylesheet" href="/public/docfx.min.css">
+                  <link rel="stylesheet" href="/public/main.css">
+                  {cssStyles}
+                </head>
+                <body class="pdftoc">
+                <h1>Table of Contents</h1>
+                <ul>{headingTocContent}</ul>
+                </body>
+                </html>
+                """);;
+        }
+
+        // Default: generate TOC from toc.yml structure
         return Html($"""
             <!DOCTYPE html>
             <html>
@@ -637,6 +757,35 @@ static HtmlTemplate TocHtmlTemplate(Uri baseUrl, Outline node, Dictionary<Outlin
             """);
     }
 
+    static HtmlTemplate BuildHeadingToc(Uri baseUrl, List<HeadingInfo> headings, Dictionary<Uri, int>? urlPageNumbers)
+    {
+        // Build flat list of all headings with CSS-based indentation for hierarchy
+        var result = new List<HtmlTemplate>();
+
+        foreach (var heading in headings)
+        {
+            var href = new UriBuilder(heading.PageUrl) { Fragment = heading.Id }.Uri;
+            var cleanUrl = new UriBuilder(heading.PageUrl) { Query = null, Fragment = null }.Uri;
+
+            var pageNumberHtml = urlPageNumbers?.TryGetValue(cleanUrl, out var pageNum) is true
+                ? Html($"<span class='spacer'></span> <span class='page-number'>{pageNum}</span>")
+                : default;
+
+            // Use data-level attribute for CSS styling of indentation
+            var item = Html($"""
+                <li data-level='{heading.Level}'>
+                  <a href='{href}'>{System.Web.HttpUtility.HtmlEncode(heading.Text)}
+                  {pageNumberHtml}
+                  </a>
+                </li>
+                """);
+
+            result.Add(item);
+        }
+
+        return Html($"{result}");
+    }
+
     /// <summary>
     /// Adds hidden links to headings to ensure Chromium saves heading anchors to named dests
     /// for cross page bookmark reference.
@@ -726,4 +875,19 @@ private static StringComparison GetStringComparison()
             ? StringComparison.OrdinalIgnoreCase
             : StringComparison.Ordinal;
     }
+
+    private static bool IsTocPage(Uri url) => url.AbsolutePath.StartsWith("/_pdftoc/");
+
+    private static bool IsCoverPage(Uri pageUri, string baseFolder, string? pdfCoverPage)
+    {
+        Debug.Assert(Path.IsPathFullyQualified(baseFolder));
+
+        if (string.IsNullOrEmpty(pdfCoverPage))
+            return false;
+
+        string pagePath = pageUri.AbsolutePath.TrimStart('/');
+        string covePagePath = PathUtility.MakeRelativePath(baseFolder, Path.GetFullPath(Path.Combine(baseFolder, pdfCoverPage)));
+
+        return pagePath.Equals(covePagePath, GetStringComparison());
+    }
 }