Development discussions (i.e., software architecture and project management) about Antora, the static site generator for making documentation sites based on AsciiDoc.
Debugging this is difficult, since there is a lot of context in flight. A single
console.log tends to emit hundreds or thousands of lines of detail.
👍
if you are making a custom block, then onContexts determines which block delimiters it can be used on. so, for example, to use it over a
====, you set it to example (technically, this is not a context, but rather a structural container, but here the term is used interchangeably)
this does not apply to block macros, only blocks
this is information that still needs to make its way into the docs: asciidoctor/asciidoctor-documentation-planning#30
basically, for 5 years (in some cases more), all docs issues stalled because Antora didn't exist
I expect things to change radically now that we have a real documentation site and not just some strung together pages
you could almost argue that the problem with docs in Asciidoctor is what led us to create Antora. It was always in the back of my mind, but that really forced it over the edge. so this is very much coming full circle right now
I kept filing issues with information, but it was just never going anywhere
indeed!
on the other hand, I cannot do it all myself. I already work close to 24/7/365 days of the year (that's hardly an exaggeration)
(accepting that has been very hard for me to do)
After trying a few variations, these few lines appear to do what I’m looking for:
const wrapper = self.createBlock(parent, 'open', [], {})
self.parseContent(wrapper, output.join('\n'))
parent.blocks.push(wrapper)The next iteration would be to remove the open block, which likely means creating each listing block separately.
Actually. what’s happening is that the markup for the source blocks is being parsed correctly, but the
include within is appearing as text, rather than functioning as an include. What would I need to do to achieve that?
Likely, I need to enable macro substitutions. :-)
It’s been a while since I looked at this bit of code. You might need to do something like turn your generated content into the sort of reader that can deal with includes. This is when I end up spending serious time with the debugger:-)
Alternatively you might consider doing the includes yourself using the antora content catalog.
Alternatively you might consider doing the includes yourself using the antora content catalog.
Back at my computer... Yes, you need to make sure you supply a PreprocessorReader rather than a plain Reader, which is what you get calling parseContent with just text. You can see an example that works (but probably has a lot more Opalese than you need) in my https://gitlab.com/djencks/asciidoctor-ainclude in lib/ainclude.js line 105.
2 replies
you only use parseContent when you need to convert it, then extract something, then put it back into the tree
that's rare
since you are writing extensions in asciidoctor.js, you may want to bring it up in the asciidoctor/asciidoctor.js channel. I'm sure Guillaume would be keen to get more advanced examples added to the new docs: https://asciidoctor-docs.netlify.app/asciidoctor.js/latest/extend/extensions/
that's really where information about writing extensions in asciidoctor.js should point. Antora should really only cover it to the extent of how to integrate them into the playbook and perhaps how to access Antora's context
part of the focus of the new docs is to make sure the docs for each project is providing the docs for its own part and we aren't trying to duplicate docs all over the place
hmm, re using an explicit PreprocessorReader, I guess my example needs it because of some faulty assumptions in asciidoctor about subdocuments (that they are always table cells).
yes, it would be useful to talk about extensions in general (showing the signature in a pseudo language perhaps) and then getting into specific Ruby examples separately. since the extension model is defined in Asciidoctor, those docs would live in Asciidoctor. but they don't have to jump right into the Ruby API specifically. as for showing a specific example in different languages, that's a big trickier. I'd have to think about that. because I don't really want the examples for AsciidoctorJ and Asciidoctor.js to cross over into Asciidoctor. but we could maybe imagine importing it from the other repo (using an include) if it is present.
but before we get into all that, I think we need some basic concrete docs in the interim because I think the extension model is really glossed over for being such an important part of Asciidoctor
:+1: