Various issues with the PDF export

[MakisH]

Some issues with the current PDF export (as of May 2026 and while reviewing #734):

• The XML config reference appears in the middle of the document for several pages. It would be better to render it in an appendix. -> Fixed by Add an appendix to the PDF archive #898
• Some pages (e.g., special systems are too wide. -> Tried to fix in Improvements to the PDF archive #899, but code blocks are not the issue.
• Pages are centered and some images take only as much width as the text. For example, the release strategy page. -> Workaround in Improvements to the PDF archive #899
• Mermaid graphs (e.g., in multi-coupling configuration) are not rendering.
• The footer (including the Newsletter block) appears at the bottom of the Quickstart.
• There is often an empty trailing page.
• Some (thin) images are too large and take up too much page area. We should restrict the maximum height. For example, the heat exchanger tutorial.
• Prince throws several warnings. We should eventually look at those.
• YouTube videos are occupying space without any rendering. For example, in the OpenFOAM adapter overview.

Many of these issues would be easy to fix. Most of the relevant files are in the pdfconfigs folder. PRs are welcome, but please keep them small (one per aspect).

Besides the above, some issues that would require discussion in the team:

• The copyright statement is incomplete, only pointing to the core library -> Expanded in Improvements to the PDF archive #899
• The "Community" and "About" pages are not incorporated (do we even want that?). Links to these appear as "page 0". From the "Community", we could add the contributing/guidelines pages, and the "About" would be interesting as well.

Note to self: On my system, I am building the container with jekyll serve --config _config.yml,pdfconfigs/config_docs_pdf.yml in one terminal, and calling Prince from my host (already installed) with prince --javascript --input-list=_site/pdfconfigs/prince-list.txt -o pdf/docs.pdf.

A local build of the PDF, for reference: May 15, 2026.

[MakisH]

@Atiqumer we do not assign issues to externals. Feel free to describe how you want to solve what, in case you want others to wait for a PR from you for a reasonable timeframe.

Since this issue is an umbrella issue for multiple smaller issues, you need to be specific. :)

[MakisH]

For the footer in the Quickstart issue, modifying the frontmatter helps to use the right layout in the PDF:

---
title: Quickstart
permalink: quickstart.html
keywords: tutorial, quickstart
summary: "Install preCICE on Linux (e.g. via a Debian package) and couple an OpenFOAM fluid solver (using the OpenFOAM-preCICE adapter) with an example rigid body solver in C++."
layout: "page"
comments: false
search: true
- sidebar: nil
topnav: topnav
toc: false
---

but then it leads to both "Quickstart" and "Tutorials" being highlighted on the top in the web view (similar to the issue of highlighting a "basic tutorial" in both parts of the sidebar):

I also tried creating a sidebar only for the Quickstart (a "Table of Contents"), but that only made the situation weirder.

Note that sidebars work differently in HUGO, which we plan to switch to (#472).

[shubham09-patel]

Hi @MakisH, I’d like to work on the “empty trailing page” issue and keep the PR focused only on that aspect.

I’ll first reproduce the PDF locally using the command you shared, then check the relevant files in pdfconfigs to identify what causes the extra blank page. If I find a clean fix, I’ll open a small PR for this item only.

[MakisH]

PRs welcome, @shubham09-patel! At the moment, I have no clue where this issue could be coming from. If there is a simple solution, we can integrate it.

[shubham09-patel]

I reproduced the PDF export locally. The PDF builds successfully with Prince, and I can confirm that configuration-xml-reference.html is now listed after appendix_part_title.html in the generated prince-list.txt.

I’ll continue checking the empty trailing page issue separately so this stays focused on that problem.

[shubham09-patel]

I also checked the generated PDF locally. The last page contains content and I do not see an empty trailing page in my local build.

Screenshot attached for reference.

[MakisH]

@shubham09-patel I meant empty pages in the middle of the document. The only empty pages (without a clear reason) I could find in my build from May 15 (page numbers as shown on each page corner) are 74 (at the end of the anyway problematic special systems) and 267 (missing an image). Debugging these would definitely be helpful!

[MuhammadAashirAslam]

• The footer (including the Newsletter block) appears at the bottom of the Quickstart.

I think migration of the bootstrap solved this issue as i am not seeing the Newsletter block