search

useblocks / sphinx-simplepdf

A simple PDF builder for Sphinx documentations
https://sphinx-simplepdf.readthedocs.io
MIT License
32 stars 14 forks source link

Make page break behavior configurable #73

Open JohannesHaag opened 1 year ago

JohannesHaag commented 1 year ago

Hello,

in our project documentation, we have often the case that a chapter has no content. For example if it is directly followed by a sub chapter or if the content is added at a later time. This results in a lot of nearly empty pages in the rendered PDF document.

As far as I have seen, there is no possibility to prevent sphinx-simplepdf from making page breaks in general, or to configure the level of chapters for which a page break should be done (eg only for the main chapters).

Maybe anyone has already a solution for this issue? If there is no option for that at the moment, it would be really helpful, to introduce such a configuration option.

Thanks in advance for your feedback and support.

kreuzberger commented 1 year ago

This could be configured via the css. In the main.css by default a page break is added before h1, h2 elements. E.g. you can disable it for h2 elements. I see currently no possibility to make it "content" dependent. You can also add classes and directives to force page breaks for e.g. specific (class) h2 elements etc.

My solution to have no page break between first (and only h1 chapter) and the "content" h2 chapters e.g. is:

/* no page break after first title */
h1 + section > h2 {
    page-break-before: avoid;
}
kreuzberger commented 11 months ago

With https://github.com/useblocks/sphinx-simplepdf/issues/82 this could now be configured in "general" for headers with class attributes. Currently it is limited to h1/h2 headers.