Asciidoctor-pdf: Customizable title page

[ruabmbua]

It would be nice, if it is possible, to define your own content for the title page. I really need this, because I have to put a table on the cover page of my document with some meta information in it. I think it is already possible, by using ruby code, but I am not so good with that language, and this feature should really be customizable with the default asciidoctor-pdf.

[mojavelinux]

How do you envision this working? Do you want a special open block (similar
to preface or abstract) that gets used on the title page? Or something else?

[ysb33r]

The use of a [title] or [frontpage]open block could be useful for other backends too.

However, this block is a bit different as it will also need to take the level 0 title into account as well. What about making it a kind of a template that can be included i.e.

= This it the title
:author: ysb33r
:frontpage-layout: path/to/template.adoc

Then template.adoc may look like

{author} has written this book called {title}.

He also want this table on the front page

[cols="2*"]
|===
| col 1
| col 2
|===

[mojavelinux]

this block is a bit different as it will also need to take the level 0 title into account as well.

That depends on whether this is supplemental content or whether it's taking over the whole layout of the page. Now you've gotten me thinking about the latter.

[plaindocs]

+1

I'd say a fairly common usage would to be to include an image below the title, as well as a logo above it.

[leif81]

I'd say a fairly common usage would to be to include an image below the title, as well as a logo above it.

There's ability to place an image above the title with the titlepage-logo attribute. See http://stackoverflow.com/a/26763956/52176 for more.

[plaindocs]

Thanks - that is what I meant when I said 'as well as a logo above it'.

[plaindocs]

From what I can read :toc-placement: preamble is _not_ implemented in asciidoctor-pdf, right As that might be enough, as long as one can avoid the pagination between title page and preamble?

[plaindocs]

I added a second image below the title by duplicating the titlpage-logo loop in the ruby.

[mojavelinux]

Customizing the Ruby is actually the way I planned for advanced users to customize the layouts. Though, we need to work on making that easier and clearer to do (and have a tutorial for it).

Having said that, getting branding images on the title pages should be something we support out of the box given it's often a core requirement. There are two key things to decide before changing the code:

1. How to express the information in AsciiDoc (clearly document-level attributes seem to be the best fit)
2. Where to place them and what constraints they will have

It's very hard to support a widely-varied layout. However, if we can imagine the page as a fixed template, then it's fairly simple to place the information into the designed places. Then, for more advanced, custom layouts, you can tweak the Ruby (until other avenues emerge in the future).

[plaindocs]

FWIIW my changes for both footer and cover image are https://github.com/plaindocs/asciidoctor-pdf/tree/feature_footer

I think the approach of adding a doc level attribute, with well documented guidelines so we don't have to do too much error checking in the code would work.

If you're wanting advanced users to customize the ruby it would be nice to be able to override things with config rather than changing asciidoctor-pdf directly. ie, use this entire COVER from mycover.rb instead of the normal cover.rb (does not yet exist) in asciidoctor-pdf.

[mojavelinux]

If you're wanting advanced users to customize the ruby it would be nice to be able to override things with config rather than changing asciidoctor-pdf directly. ie, use this entire COVER from mycover.rb instead of the normal cover.rb (does not yet exist) in asciidoctor-pdf.

That's precisely what I mean by making it easier. There is a new API in the latest Prawn that will allow us to partition the code this way so that it can be much more easily customized. Now, we just have to migrate the code to that model :)

[mojavelinux]

See #53

[mojavelinux]

I've made some strides allowing the look & feel of the title page to be customized. See #135.

That change doesn't yet allow you to customize the content. I'm thinking what we'll probably do is have a custom content area into which we will load docinfo content from an adoc file. Beyond that, I think you'll need to extend the converter and override the layout_title_page because extension is the spirit of the Asciidoctor ecosystem.

[mfitzp]

Not sure whether this fits here or in another feature request — but in asciidoctor-epub there is now support for a image title page using :front-cover-image: to set an image to use as the cover.

EDIT: I've just discovered that this is actually already working :+1: I had just messed up the directives.

