Re: access to the document components during or after rendering

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: access to the document components during or after rendering

mojavelinux
Administrator
Michael,

On Mon, Jun 30, 2014 at 1:44 PM, Michael Hunger wrote:

I haven't found time to figure out yet where to look for the means that you need to access certain elements of the asciidoc-document either during or after parsing with asciidoctor. 

I'm especially interested in things like, attributes, titles, sections, blocks (cypher), images etc.

The best place to look for information about the API right now is the Ruby API docs for Asciidoctor. You'll want to focus in particular on the Extension APIs, AbstractNode and AbstractBlock.


The API docs look a lot better when you render them locally because they use a syntax that rubydoc.info doesn't parse entirely right. Just clone the repo, run the doc task, then look in

    cd asciidoctor
    rake yard

Open rdoc/index.html in your browser and start exploring.
 

I want to look into the server-side rendering of graphgists and instead doing the jquery selection on the rendered HTML I thought it would much easier and faster to access those elements and information during the asciidoctor rendering process.

Absolutely. I think that postprocessing HTML should always be considered the last resort. That usually means that an extension point wasn't available or wasn't sufficient to meet the requirements. Of course, there are times when postprocessing the HTML is appropriate, but it should be the exception rather than the rule.
 

So if you have any pointers about the API, visitors, callbacks, datastructures or examples that I could look into, I would very much appreciate that.

The Extension API docs are the most complete in all of Asciidoctor, so I certainly recommend reading through those. The main data model is the AbstractNode and AbstractBlock. You'll notice that Asciidoctor mostly uses a "schemaless" model to keep things simple and flexible...so you won't find specific types for each block context (i.e., sidebar, listing, etc). Most of the data for a block gets stored in its attributes.

You can also check out the Asciidoctor extension labs to get ideas about where to tap into the parsing:


If you have more questions or suggestions, please feel free to post them on the list. There are many innovators around here to help get you going!

Cheers,

-Dan

p.s. I'm very aware that I need to write more docs for Asciidoctor, especially in regard to how to build on it and extend it. That's a major focus after the 1.5.0 release.

--
Reply | Threaded
Open this post in threaded view
|

Re: access to the document components during or after rendering

mojavelinux
Administrator
I almost forgot to mention. We plan to make all the extension points available in AsciidoctorJ and Asciidoctor.js as well. In fact, they are already available, but we continue to work to improve the accessibility in those environments for extension writers.

-Dan