Separate top margin for title page

[gunillabolin]

Thank you for all the work you've put into asciidoctor-pdf!

I would like to be able to add a title-logo-image to my title page without a margin at the top, ie, I want to align it to the very top of my title page. Is there a way to do this without ruining the rest?

The only margin in my theme file that seems to have an effect is the page_margin. However, setting the page_margin top value to zero puts my title image where I want it, but the rest of the document without a top margin.

Thank you in advance!

[mojavelinux]

The way you would do this, in theory, is to set the title_page_logo_top key in the theme to 0%:

title_page:
  logo:
    top: 0%

Or the top attribute on the title-logo-image image macro to 0%:

:title-logo-image: image:logo.png[align=center,top=0%]

However, as it turns out, we're forcing the resolved value, at a minimum, to match the top margin of the page. We should not be doing this. A value of 0% should place the image at the absolute top of the page.

I also think that the value should accept an absolute value, such as 0.5in. This is easier to reason about than the percentage.

[gunillabolin]

Thanks for your quick answer!

I've tried both of those, but as you say, it doesn't work. I think the absolute value is a better solution, too.

Another thing, I've been playing around with title-logo-image quite a lot in the past few days, trying to make it work the way I want it to. To make it stretch across the whole page I set the scaledwitdh percentage to 125%. Is it supposed to work this way, or is it something that might stop working in some future update?

[mojavelinux]

To make it stretch across the whole page I set the scaledwitdh percentage to 125%.

You should set the pdfwidth attribute instead. Technically, it's the same as scaledwidth, but pdfwidth is a) clearer and b) more future proof.

The reason you need to set the width to 125% has to do with the fact that the image is constrained to the side margins. To get the image to stretch outside the margins, you have to use a number higher than 100%. That amount is calculated by the ratio between the margin width and the page width (meaning page width / margin width * 100). That's roughly 120% for the default theme (A4 with 0.67in side margins).

I think this needs to be documented.

That also makes me realize that we should add an option to the image macro to allow the image to span the width of the page (instead of the margin width). In fact, I have a note in the source code to add support for this alignment. If you want to pursue it, please open another issue and we can discuss.

[AlexanderZobkov]

@gunillabolin, regarding placing a logo on the title page at the top. Instead of placing the logo with title_page_logo_XXXX keys, you could try using title_page_background_image:

• Prepare SVG of the same dimensions as the title page (72 dpi)
• Place the logo at the top of SVG.
• Configure the theme file to use the SVG file as the title page background image

[gunillabolin]

Thank you for your reply, Alexander!

Unfortunately, in the latest version of asciidoctor-pdf background images (and other things) on the title page do not work. This is due to a bug in the bundled version of Prawn; 1.3.something. The image doesn't show up on the page.

We use a work-around with title_page_background_image and building with Prawn 2.0 in order to get the pdf approved :-)

[mojavelinux]

in the latest version of asciidoctor-pdf background images (and other things) on the title page do not work.

To keep the record straight, backgrounds don't work when using AsciidoctorJ PDF. They work fine if you are using Asciidoctor PDF directly. This has to do with Ruby compliance in the version of JRuby that AsciidoctorJ currently uses. If you are using AsciidoctorJ, and want backgrounds, we recommend that you use JRuby 9k and the Prawn 2 gem directly. For an example, see:

https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-with-theme-example

[gunillabolin]

Sorry about that, it was a misunderstanding on my part.

What mojavelinux described above is the workaround we're using.

[mojavelinux]

To make it stretch across the whole page I set the scaledwitdh percentage to 125%.

You can now use the width value 100vw to achieve the same result.

[mojavelinux]

To clarify the goal of this issue, the top value specified on the image on the title page should be relative to the page, not the content area.

[mojavelinux]

To be more consistent with CSS, and the new vw units on the block image macro, I've decide to make the % unit on the top value relative to the content height (i.e., from top margin) and the vh unit relative to the page height.

To position the image flush to the top margin, you'd use:

:title-logo-image: image:title.svg[top=0%]

To position the image flush to the top of the page, you'd use:

:title-logo-image: image:title.svg[top=0vh]

[ModProg]

This does not seam to work anymore.
I tried to set an image in the top left corner:

title-page:
  logo: 
    align: left
    top: 0vh
    image: image:uni-logo.png[top=0%,left=0%,pdfwidth=50%]

But it still has a margin

[mojavelinux]

There are two ways to align the logo to the upper left corner of the page.

extends: default
title-page:
  logo:
    image: image:logo.png[pdfwidth=1in,top=0vh,align=left,opts=align-to-page]

Notice the use of opts=align-to-page, which tells the converter to start at the left edge of the page. (You can find a mention of this option in the docs under https://github.com/asciidoctor/asciidoctor-pdf/blob/v1.5.x/README.adoc#image-scaling).

The other way is to apply a negative margin that reverses the page margin:

extends: default
title-page:
  logo:
    image: image:logo.png[pdfwidth=1in]
    align: left
    margin-left: -0.67in
    top: 0vh

In the future, please ask usage questions in the community chat at https://asciidoctor.zulipchat.com.