[Feature Request] Option to generate PDF Table of Contents from document headings

[tsondergaard]

Summary

Add a configuration option to generate the PDF Table of Contents page from actual markdown headings within documents, rather than exclusively from toc.yml.

Motivation

Currently, the PDF TOC page is always generated from toc.yml. While toc.yml is useful for site navigation structure, it often doesn't reflect the detailed structure within individual documents. For single-document or small-document-set PDFs, a TOC generated from markdown headings (#, ##, ###, etc.) would be more useful and require less manual maintenance.

Proposed Solution

Add a configuration option in toc.yml or docfx.json to control the PDF TOC source:

# In toc.yml
pdfTocSource: headings  # or 'toc' (default)

Or alternatively:

// In docfx.json globalMetadata or pdf section
"pdfTocSource": "headings"

Possible values:

• toc (default): Current behavior, TOC from toc.yml
• headings: Generate TOC from #/##/### headings in markdown files
• both: Merge toc.yml structure with in-document headings

Additional options to consider:

• pdfTocHeadingDepth: Maximum heading level to include (e.g., 3 for ###)

Use Case

I maintain technical documentation where each markdown file is a self-contained chapter. The toc.yml provides top-level navigation, but when generating a PDF, I want the TOC to show the internal structure of each document (sections, subsections) which are defined by headings in the markdown, not duplicated in toc.yml.

Related Issues

• Generated PDF's outline/bookmarks don't link to the correct page when setting property outline to DefaultOutline #5490 — Discusses PDF bookmarks/outline (which can use headings via WkDefaultOutline), but not the TOC page
• PDF on Chromium #9343 — Chromium-based PDF implementation, TOC page still uses toc.yml
• Missing PDF functions in docFX and a few suggestions from current projects. #1882 — PDF feature requests, assumes toc.yml-based TOC