search

asciidoctor / asciidoctor-pdf

:page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby.
https://docs.asciidoctor.org/pdf-converter/latest/
MIT License
1.14k stars 500 forks source link

Set margins for different blocks #2011

Closed edward-encoord closed 2 years ago

edward-encoord commented 2 years ago

Thanks for this nice tool. I'm wondering if it's possible to set margins for different blocks.

I have tried:

block:
  margin-top: 0
  margin-bottom: 0
  example:
    margin-top: 10
    margin-bottom: 10

and

block:
  margin-top: 0
  margin-bottom: 0
example:
    margin-top: 10
    margin-bottom: 10

but they do not work. Maybe I did something wrong.

Why I need this. For some reason, I need to set both margins of the image block as 0, but I don't want this setting for any other block.

My current way to set margins for different blocks. Now, for the sidebar block and the admonition block, I can set:

sidebar:
  border-color: FFFFFF  # white
  border-width: 3
  border-radius: 3

so that there is some space because of the thick white border.

For other blocks, I add ifdef::backend-pdf[{empty} +] or ifdef::backend-pdf[---] between them, and set:

thematic-break:
  border-color: FFFFFF
  border-width: 0
  margin-top: 1
  margin-bottom: 3

Another way is to put all the blocks inside the example block and:

example:
  padding: [8, 15, 8, 15]
  border-color: FFFFFF  # white

So the space between blocks is controlled by padding.

I'm using asciidoctor/docker-asciidoctor:

bash-5.1# asciidoctor-pdf -v
Asciidoctor PDF 1.6.2 using Asciidoctor 2.0.17 [https://asciidoctor.org]
Runtime Environment (ruby 3.0.3p157 (2021-11-24 revision 3fb7d2cadc) [x86_64-linux-musl]) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
mojavelinux commented 2 years ago

This is not currently possible. All dedicated block types (except paragraphs) share the margins defined in the block category key. The theming guide clearly states this fact.

This issue is related to #1515. We can explore implementing margins per block type when that issue is worked on.

edward-encoord commented 2 years ago

Thanks for the reply. I can rely on adding ifdef::backend-pdf[---] manually for now. Feel free to close this issue.

mojavelinux commented 2 years ago

Is there a reason you need to set different margins for different block types? Can you explain the use case and what you expect to happen?

Even if we add support for different bottom margins for different block types, you would get a different margin above the block than below it. That then gets us into when top margins should be applied and how they interact with the bottom margin of a preceding block. But in order to get anywhere, I need to understand what you are trying to achieve visually.

edward-encoord commented 2 years ago

Sorry for the late reply.

I need margin-top and margin-bottom of some block images and tables to be 0. I want some block images to be specially positioned between paragraphs, so I put those images inside some tables. Any margin makes this positioning ugly.

When margin-top: 0 and margin-bottom: 0, for example:

image

(with borders for your examination)

image

When margin-top: 10 and margin-bottom: 10, the margin between the figure and paragraphs will be 20:

image

(with borders for your examination)

image

For the normal images, normal tables and other blocks, I'd their margins to be normal. Now I need to find other ways to separate them from each other and paragraphs.

mojavelinux commented 2 years ago

I'm happy to report that the problem you're drawing attention to here has been resolved in Asciidoctor PDF 2 by #1515. I'll share a screenshot here of content similar to yours using the default theme from Asciidoctor PDF 2.

screenshot

Bottom margins are now smart. The converter is aware when a block is the last child inside an enclosure and does not add a bottom margin to it in that case. So there's no need to adjust the bottom margin manually. And we've done away with top margins (except for headings), so there's no need to worry about those either.

I encourage you to try Asciidoctor PDF 2 and report back whether it allows you to get the result that you want. In your case, you should set block-margin-bottom to 20.

edward-encoord commented 2 years ago

I can confirm my problem has been solved in Asciidoctor PDF 2. Thanks for the effort and tip.

I noticed lots of other improvements. However, there're some noticeable differences, like the math blocks are approximately 10 % wider. I guess I need to adapt some settings. Also, there're some theme settings in 1.6.2 deprecated in 2.0.0.

I plan to use v1.6.2 for now, and use v2.0.0 after the synced theme guide and the release note.

mojavelinux commented 2 years ago

I can confirm my problem has been solved in Asciidoctor PDF 2. Thanks for the effort and tip.

:tada: :tada: :tada: Thanks for verifying!

like the math blocks are approximately 10 % wider.

Hmm, that seems unexpected. If you can prepare a reproducible example, could you file an issue so I can investigate it?

I guess I need to adapt some settings.

We programmed Asciidoctor PDF 2 so that there is no immediate requirement to change any settings. Of course, there deprecations that you'll want to start addressing in time.