asciidoctor
Support callouts for images (callout list without callout refs)
I would like to be able to insert images containing callout markers (hand-edited), followed by a callout list explaining the image. Asciidoctor warns that the callout references don't exist.
I'd like a way of specifying that a callout list refers to an image, so that Asciidoctor does not generate those warnings. (I'm not necessarily asking for Asciidoctor to add the callout markers to the image.)
Reference: DocBook imageobject with callout list
Probably the best thing to do here would just be to have an option to disable reference checking. In other words, a discrete callout list. In fact, we could borrow the discrete style from headings for this purpose, essentially telling the parser not to go looking for the target.
I don't think trying to correlate it to references in the image would make much sense since Asciidoctor can't validate the image anyway. And itemizing the location of all of them in the image is just the kind of busy work AsciiDoc aims to get away from.
Having the same issue, would like to disable the no callout found error for images with callouts for result below:
The work-around I found for this is to copy the css class .conum[data-value]{...} to .conum{...}. Just make a copy of the class and remove the [data-value] specifier. Then each line can be:
[.conum]#1# Home page is a _branch_, therefore `_index.md` file is *required*.
Result can be seen here:
https://bubbleuptoppop.com/hugo/bundles-folders/
Probably the best thing to do here would just be to have an option to disable reference checking. In other words, a discrete callout list.
On further thought, I think this would be a bad idea. It would likely lead to an abuse of the callout list and would not provide any way to validate that it has something to map to for reference purposes.
Now, obviously, AsciiDoc cannot see callout numbers in the image. But what we could do is allow the author to itemize which callout numbers the author sees in the image using the callouts attribute (e.g., conums=1;2;3;4;5 or conums=1-5). That gives the callout list something to check against.
Another approach would be to introduce the circled style on the ordered list that would decorate the numbers in exactly the same way they are decorated in the callout list. This would give the author who really wants to manage the callout association outside of AsciiDoc's referencing system a way to do it. So maybe it's not even an either/or proposal, but rather two solutions.
While the suggested workaround might give someone a way out of situation where they are getting pressure, it should not be considered a recommended practice. It misuses AsciiDoc as a means to an end rather than using it to make clean, semantic content.
But what we could do is allow the author to itemize which callout numbers the author sees in the image
I think I prefer this approach. Perhaps as well as / instead of a conums attribute, authors could list callout numbers in the image's alt text? So, for @sittim 's example above, something like:
image::ebike.png['Bicycle with electric motor <1> <2> <3>']
I think that a circled style on the ordered list would quickly get repurposed for other uses, and authors would then have no way to be sure that that a circled ordered list would be formatted in the same way as regular callout lists. I'd prefer callout lists for images to have the same semantic markup as a regular callout list.
If you add an extension to your setup:
require('@asciidoctor/core')
module.exports = function (registry) {
registry.treeProcessor(function () {
const self = this
self.process(function (document) {
document.findBy({'context': 'olist', 'style': 'calloutlist'}, function (list) {
list.context = list.node_name = 'colist'
})
return document
})
})
}
Then by adding a calloutlist as a style to an ordered list, the compiled list will then take on the style of a callout list – but you don't have to associate with a listing block or anything else.
[calloutlist]
. This is a test
. This is another test
It's a bit of work, but the advantage is that it will look exactly like a regular callout list (which is built using tables and styles and can be pretty tricky to mimic in raw Asciidoc).
The disadvantage is that it sort of piggy-backs of the existing callout setup, so it always uses numbers.
Please note that the previous instructions only apply if you are using Asciidoctor.js.
For anyone interested in using the aforementioned extension, please direct questions about it to the project chat at https://chat.asciidoctor.org. Let's not have this thread veer off course.