Asciidoctor-pdf: Allow customisation of header and footer

[wimdeblauwe]

I would like to be able to set a custom header and/or footer in the PDF output.

Some ideas:

• Same header/footer on each page
• Header/footer can include the name of the current chapter you are on
• Can insert a date in there
• Can still add the page number where you want

[mojavelinux]

How would imagine this information would be specified? One simple way is to make it an extension point, allowing you do write a short amount of code to handle the layout of the header and footer. A more restrictive, and a bit more difficult way, is to allow it to be specified using some markup format (perhaps even AsciiDoc) in a special file or the theme file.

The philosophy of Asciidoctor PDF is to provide reasonable conventions and allow customization to be made via programming. Having said that, if we can find a simple way to supply configuration, I'd be happy to pursue that. Still, I think it makes the most sense to focus on extension points.

[wimdeblauwe]

I am thinking of migrating my Confluence created manuals to asciidoc. For this, I need good PDF export. We currently use no header, but we do use a footer with:

• A horizontal line over the width of the page to offset the footer
• an image (logo) left aligned
• The text "Page x of y" center aligned
• A static text right aligned

I know nothing of asciidoctor-pdf internals, so I have no clue what would be the easiest/best way to do it. Seems as a user being able to specify some Asciidoc would be really great.

[plaindocs]

+1

[mojavelinux]

A horizontal line over the width of the page to offset the footer

This we can easily control with the theme. I may have something in there already, but it may need to be refined / tested.

an image (logo) left aligned

Also sounds like we could get it done with the theme. Another possibility is an AsciiDoc attribute.

The text "Page x of y" center aligned

Definitely something that makes sense in the theme. We could also make the template text something that is put in the theme (think sprintf)

A static text right aligned

Would this be attribution text of some sort?

There's a very real possibility that a docinfo-style file for the footer could be used to accommodate the footer content. We could perhaps agree on some attribute names that can be referenced in the text to allow the content to be dynamic. Anything related to style would then be handled in the theme. Separation of content and presentation.

[plaindocs]

I would have thought you want variables made available to the theme, such as $page_num, $page_count, $current_h1 which you could then set in the theme somehow as

footer_left=current_h1
footer_right=page_num of page_count

Or is that naive?

[wimdeblauwe]

The static text is the company url.

Let me know if you have something I can test, I can make some time for it.

Regards,

Wim

Op maandag 2 februari 2015 heeft Dan Allen [email protected] het
volgende geschreven:

A horizontal line over the width of the page to offset the footer

This we can easily control with the theme. I may have something in there
already, but it may need to be refined / tested.

an image (logo) left aligned

Also sounds like we could get it done with the theme. Another possibility
is an AsciiDoc attribute.

The text "Page x of y" center aligned

Definitely something that makes sense in the theme. We could also make the
template text something that is put in the theme (think sprintf)

A static text right aligned

Would this be attribution text of some sort?

There's a very real possibility that a docinfo-style file for the footer
could be used to accommodate the footer content. We could perhaps agree on
some attribute names that can be referenced in the text to allow the
content to be dynamic. Anything related to style would then be handled in
the theme. Separation of content and presentation.

—
Reply to this email directly or view it on GitHub
https://github.com/asciidoctor/asciidoctor-pdf/issues/89#issuecomment-72519309
.

[plaindocs]

How would one access variables set in the .adoc header from

https://github.com/asciidoctor/asciidoctor-pdf/blob/master/lib%2Fasciidoctor-pdf%2Fconverter.rb#L1140

I'm hacking something together for personal use, but can probably make it at least usable if not elegant for other people.

[plaindocs]

I've got something usable for myself, which takes the :footer: attribute from the doc being processed, and puts it in page_number_label.

I'm having trouble with alignment, as center does not seem to work in this context, so probably I need to use another formatted_text_box instead of the same one?

[DavidGamba]

@mojavelinux do you have any example of how to integrate a footer docinfo here?

I did a quick hack building on the idea from @plaindocs to add header and footer using the attributes header (centered), header-right (right aligned) and header-left (left aligned), and the same for the footer.

https://github.com/DavidGamba/asciidoctor-pdf/commits/header-footer

I separated (copied) the logic from the page number because my company requires the header and footer to start at the front page.

I don't know if you can embed images into attributes but if you can and when asciidoctor-pdf supports inline images this could be an easy way to do it. However the docinfo way allows for more customization and is consistent with the HTML backend way.

