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

[guuskuiper]

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:

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 and that did succeed in merging and signing.

[guuskuiper]

Analysis using Copilot by comparing PDF's created by PdfPig and PDFSharp and signing both twice.

What Is Happening

A signed PDF is not rewritten in place. Each signing operation appends an incremental revision:

Original merged PDF
+ first signature revision
+ second signature revision

The first signature’s /ByteRange covers everything through the first revision. The second signature covers the final revision.

When Adobe validates the first signature, it performs two separate checks:

Cryptographic integrity: Are the bytes covered by the first signature unchanged?
Modification analysis: Are changes made after the first signature permitted, such as adding another signature field?
The first check passes for both supplied PDFs. The PdfPig signature is cryptographically intact.

Where PdfPig Goes Wrong
PdfPig writes link annotation dictionaries directly inside each page’s /Annots array:

/Annots [
  <<
    /Type /Annot
    /Subtype /Link
    /Rect [...]
    /A << ... >>
  >>
]

These are direct objects. They have no PDF object number.

PDFsharp instead writes annotations as indirect objects:

/Annots [
  189 0 R
  190 0 R
]

With separate definitions:

189 0 obj
<<
  /Type /Annot
  /Subtype /Link
  /Rect [...]
  /A << ... >>
>>
endobj

An annotation dictionary is expected to be an indirect object. The /Annots array itself may be direct, but its annotation entries should be indirect references.

Why It Breaks Only After Signing Twice
The second signature adds another signature field and widget annotation. Adobe must compare the revision after signature one with the final revision and decide:

Was only another signature field added?

That comparison depends on stable indirect object identities. An indirect annotation such as 189 0 R can be tracked between revisions. An inline annotation dictionary has no independent identity.

For the PdfPig file, independent revision analysis failed while traversing page annotations with:

Array contains direct objects

The subsequent revision was therefore classified as:

ModificationLevel.OTHER

Adobe consequently cannot establish that the only change was adding another signature. It reports the earlier signature as invalid or as invalidated by later changes.

For the PDFsharp file, the same analysis succeeded and reported:

ModificationLevel.FORM_FILLING
Changed field: Signature3

That is the expected classification for adding another approval signature. Adobe therefore keeps the first signature valid.

Important Distinction
The PdfPig result does not mean:

The certificate is bad.
The CMS signature value is wrong.
/ByteRange is incorrect.
The signed bytes were modified.
The second signer corrupted the original signed bytes.
Both CMS signatures in the PdfPig file pass cryptographic verification. The failure is in Adobe’s structural and incremental-change validation.

Why Removing Links Appears to Fix It
Removing links prevents PdfPig from creating the problematic direct annotation dictionaries. Adobe can then analyze the second revision without encountering them.

That workaround removes the trigger, but it does not repair the underlying serialization problem.

The content-preserving fix is for PdfPig’s writer to register every copied link annotation as an indirect PDF object and place references such as 189 0 R in /Annots. The current issue originates from the annotation-copy path, but the actual serialization behavior is inside PdfPig’s PdfDocumentBuilder. The public KeepAnnotations and CopyLinkFunc APIs do not appear to expose control over direct versus indirect allocation.