Hugo

Libasciidoc - a Golang Asciidoc renderer

I’d like to start this thread so we can discuss the ongoing implementation of a better (faster!) Asciidoc solution than what we currently have.

The project is already on its way here:

I’m going to invite the author to participate here also, he’s mentioned that Hugo integration is a priority for him.

Since the Asciidoc Specification will be long and complex, this will surely take a long time and a lot of Community effort to get to a point where it’s on par with the existing Ruby Asciidoctor renderer.

I believe this thread can help us in that journey and I will be making some proposals in the following posts.

I work on an asciidoctor based site (source, site). I am very happy with Asciidoc as a format, but quite unhappy with the rendering times - Hugo’s beautiful speed is lost in the Ruby component.

I’d like to start trying out the new library as soon as possible, and I propose that this could be a nice way to proceed:

  1. Hugo adds a supported file extension (I earlier suggested .adocish but it could also be something like .libadoc) which calls the new libasciidoc engine. This means that the .adoc extension will remain attached to the Ruby libasciidoctor.

  2. So now I can leave all my existing files as they are, and the site will render fine. But my simpler files, without much formatting, without tables, etc., I can change their extension to the new one, and they will render with the new engine. The two engines can be used in paralell, and I get to select which one I use file by file.

  3. So we can get immediate speed improvements, and I get a way to progress incrementally in the amount of files in my site that are generated with the new engine, as it becomes more able.

  4. For the developers, this means more people can jump in immediately, and this will surely generate a force to get more code contributions. For example, if I need support for some table attribute that would allow me to put a dozen more pages into the new engine, I have an incentive to go an write the support for that attribute.

  5. At some point in the future, when libasciidoc is mature, and we are ready to drop the Ruby asciidoctor, we go back to using the standard .adoc extension, and the engine selection is done via a configuration file.

Thoughts, anyone?

A quick note from me;

I have been doing a major overhaul and split all the different content renderer ingegrations into their own packages. I’m currently working on making Goldmark the new standard for md/markdown extensions, and I will make that thing configurable (as I suspect it will break some sites, at least in short term).

With that it should be much easier to maintain and add LibAsciidoc, even if it’s not finished.

Note that you can also set the renderer to use via the markup variable i front matter, and that you can also use the cascade keyword to configure entire sections etc.

2 Likes

Thanks for the note. Let me see if I am catching this correctly…

  • So the markup front-matter would be a way of getting rid of my new extension and specifying the choice of renderer inside the file. That sounds better than my proposal, of course, much tidier.

  • and the cascade (I had never heard of it, just went off to read the Docs on it) is an easier, more practical way of setting that for entire folders instead of individually, is that it?

I am hoping when the libasciidoc author comes in this thread he can give us some instructions on how to set up the current version and start experimenting with it. I don’t know if there needs to be any change on Hugo’s side for this to be possible?

@pgr yes to both your bullets. Cascade is a fairly new construct – one of @regis 's great ideas.

But note that the cascading is recursive, so if you set it on the home page it will cascade down to … every page.

@bep @pgr All those ideas look great!

On the libasciidoc side, I’m willing to provide as many metadata as needed to ease the Hugo integration (I’m currently thinking about returning the title, authors, ToC, etc.). I have not taken the time to look at how to do the integration (yet besides a quick PoC, but that was quite a long time ago), but I would definitely love to see how the code is refactored so I can jump in!

Also, feel free to open issues to request features/etc. that would help with the Hugo integration. I’ve created a label to triage/track such issues :wink:

1 Like