[mojavelinux]

I would have thought you want variables made available to the theme, such as $page_num, $page_count, $current_h1 which you could then set in the theme somehow

That's certainly possible. The theme files are an enhanced YAML syntax to supports variable references (much like AsciiDoc attribute references) like you see in the default theme. Variables can appear in a string of text (interpolated).

[mojavelinux]

I'm having trouble with alignment, as center does not seem to work in this context, so probably I need to use another formatted_text_box instead of the same one?

Likely. The current layout of the footer is pretty specialized (and pretty ugly code), so replacing it with something more generic is probably going to be most suitable for injecting content.

[mojavelinux]

I did a quick hack building on the idea from @plaindocs to add header and footer using the attributes header (centered), header-right (right aligned) and header-left (left aligned), and the same for the footer.

I like the idea, but we need to think about the best attribute names if we take this approach. Something like pdf-header-text, pdf-header-text-left, pdf-header-text-right might be more clear.

The other way in which we can address this issue is provide more hooks into the processor in case you want to override something. This is done by delegating to a method in the place most convenient to override. Too much nested logic means you have to reimplement large sections of code if you create a converter subclass or monkeypatch.

[mojavelinux]

I think I nailed all of the requirements in the issue description with #165. I essentially implemented content templates for the 6 trim locations (top left, top center, top right, bottom left, bottom center, bottom right) for both recto and verso pages. Almost all aspects of styling can be controlled by the theme.

The content templates are substituted as inline AsciiDoc, so you get all the flexibility of document attributes. Inline images are supported if the image is the only content for a given position.

I also set the following dynamic attributes.

• {page-count}
• {page-number}
• {document-title}
• {document-subtitle}
• {chapter-title}
• {section-title}
• {section-or-chapter-title} (for when a section hasn't been seen yet)

We can always go further with this, but I think this is a great start.

I'd like to explore the idea of using separate AsciiDoc files for these templates in a separate issue. For the purpose of this issue, I implemented it in the theme.

[mojavelinux]

Here's an example from the default theme:

footer:
  font_size: $base_font_size_small
  font_color: $base_font_color
  # NOTE if background_color is set, background and border will span width of page
  border_color: dddddd
  border_width: 0.25
  height: $base_line_height_length * 2.5
  padding: [$base_line_height_length / 2, 1, 0, 1]
  valign: top
  recto_content:
    right: '{section-or-chapter-title} | {page-number}'
  verso_content:
    left: '{page-number} | {chapter-title}'

[mojavelinux]

I separated (copied) the logic from the page number because my company requires the header and footer to start at the front page.

We'll need to deal with this requirement in a follow-up issue. Also, many books use different running content for chapter pages. We'll need to deal with that as well.

[mojavelinux]

For now, I decided to make this part of the theme rather than the document because I don't think this is content that belongs in the document. We could still consider allowing the document to contribute to what the theme sets via attributes, but let's deal with that in a follow-up issue.

[mojavelinux]

Btw, a useful page for reference about running headers and footers from SageHill's documentation on DocBook XSL customization. http://www.sagehill.net/docbookxsl/PrintHeaders.html

[mojavelinux]

And here's a similar reference about running headers and footers for the MOM macros for LaTeX. http://www.schaffter.ca/mom/momdoc/headfootpage.html#hdrftr-strings

[mojavelinux]

Note that the documentation for this configuration can be found in the theming guide.

http://gist.asciidoctor.org/?github-asciidoctor%2Fasciidoctor-pdf%2F%2Fdocs%2Ftheming-guide.adoc#running-header-footer

[alexfederlin]

This is great stuff. And developed just in time for my needs.

I would love to see two additional features:

• make the revnumber and revdate attributes accessible
• If the content becomes too long (like very long {document-title}) make it wrap around so it does not clash with text in other positions
  Thanks!

[mojavelinux]

make the revnumber and revdate attributes accessible

I have good news for you. These are already available. In fact, you can use any document-scoped attribute in the content of the running header/footer.

If the content becomes too long (like very long {document-title}) make it wrap around so it does not clash with text in other positions

It will wrap, but as you've pointed out, it does that after clashing with content in a neighboring position. What we need are stop columns. The best thing to do here is probably to switch to using the columnar/table layout so that the PDF engine will automatically handle this behavior. Would you like to open an issue for this change?

[bannmann]

Would you like to open an issue for this change?

See issue #608.