Add support for theming admonition blocks by type

[Hamsterbau]

Current behaviour

Currently if i want to use asciidoc pdf generator with theming, it is possible (thanks to another issue) to change basic stuff for admonition blocks:
https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#keys-admonition

Example:

admonition:
  background_color: f5f5f5
  border_color: 7d7d7d
  border_width: $base_border_width
  padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm]

Issue:
#444

But i cannot change these settings (especially background color) for a specific block type (e. g. caution in red or warning in orange).

Improvement: Admonition settings based on type

It would be nice to be able to configure admonition settings based on the current type.

Example:

admonition:
  caution:  
    background_color: ff0000
    border_color: ff0000
  warning:  
    background_color: ffa500
    border_color: ffa500

[mojavelinux]

Here's how you can implement this using an extended converter.

class PDFConverterAdmonitionThemePerType < (Asciidoctor::Converter.for 'pdf')
  register_for 'pdf'

  def convert_admonition node
    type = node.attr 'name'
    key_prefix = %(admonition_#{type}_)
    return super if (entries = theme.each_pair.select {|name, val| name.start_with? key_prefix }).empty?
    save_theme do
      entries.each {|name, val| theme[%(admonition_#{name.to_s.delete_prefix key_prefix})] = val }
      super
    end
  end
end

It works by temporarily overlaying the theme keys for a specific type onto the main admontion theme keys.

[mojavelinux]

This is going to be tricky to support by default since the admonition keys are a bit inconsistent. Both the label and icon can be configured per type, except the type comes after the element in the key name. Ideally, we would switch this all around so that the type is always the second segment of the key.

admonition:
  border-width: 0.5
  tip:
    border-color: #FFFF00
    icon:
      name: far-lightbub
    label:
      font-style: italic

Making that change would warrant a major version bump.

I'm also wondering whether the type should be in all uppercase so it is not confused with other key names.

admonition:
  TIP:
    border-color: #FFFF00

[lirantal]

Have been trying to figure this thing out too. Any chance we land this soon?

I've seen the note about the extended converter above, which is also great as a workaround. Would love to ask - if I used asciidoctor-pdf executable gem so far, how do I apply the extended converter to it so it works with my workflow?

[lirantal]

I ended up figuring out how to actually apply the extended converter (by specifying a -r converter.db argument to the asciidoctor-pdf CLI. Perhaps it is worth to update the docs with this information to make it easier to grasp for folks new to Asciidoctor / Ruby ? I'm happy to shoot a PR if you want me to.

[mojavelinux]

A pull request to update the docs would be most welcome.

[lirantal]

I ended up finding what needs to happen by reading:

1. This: https://docs.asciidoctor.org/pdf-converter/latest/extend/use-cases/#theme-admonition-per-type
2. Then understanding how to apply it by following the docs here: https://docs.asciidoctor.org/pdf-converter/latest/extend/create-converter/

What would be the best place to put these to make it easier for the next human who needs to sort this out?

[mojavelinux]

Given that you were the one looking for the information, I think you would be the best one to answer that question. Where did you expect to find it? Was this page not sufficient? https://docs.asciidoctor.org/pdf-converter/latest/extend/use-converter/ If so, what information would have helped?

[lirantal]

Well, in hope of being able to theme them, I was hoping to find it here: https://docs.asciidoctor.org/pdf-converter/latest/theme/admonition/

But, not being able to find any mention of it there threw me into a research sprawl.
Would it be fitting/possible to shoot up a PR to update that part of the docs?

[mojavelinux]

The issue is that the page you pointed to is about the theme keys, not about extensions. These are two separate things. But I suppose we could point out explicitly that it's not currently possible to theme admonitions by type, but there is an extended converter example in the use cases that shows you how you could do it. So I could see how that transition could work.

[lirantal]

The issue is that the page you pointed to is about the theme keys,

Right, but that's where I'd go to in order to find how to theme admonitions :-)
They are separate for you because you already have the context and knowledge that theming admonition per type is something that requires extra convertors but for a new comer, I'd expect them to just be another category key. After quite some research spent I realized that's not supported, but it certainly isn't obvious.

So anyways, I'm happy to make doc updates in multiple places too but am resorting to your guidance as to where that should go.

p.s. another place I'd stick some guidance is within the actual file

asciidoctor-pdf/docs/modules/extend/examples/pdf-converter-admonition-theme-per-type.rb

Line 1 in 803b575

class PDFConverterAdmonitionThemePerType < (Asciidoctor::Converter.for 'pdf')

(I'd suggest a README if it was within its own folder)

[mojavelinux]

Yep. Sounds good. I'll review and help revise what you suggest..

[lirantal]

Sure thing!

Here's one and another which I think would be helpful to make this information more available to developers.

[mojavelinux]

This information is now incorporated into the docs.

[lirantal]

Thank you!