Skip to content

Switch to make singlehtml + Chromium for PDF output - #307

Open
legoktm wants to merge 1 commit into
mainfrom
singlehtml-chromium
Open

Switch to make singlehtml + Chromium for PDF output#307
legoktm wants to merge 1 commit into
mainfrom
singlehtml-chromium

Conversation

@legoktm

@legoktm legoktm commented Jul 29, 2026

Copy link
Copy Markdown
Member

Instead of going through LaTeX, which has some limitations (e.g. can't use newer emojis), we can use sphinx's pre-existing "singlehtml" target, and just have a browser print it to PDF. Chromium has a better CLI setup for this, but in the future we can swap to Firefox if desired.

I think for the most part this will be a nicer experience for users, because it'll be much closer to what's already online (some CSS is different), and because it's just HTML, there'll be far less less gotchas of things that work in HTML mode but not in PDF mode.


This was done by Claude after I got nerdsniped by @jskinne3.

Test plan

  • Compare with existing PDF output, decide which is better.

Checklist

This change accounts for:

  • local preview of changes beyond typo-level edits

Instead of going through LaTeX, which has some limitations (e.g. can't
use newer emojis), we can use sphinx's pre-existing "singlehtml" target,
and just have a browser print it to PDF. Chromium has a better CLI setup
for this, but in the future we can swap to Firefox if desired.

I think for the most part this will be a nicer experience for users,
because it'll be much closer to what's already online (some CSS is
different), and because it's just HTML, there'll be far less less
gotchas of things that work in HTML mode but not in PDF mode.
@almet

almet commented Jul 30, 2026

Copy link
Copy Markdown
Member

I've been using https://weasyprint.org/ to turn HTML documents into PDF (as a python library but it can be used as a CLI as well) with great results 🙂.

It requires to configure a bit more the CSS "print" target, but the upside is that you can have documents that have a nice paper feeling, disable some menus and information that don't make sense for print, but are are displayed in the HTML rendered for browsers.

It seems that there exists an integration for sphinx: https://pypi.org/project/sphinx-weasyprint-builder. I haven't tried it, but if you're willing to spend some time tweaking the CSS, I bet you won't regret it (plus, it doesn't need an actual browser)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants