Using `front-cover-image` in book

[MarcL]

Hello.

Thanks for maintaining a great set of tools. I'm relatively new to the Asciidoc format and conversion toolchains so it might be user error, but I can't get a book front cover image to embed within a converted PDF.

My Asciidoc document is as follows:

= Book title
Marc Littlemore <my@email.com>
v1.0, April 18, 2020: First draft
:doctype: book
:front-cover-image: image:./book-cover.png[]
:toc:

include::01-first-chapter.adoc[]
include::02-second-chapter.adoc[]

I've tried both a book-cover.png and book-cover.pdf file and the image/PDF is in the same folder as the above document.

Is front-cover-image supported with the JS version of Asciidoctor PDF and am I using it correctly?

Thanks, Marc

[ggrossetie]

Hello Marc!

Thanks for maintaining a great set of tools.

:blush:

I'm relatively new to the Asciidoc format and conversion toolchains so it might be user error, but I can't get a book front cover image to embed within a converted PDF. I've tried both a book-cover.png and book-cover.pdf file and the image/PDF is in the same folder as the above document. Is front-cover-image supported with the JS version of Asciidoctor PDF and am I using it correctly?

This feature is not implemented but if you are familiar with CSS it should be relatively simple to reproduce it:

= Hoping This Works
:doctype: book

== Guessing

The first step is guessing.

@page :first {
  background-size: contain;
  background-image: url("./orly.jpg");
}

/* move the book title to the correct location */
#cover > h1 {
  color: white;
  margin-top: 8cm;
  font-size: 7rem;
}

And here's the result:

orly.pdf

I guess we should probably add it to the README. Feel free to submit a pull request to improve the documentation.

[MarcL]

Thanks, @Mogztter. That makes sense. I found the :front-cover-image: element from a Google search but I'm assuming it's only supported by the Ruby version. Would be good to identify the differences between the two perhaps?

Is there any documentation for all of the CSS identifiers and classes for each doctype? I think that would be useful.

I'll look at raising a PR to update documentation for you. No problem. 👍

[ggrossetie]

Thanks, @Mogztter. That makes sense.

Awesome! I forgot to add the command line used to produce the PDF:

$ asciidoctor-pdf -a stylesheet="asciidoctor-pdf/css/asciidoctor.css;asciidoctor-pdf/css/document.css;cover.css" orly.adoc

(I'm using ; as a separator but in the next version you should use ,)

I found the :front-cover-image: element from a Google search but I'm assuming it's only supported by the Ruby version.

The name of this project is a bit misleading. It's not really a port of Asciidoctor PDF from Ruby to JavaScript. The goal is the same but the technological stack is truly different. Asciidoctor PDF Ruby is using a Ruby library called Prawn while Asciidoctor.js (Web) PDF relies on the browser and the CSS Paged Media specification. At some point, we might implement this feature. It will basically add a few lines of CSS in the HTML page as described above.

Is there any documentation for all of the CSS identifiers and classes for each doctype? I think that would be useful.

No but I agree it could be really useful, especially for the title page.

I'll look at raising a PR to update documentation for you. No problem.

Thanks! Any help is greatly appreciated 🙏

[MarcL]

The name of this project is a bit misleading. It's not really a port of Asciidoctor PDF from Ruby to JavaScript. The goal is the same but the technological stack is truly different. Asciidoctor PDF Ruby is using a Ruby library called Prawn while Asciidoctor.js (Web) PDF relies on the browser and the CSS Paged Media specification.

Thanks for clarifying @Mogztter. It's a great project and I'd like to get involved in it. I've been looking for a framework to write up some ebooks that I've been meaning to work on. I originally went down the Markdown route and also found PrinceXML but that seemed too costly. I only found Asciidoc in the past week and it looks much more appropriate for building technical ebooks than anything else I've found. My last ebook was written using Canva. Something I don't want to repeat! 😆

I've got a few work-related things to get out of the way earlier this week but then I'll look to raise a PR for some documentation changes. Have you got a contributor's guide that you'd like me to follow?

[ggrossetie]

Thanks for clarifying @Mogztter. It's a great project and I'd like to get involved in it.

🎉

I only found Asciidoc in the past week and it looks much more appropriate for building technical ebooks than anything else I've found.

Indeed, AsciiDoc is a great choice for writing technical books. Quite a few people in the community could share their experiences about writing a book in AsciiDoc. I don't know if it's one of your requirement but we also have an EPUB3 & KF8/MOBI converter: https://github.com/asciidoctor/asciidoctor-epub3

I've got a few work-related things to get out of the way earlier this week but then I'll look to raise a PR for some documentation changes.

Excellent!

Have you got a contributor's guide that you'd like me to follow?

Not really 😅 The basic workflow is to create an issue so we can discuss and decide if this is something we want to do and how we want to do it. For documentation changes, you can directly open a pull request (unless you want to do major changes that need to be discussed first).