Document how to create a new admonition type #9
Comments
|
When you only need a change that can be controlled by the stylesheet, I think the best approach is to simply append a role in the AsciiDoc content and then append the necessary CSS to match. In this case, we should view the admonition types as broad categories or levels that can be "specialized" using a role. In HTML, that will output: <div class="admonitionblock note think">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>A thinkspot admonition.</p>
</div>
</td>
</tr>
</table>
</div>If you want the value of the title attribute to be “Thinkspot” instead of “Note”, you can set the caption too. You can then customize the icon using CSS, which can be appended using docinfo or a custom stylesheet. .admonitionblock.think td.icon .icon-note:before {
content:"\f0eb";
color:#000;
} |
|
How would I add additional admonitions, like |
|
If you add a new admonition type, then you'd technically be introducing a new type of block (named QUESTION, for instance), which would need to be handled by a custom block extension. You could then map the result back to an admonition node so that the built-in handler takes care of generating the output for it. The icon is controlled by the "name" attribute (e.g., "icon-#{node.attr 'name'}"). It doesn't validate the name value, so it can be any value you want. You'd still need to add CSS to map that class to a Font Awesome icon. The fact that admonition types are controlled by the block name is kind of strange. In UniDoc, I'd actually like to see the admonition type be a special attribute, something like: That way, we aren't introducing new block types for each type of admonition. But that's a separate discussion. |
|
I thought of a way to mark this up for UniDoc (possibly supported in Asciidoctor before then). We overload the block title and allow a special prefix to indicate this is an admonition. That way, we aren't introducing a new block type for each admonition type. And it's much closer to the paragraph version (e.g., |
|
Thanks. Curious, what is this UniDoc thing you speak of? :-) |
|
UniDoc is an (eventual) goal of making a specification for AsciiDoc to make it easier to create tools and other implementations and to refine the syntax where necessary. For more info, see https://github.com/asciidoctor/asciidoctor/wiki/AsciiDoc-Specification-(aka-UniDoc)-Planning. |
|
Requiring a custom block type does seem like a bit much for adding a new admonition type. That I agree with. I would basically just like to get rid of this warning: If I do something like the README (which probably isn't the processing I want it to do) and require my file on the command line, that warning is still there. RUBY_ENGINE == 'opal' ? (require 'question-block/extension') : (require_relative 'question-block/extension')
Extensions.register do
block QuestionBlock
endclass QuestionBlock < Extensions::BlockProcessor
use_dsl
named :question
on_context :open
def process parent, reader, attrs
create_paragraph parent, reader.lines, attrs
end
end |
|
Can you show me an example snippet of the AsciiDoc source. That way I can
help debug.
|
|
Sure. Am I missing something here? [QUESTION]
====
1. How can you save your work when using The Go Playground?
====Also, my full command looks like this, in case it's just not loading for some reason: asciidoctor -r asciidoctor-pdf -r ./lib/sectnumoffset-treeprocessor.rb -r ./lib/question-block.rb -b pdf -a source-highlighter=coderay -a pdf-fontsdir=resources/fonts -a pdf-style=resources/themes/manning-theme.yml manuscript/*.adoc -D pdf/ |
|
That confirms my suspicion. The context is :example not :open. Make that
change and it should work.
|
|
Made the change, I still get the warning when generating a pdf. Maybe I shouldn't worry about it. As I understand it, my publisher is going to handle customizing the icons when they convert to DocBook. So I don't need it to look exactly right, which just means I get a warning when generating. |
|
On a completely unrelated note, why not use the Q&A syntax for this? |
|
...btw, I'm testing the extension... |
|
Aha! The style is case sensitive. The following will work. require 'asciidoctor/extensions'
class QuestionBlock < Asciidoctor::Extensions::BlockProcessor
use_dsl
named :QUESTION
on_context :example
def process parent, reader, attrs
create_paragraph parent, reader.lines, attrs
end
end
Asciidoctor::Extensions.register do
block QuestionBlock
endBtw, you probably want to create an admonition block instead of a paragraph in the process method. I'll try to fill in the details, then we can check this into the extension lab. |
|
Voila! require 'asciidoctor/extensions'
class QuestionBlock < Asciidoctor::Extensions::BlockProcessor
use_dsl
named :QUESTION
on_context :example
def process parent, reader, attrs
attrs['name'] = 'question'
attrs['caption'] = 'Question'
admon = create_block parent, :admonition, nil, attrs, content_model: :compound
parse_content admon, reader
admon
end
end
class QuestionBlockCss < Asciidoctor::Extensions::DocinfoProcessor
use_dsl
def process doc
'<style>
.admonitionblock td.icon .icon-question:before{content:"\f128";color:#000}
</style>'
end
end
Asciidoctor::Extensions.register do
block QuestionBlock
docinfo_processor QuestionBlockCss
end |
|
I'll put this into the extensions lab so we can hack on it there. |
|
It's there now. |
|
Thanks. It works. I haven't done any custom icons in the PDF (for TIP, etc.) but this works as well as those ones. As for |
|
The combination of |
|
When using Asciidoctor PDF, you need to define an admonition type for question in the custom theme. See https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#admonition. Otherwise, the icon resolves to nil. |
|
The HTML5 backend just relies on the stylesheet to sort out the icon, but Asciidoctor PDF actually has to look it up. |
|
Gotcha. I'll look into it, thanks |
|
That's also how you can customize all the icons in Asciidoctor PDF. Technically, you don't even need a custom admonition type if you just hijack the icon :) |
|
Hah. Guess I could've just hijacked the warning icon or something. Doh. I must be doing something wrong, as I don't quite understand the layout of the YAML. I either get that nil error or a admonition:
border_color: $base_border_color
border_width: $base_border_width
admonition_icon_note_stroke_color: 000000
admonition_icon_question_name: fa-question
admonition_icon_question_stroke_color: 000000
admonition_icon_question_size: 24
admonition_icon_experiment_name: fa-flask
admonition_icon_experiment_stroke_color: 000000
admonition_icon_experiment_size: 24 |
|
no change with admonition:
admonition_icon_tip_name: fa-questionerror admonition_icon_tip_name: fa-questionor admonition:
icon_tip_name: fa-question |
|
First, it has to be defined with the other admonition settings or else the theme is incomplete. admonition:
border_color: $base_border_color
border_width: $base_border_width
padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm]
icon:
question:
name: fa-question
stroke_color: 000000
size: 14But that brings us to a separate problem. The converter attempts to merge the theme data with the built-in defaults, but the built-in default is nil. So a change is needed to Asciidoctor PDF at line https://github.com/asciidoctor/asciidoctor-pdf/blob/master/lib/asciidoctor-pdf/converter.rb#L1786. |
|
With that change to Asciidoctor PDF, it works. I'll commit it. You'll need to use HEAD. |
|
Hm. I don't suppose putting this in my Gemfile and running bundle update is enough to get it working? gem 'asciidoctor-pdf', github: 'asciidoctor/asciidoctor-pdf'obviously not, it's still using alpha.10. hmmmm UPDATE: |
|
Sweet. The PDF looks pretty great.
There are some spots where it messes up, like when I have a quote or TIP inside the admonition. Those work fine when hijacking a different admonition, so it must be something in the CustomAdmonitionBlock code. Notice the byline is repeated below.
[EXPERIMENT]
.Experiment: malacandra.go
====
[quote, C.S. Lewis, Out of the Silent Planet]
"Malacandra is much nearer than that: we shall make it in about twenty-eight days."
Malacandra is another name for Mars in a SciFi trilogy by C.S. Lewis. Write a program to determine how fast their ship would need to travel in order to reach Malacandra in 28 days. Assume a distance of 56,000,000 km.
====Whether or not I should be doing that sorta thing is a whole other question. |
|
The implementation is a bit naive at the moment. Now that we have the
|
|
In short, we need to pass around attributes more carefully.
|
|
Fixed. Turns out I couldn't remember how to create a block extension right myself :) |
|
@nathany When you use a GitHub reference in your Gemfile, you have to run everything using |
|
Hah. I forgot about |
|
Excellent! Thanks for testing and providing feedback.
|
|
Thank you both for this. I have successfully added the four new blocks I need into a separate .rb file. Works a treat. The reason I wanted new blocks is to save having to remember which admonition I had mapped to thinkspot, etc. Now all I need to do is |
|
One more question. One of my new blocks uses a custom icon which I had got to work before by hijacking the icon in the master css file thus: Unfortunately, when I try this in the new block definition file: It throws errors when I try to run it through asciidoctor. Can I not use base64 images this way? Also, how do I get the new blocks to work as paragraphs too? E.g. Rather than always having to use block mode: |
|
Any suggestions on the base64 question? |
|
As an add-on question to the lovely discussion above. How hard is it to make a custom admonition block optional? So, if attribute "Teacher" is set, then all "Teacher" admonition blocks are included, otherwise they're not. In usecase lingo: An an author of school books I would like to have one source files that an be processed to a students- and to a teachers-edition (with extra included blocks to guide/hint the teaching process). I know I can create conditional text and that would work, but I' m just spoiled by all the fancy stuff Asciidoctor can do for me. :-) |
|
@kwoot I encourage you to direct your question to https://asciidoctor.zulipchat.com, where we can discuss usage scenarios as a community (without risk of going off topic). |
|
There is a custom admonition block extension in this lab. That's as far as we are going to take it here. |
I think it's an extension I need, but I'm not sure how to go about making one. Here's what I need:
I am converting a text book to various e-formats and the book has several in-text devices. Up till now I have been using the built-in admonitions and just created a new stylesheet to use different icons to match what I need. However, it seems to me that rather than subverting the existing admonitions it would be better to create new custom blocks for this project. For example, I need a block that looks and behaves exactly like an admonition except that it should be called
thinkspotrather thantip,caution,warning, ornote.Can someone give me a step-by-step on what to do?
Thanks!
The text was updated successfully, but these errors were encountered: