Porting any wanted API additions in Raise

[danShumway]

Quick heads up, I've pulled my site's generation code out into its own project, Raise. It uses a number of enhancements from this repo, but provides a wrapper around AsciiDoctor with a few additions.

Many of the API additions I'm supporting will probably end up not making sense in the core AsciiDoctor template system (many of them are unrelated to templates anyway). A few of them might make sense for me to rip out and submit as pull requests here.

A few things I either support now or am planning to support in the future that could be relevant:

• asynchronous templates: AsciiDoctor is not async right now, I'm going to try to put together a hacky system to allow asynchronous templates in Raise. This is necessary because I eventually want to support templates from non-JS sources (python, ruby, shell scripts, etc...) and they need to be executed as separate processes.

• template_dirs as an attribute inside of a doc: Because I want people to use Raise primarily from the command line, templates are per-page and specified within the AsciiDoctor document, not in code. Would it make sense to have a similar option for core templates?

• CSS compilation: I believe that AsciiDoctor already supports this in a more official way than what I have kind of hacked together for Raise. I haven't checked to see if AsciiDoctor.js supports the same API yet (ie, was Compass ported to JS alongside AsciiDoctor). That's likely something that should be handled separately from template support though.

And then some miscellaneous stuff that likely is not worth porting: renaming pages (test.html -> test/index.html), allowing Babel compilation and minification for Javascript, adding timestamps to scripts/css to get around caching, etc...

[s-leroux]

Great work you did with Raise, Dan!

• asynchronous templates: this is definitely something I wanted to add to the JS templating system. I planned to add a couple of Promise-returning wrapper around the high-level API like load, convert or the template-file loading facilities. I assumed besides the basic document I/O, the AsciiDoctor core was not performing (too much) blocking calls. But I may be wrong here.
  I like your idea of allowing to run the template engines as a separate process. I don't know if this is feasible, but we may envision a system preforking a couple of worker co-processes to increase parallelism.
• template_dirs as an attribute inside of a doc: I've investigated that option in my earlier attempt at leveraging AsciiDoctor to generate websites. But I end up thinking it would be best to maintain a clear separation between the content (the document) and the presentation. In my case, for example, I may produce HTML, plain text and XML output from the same document. Of course, YMMV.
  If I remember it well, I also have some issues because to access the document attributes, you have to parse first the document. But to parse it, you must already provide the renderer. We may imagine a solution passing a proxy renderer initially, and that latter instantiating the real renderer when it found the necessary pieces of information in the document. But I didn't pursue in that direction.
• CSS compilation: As of myself, I think this is out of the scope of the template engine. The core reason is I want the template engine to remain output-agnostic. Even if a good share of use cases would be generating HTML from AsciiDoctor documents, this is not mandatory, and I wouldn't open the door to output-specific features. But if you think such facility is really needed during the document conversion phase, we may consider adding a hook somewhere so you can provide custom actions at key events.

[danShumway]

We may imagine a solution passing a proxy renderer initially, and that latter instantiating the real renderer when it found the necessary pieces of information in the document.

Yep, this is exactly what I'm doing - build the document tree, pull out the attributes, throw away and regenerate the tree. It's pretty hacky.

Also agreed on CSS compilation being a separate scope, I only brought it up because I suspect that AsciiDoctor's built in compiler is in the same state as their template engine was: works in Ruby, not in JS. Definitely a separate effort, but if I start to work on something like that I'll probably try to mirror the same strategy you set up for templates.

I agree with you for the most part on separating presentation and content, but it's also really useful for site generation to have attributes bundled closely to the source of a page. I need to keep thinking about how linking works, I suspect there's a cleaner, more generic way to do stuff like this that won't railroad people into only supporting HTML.

I suppose what I'm actually looking for is a way to designate a role for a document. A blog post is likely going through a separate template from a homepage. With template_dirs, the way you'd handle that is by hard-linking your template directory to the page, which I agree is not very friendly if you want to support multiple output types. Theoretically, with a category or role I would handle that by (at compile time) filtering out all of my blog posts and then compiling them with a separate template_dirs.

It's quite possible that AsciiDoctor already supports something like that, sometimes I miss a feature and get surprised by it later. Also (likely) outside the scope of the templating engine itself, but I'll keep thinking about it.

[s-leroux]

I suppose what I'm actually looking for is a way to designate a role for a document. A blog post is likely going through a separate template from a homepage. With template_dirs, the way you'd handle that is by hard-linking your template directory to the page, which I agree is not very friendly if you want to support multiple output types. Theoretically, with a category or role I would handle that by (at compile time) filtering out all of my blog posts and then compiling them with a separate template_dirs.

That's mostly how I handle things myself. But my workflow is slightly different since for the website I pre-process all documents as embedded HTML. But I attach a custom "category" attribute in the document header which is used by the web server to identify at runtime in which page template the embedded HTML should fit. This is a kind of hybrid static/dynamic architecture.

But indeed, that would be an improvement if we could somehow choose the "right" set of templates while processing the document.

XSLT has the notion of mode. Maybe we could leverage something similar. So, in the document template (or any other one BTW), you could change the current mode based on a document attribute or anything else and then, for processing subsequent elements, only templates corresponding to that mode would be considered, until you eventually change mode again.