Skip to content

feat(packages): Add scaling and anchoring to the background command#2346

Open
Omikhleia wants to merge 1 commit intomasterfrom
feat-background-more-options
Open

feat(packages): Add scaling and anchoring to the background command#2346
Omikhleia wants to merge 1 commit intomasterfrom
feat-background-more-options

Conversation

@Omikhleia
Copy link
Copy Markdown
Member

@Omikhleia Omikhleia commented Nov 15, 2025

New options: page (for multi-page images such as a PDF), scale (for disabling scaling), preserveaspect (for aspect ratio preservation when scaling), anchor (for positioning of the image when needed).

Moreover a color and an image src can both be set, for cases where the image has transparent areas or isn't scaled to the full bleed area (due to aspect ratio preservation or absence of scaling).


The default behavior so far for images (corresponding to scale=true, preserveaspect=false) was nice in many cases (e.g. when using some old-paper-like texture on pages)...

But the extended proposal here is something I considered for some projects:

  • In one, I fancied having some sort of floral ornaments at the top-right corner of chapter pages (i.e. ideally anchor=ne, scale=true, preserveaspect=true to avoid distortion if changing the book paper size but using the same image file)
  • In another, I fancied having some markings (e.g. draft, confidential etc.) on pages (so anchor=center, scale=false).
  • When using a PDF as "background image", the ability to pick the page to use is also a nice option (e.g. in the just mentioned case for markings, using a PDF allows for scalable drawings, and one can have all backgrounds in a given file, etc.)

This is but a proposal, which I find interesting for my needs, but it also raises some good questions:

  • Whether allpages should be true by default...
  • Whether allpages and one-page backgrounds should be stacked rather that one disabling the other... On that matter see also in-code comment on the tricky question for the user for controlling where page breaks occur. That would lead to questioning the command(s) and their scope...
  • Whether the page (+ bleed) area is always the target, or some specific frame id could be used... But this needs to be carefully considered, I played with it in another experiment but didn't include it here; it can quickly become a hornets' nest (due to switching masters and layouts etc.) and it is then hard to explain with good sense...

Feedbacks are welcome.

New options: page (for multi-page images such as a PDF), scale (for
disabling scaling), preserveaspect (for aspect ratio preservation when
scaling), anchor (for positioning of the image when needed).

Moreover a color and an image can both be set, for cases where the image
has transparent areas or isn't scaled to the full bleed area.
@Omikhleia Omikhleia added this to the v0.15.x milestone Nov 15, 2025
@Omikhleia Omikhleia requested a review from alerque as a code owner November 15, 2025 11:37
@Omikhleia Omikhleia added enhancement Software improvement or feature request modules:packages Issue relates to core or 3rd party packages labels Nov 15, 2025
@Omikhleia Omikhleia self-assigned this Nov 15, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement Software improvement or feature request modules:packages Issue relates to core or 3rd party packages

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant