dotnet / dotnet/docfx

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

Open
#10,994 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.