dotnet / dotnet/docfx

[Feature Request] Add an option to omit link annotations from generated PDF files

Open
#11,130 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 11m
Merged PRs (30d)
10

Description

PDFs generated by Docfx contain link annotations. Some digital-signing tools fail to sign the resulting PDF correctly. In our case, applying a second signature can also invalidate the first signature.

Removing all link annotations before signing allows the same PDF to be signed successfully. Removing bookmarks alone does not resolve the problem.

It would be useful if Docfx supported an option to omit link annotations from generated PDF output. This would provide a workaround for signing tools that cannot process the annotations emitted during PDF generation and merging.

The current PDF documentation provides options such as `pdfFileName`, `pdfTocPage`, `pdfCoverPage`, and `pdfPrintBackground`. A new `pdfKeepLinks` option could be added to control whether links are retained.

For example, as TOC metadata:
```yaml
pdf: true
pdfKeepLinks: false
```

The default value should be `true` to preserve the current behavior.

Docfx's PDF merge functionality uses PdfPig. PdfPig already exposes the `PdfDocumentBuilder.AddPageOptions.KeepAnnotations` options:
```
var options = new PdfDocumentBuilder.AddPageOptions
{
KeepAnnotations = pdfKeepLinks
};

builder.AddPage(document, pageNumber, options);
```

Docfx could pass the proposed pdfKeepLinks value to this existing PdfPig option, avoiding the need for a separate PDF post-processing step.

This is a workaround. A proper solution to this problem would require either:

- A fix in the PdfPig package. The latest version does currently not solve this problem.
- Switch to a different PDF merging package. I did test [PDFSharp](https://github.com/empira/pdfsharp) and that did succeed in merging and signing.

Contributor guide

Open the contributing guide

Research direction

Start with Docfx's PDF merge functionality and its TOC metadata handling; inspect how existing options such as pdfFileName and pdfPrintBackground are read and passed into PdfPig. Use PdfDocumentBuilder.AddPageOptions.KeepAnnotations as the integration point, preserve true as the default, and verify generated PDFs with the option enabled and disabled.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.