[mojavelinux]

:+1:

[zgrzybek]

I would really love to use AsciiDoc in my project, but unfortunately the prerequisite is to have the ability to change the template of the title page - without this I will probably need to look for a different solution.

Do you know any timelines for this feature?
Or is there any description of how to properly extend the converter and use it together with asciidoctor-maven-plugin and asciidoctorj-pdf?

[mosabua]

I would not look for another solution just because of the title page. You can already do a lot with the existing theming and parameters and if all else fails - create a custom PDF front page any way you want and stitch it to the output of asciidoc..

[veeg]

Extend the converter and output raw prawn instructions. Quite easy to do. Look at the create_title_page function for inspiration.

[zgrzybek]

@veeg that sounds like something I could be able to do.
Are you aware of any example of how to connect such an converter extension with asciidoctor-maven-plugin execution, or at least how to do it from java code without the maven plugin?

[AlexanderZobkov]

This might help you http://raibledesigns.com/rd/entry/re_customizing_an_asciidoctor_pdf

[veeg]

Memory serves me wrong. It was layout_title_page as pointed out by the above link.

[mojavelinux]

if all else fails - create a custom PDF front page any way you want and stitch it to the output of asciidoc.

Exactly. In the end, you can always replace the title page that Asciidoctor PDF generates with your own using a PDF manipulation library. I highly recommend pyPdf (which is used by pdfshuffler).

Thinking a bit beyond that, I think the best way to handle a custom title page is to make the title page function an extension point. While it's possible to override the converter today, it would be nicer if it were possible to plug in code that isn't coupled to the converter. The extension would only permit you to modify a single page, but at least you would get 100% control over it using the Prawn API. I'll have to see if I can make that work.

[ilvetz]

+1
need to add a mark for classified documents

[mojavelinux]

I merged this issue with #1006.

[Alyaksej]

What about copyright-page (or author-page)? Can I add "author-page" between title-page and TOC? Maybe some macro exist? For example :author-page: and :author-page!: (as like as :toc: - :toc!: )

[mojavelinux]

You can add as many pages as you like using AsciiDoc content. For example:

= Document Title
Author Name
:title-page:

{authors}

<<<

remaining content

However, these pages will only be styled as normal pages. If you want them styled in a special way, you will need to extend the converter. This converter is designed for simple / typical typesetting out of the box. If you want advanced typesetting, you need to extend the converter.

[Alyaksej]

If I do that

= Document Title
Author Name
:title-page:

{authors}

<<<

remaining content

I have no TOC in my pdf document.
In my pdf document I need this order:

1. title page
2. copyright page
3. TOC
4. text
   Is it possible?

[mojavelinux]

= Document Title
Author Name
:title-page:
:toc: macro

{authors} or whatever

<<<

toc::[]

== Section

remaining content

You'll probably want to adjust the start_at value for the page_numbering and running_content in the theme as well.

[DaLynxx]

+1

Below 'my story' for the +1

For me the possibility to affect the content of the title page (and the layout/format) is important.

I have a pipeline starting from XML content which is transformed via XSLT to an asciidoctor formatted report. The customer has requirements on the resulting media, so it need to end up as a a pdf with several requirements on format and content including the the front page.

I managed to work around most of my issues by allowing "font page generator" into the pipe just in front of asciidoctor-pdf. Currently it imports an .svg template in which markers are replaced with the necessary meta-data. The .svg is then imported as the background-image for the title page.

I still got one issue left which is dynamic content that I do not have access to when the front-page-generator is running. The total number of pages of the report needs to be listed on the front-page.

A multi-pass solution is possible and probably where I will end up for now, i.e. run asciidoctor-pdf extract the number of resulting pages, update the .svg, re-run asciidoctor-pdf.
Actually it would be a nice feature if the verbose mode of asciidoctor-pdf would report on the number of pages generated.

Anyway, I vote +1 for any increased possibilities in manipulating affecting the content and format of the title page.
Regardless, tnx for a nice toolset.