precice / precice/precice.github.io

Various issues with the PDF export

Open
#897 12 comments 1 reaction 0 assignees View on GitHub
good first issue technical
Dominant language
HTML
Stars
31
Forks
140
Avg merge
1d 23h
Merged PRs (30d)
6

Description

Some issues with the current [PDF export](https://precice.org/docs-meta-publish-to-pdf.html) (as of May 2026 and while reviewing #734):

- [x] The [XML config reference](https://precice.org/configuration-xml-reference.html) appears in the middle of the document for several pages. It would be better to render it in an appendix. -> Fixed by #898
- [x] Some pages (e.g., [special systems](https://precice.org/installation-special-systems.html) are too wide. -> Tried to fix in https://github.com/precice/precice.github.io/pull/899, but code blocks are not the issue.
- [x] Pages are centered and some images take only as much width as the text. For example, the [release strategy page](https://precice.org/dev-docs-release-strategy.html). -> Workaround in https://github.com/precice/precice.github.io/pull/899
- [ ] Mermaid graphs (e.g., in [multi-coupling configuration](https://precice.org/configuration-coupling-multi.html#composition-of-bi-coupling-schemes)) are not rendering.
- [x] The footer (including the Newsletter block) appears at the bottom of the Quickstart.
- [x] There is often an empty trailing page.
- [x] 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](https://precice.org/tutorials-heat-exchanger.html).
- [ ] Prince [throws several warnings](https://precice.org/docs-meta-publish-to-pdf.html#warnings-by-prince). We should eventually look at those.
- [ ] YouTube videos are occupying space without any rendering. For example, in the [OpenFOAM adapter overview](https://precice.org/adapter-openfoam-overview.html). -> The space issue is now mostly solved in https://github.com/precice/precice.github.io/pull/972, we would just need a placeholder link to the video.

Many of these issues would be easy to fix. Most of the relevant files are in the [`pdfconfigs`](https://github.com/precice/precice.github.io/tree/master/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:

- [x] The copyright statement is incomplete, only pointing to the core library -> Expanded in https://github.com/precice/precice.github.io/pull/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](https://nextcloud.in.tum.de/index.php/s/fYPdkYgajSE8XG3).

**Important:** The website has been ported from Jekyll to Hugo in the `hugo` branch (to be merged to `master` soon) and the PDF generation has been ported to Hugo in #972.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.