Support tagged content in PDF exports for accessible heading structure #2604

New Issue

OVERLORD · 2026-02-05T04:36:09+03:00

OVERLORD commented

2026-02-05 04:36:09 +03:00

Originally created by @WestphalDenn on GitHub (Jan 25, 2022).

Describe the Bug

I am a blind user of Bookstack. Using it in general works fine. There is one thing though I have noticed.

When exporting a page to a PDF-File, the heading-structure set in the editor is not seen by the screenreader. It appears that the tags used to provide this kind of information to assistive technologies is isregarded during the export process.

It would help a great deal if the formating is preserved during exports to PDF. That ensures that the exported PDF-Files can be read and efficiently navigated by all people.

Thank you for taking the time to fix this. I'll gladly provide more info if necessary.

Steps to Reproduce

open a page in bookstack which has at least one heading.
export the page as PDF.
Open the PDF
Using PDF-testing-tools of choice see that the heading(s) are just enlarged text and not tagged as headings.

Expected Behaviour

the exported PDF-File should preserve formating in an accessible way.

Screenshots or Additional Context

No response

Exact BookStack Version

21.12.2

PHP Version

No response

Hosting Environment

Cloudron-install

Originally created by @WestphalDenn on GitHub (Jan 25, 2022). ### Describe the Bug I am a blind user of Bookstack. Using it in general works fine. There is one thing though I have noticed. When exporting a page to a PDF-File, the heading-structure set in the editor is not seen by the screenreader. It appears that the tags used to provide this kind of information to assistive technologies is isregarded during the export process. It would help a great deal if the formating is preserved during exports to PDF. That ensures that the exported PDF-Files can be read and efficiently navigated by all people. Thank you for taking the time to fix this. I'll gladly provide more info if necessary. ### Steps to Reproduce 1. open a page in bookstack which has at least one heading. 2. export the page as PDF. 3. Open the PDF 4. Using PDF-testing-tools of choice see that the heading(s) are just enlarged text and not tagged as headings. ### Expected Behaviour the exported PDF-File should preserve formating in an accessible way. ### Screenshots or Additional Context _No response_ ### Exact BookStack Version 21.12.2 ### PHP Version _No response_ ### Hosting Environment Cloudron-install

OVERLORD added the 🔨 Feature Request 🚚 Export System ♿ A11y ⛲ Upstream labels 2026-02-05 04:36:10 +03:00

OVERLORD commented

2026-02-05 04:36:15 +03:00

@ssddanbrown commented on GitHub (Jan 26, 2022):

Thanks for reporting @WestphalDenn, I've updated the title and re-categorised the labels of this issue since it's not specifically a bug in existing functionality we've previously built/supported, but a feature request to an existing subsystem that's currently an accessibility failure which should be improved.

This has been my first experience of PDF accessibility. The following page has proved very useful to understand the technical aspects: https://www.w3.org/WAI/WCAG21/Techniques/pdf/PDF9

Unfortunately our default PDF renderer, DOMPDF, doesn't appear to support the required manner of tagging in any way right now. It also looks like it might require a significant amount of work to add. It would be something I'd love to provide upstream to DOMPDF if I could find the time to understand the DOMPDF project source and PDF specifications better. Have ordered an introductory book to PDF for when the moment hits.

In the meantime, listed below are a couple of other PDF export options that may provide more accessible results. In the above I've only tested via our default DOMPDF renderer:

I try to retain presentable print styling. Printing as PDF via the browser may provide a more accessible output.
PDF exporting can be configured to use WKHTMLtoPDF as detailed in our docs here although this does have some security implications. WKHTMLtoPDF generally provides more accurate outputs so may also provide more accessible output.

@ssddanbrown commented on GitHub (Jan 26, 2022): Thanks for reporting @WestphalDenn, I've updated the title and re-categorised the labels of this issue since it's not specifically a bug in existing functionality we've previously built/supported, but a feature request to an existing subsystem that's currently an accessibility failure which should be improved. This has been my first experience of PDF accessibility. The following page has proved very useful to understand the technical aspects: https://www.w3.org/WAI/WCAG21/Techniques/pdf/PDF9 Unfortunately our default PDF renderer, DOMPDF, doesn't appear to support the required manner of tagging in any way right now. It also looks like it might require a significant amount of work to add. It would be something I'd love to provide upstream to DOMPDF if I could find the time to understand the DOMPDF project source and PDF specifications better. Have ordered an introductory book to PDF for when the moment hits. In the meantime, listed below are a couple of other PDF export options that may provide more accessible results. In the above I've only tested via our default DOMPDF renderer: - I try to retain presentable print styling. Printing as PDF via the browser may provide a more accessible output. - PDF exporting can be configured to use [WKHTMLtoPDF as detailed in our docs here](https://www.bookstackapp.com/docs/admin/pdf-rendering/) although this does have some security implications. WKHTMLtoPDF generally provides more accurate outputs so may also provide more accessible output.

OVERLORD referenced this issue

2026-02-05 04:44:31 +03:00

[Feature Request]: plug-in interface that makes external content appear to be a book with pages #2660

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#2604