[Feature Request] Option to generate PDF Table of Contents from document headings
- Dominant language
- C#
- Stars
- 4.4k
- Forks
- 890
- Avg merge
- 2h 9m
- Merged PRs (30d)
- 11
Description
## 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:
```yaml
# In toc.yml
pdfTocSource: headings # or 'toc' (default)
```
Or alternatively:
```json
// 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
- #5490 — Discusses PDF bookmarks/outline (which can use headings via `WkDefaultOutline`), but not the TOC page
- #9343 — Chromium-based PDF implementation, TOC page still uses `toc.yml`
- #1882 — PDF feature requests, assumes `toc.yml`-based TOC
Contributor guide
Research direction
No implementation files, tests, or entry points are named. Start by locating the existing PDF TOC generation and toc.yml handling, then review issues #5490 and #9343; done means a documented configuration selects the TOC source and tests cover headings, default toc behavior, and any supported merge or depth options.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100