HUGO

Libasciidoc - a Golang Asciidoc renderer

feature
#1

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.

#2

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?

#3

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
#4

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?

#5

@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.

#6

@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:

2 Likes
#7

Every once in a while I come here and bump the Asciidoctor related threads… :smiley:

I’d just like to reach the point where things are sufficiently advanced for the Community to really gather around this project and help. I predict (hope?) there will be quite a few interested people.

@bep can you give us some pointers as to what would need to be done to get a proof-of-concept Hugo site rendering a page via libasciidoc? That work you recently did for Goldmark, has it brought some progress to this goal?

Thanks a million!

#8

I’m interested in this work, as well. Having a performant way of using asciidoc in hugo would be of great use to documentation projects.

1 Like
#9

A bit of thread archaeology from me, as I’ve recently moved my 300+ page Hugo site from Markdown to AsciiDoc and run up against this dramatic slowdown in site rendering.

I’ve written about the hassles and hurdles of making the change here:

https://stiobhart.net/2020-04-18-hugo-asciidoctor/

if anyone wants a peep at what they may be letting themselves in for!

One thing that I noted from the original post here:

I’m not entirely convinced that “the Ruby component” [ie. asciidoctor] is the cause of the massive slowdown that Hugo experiences with AsciiDoc authored sites.

As mentioned in the article I linked to above, I ran the asciidoctor gem standalone on my Hugo site content folder and it converted 300+ .adoc pages to HTML in about 2 seconds. Likewise, Hugo would build the previous Markdown version of my site in [if I remember correctly] about 10 seconds. This has now gone up to around 60 seconds, for the AsciiDoc version.

So both asciidoctor and Hugo are sufficiently speedy individually. It’s just when acting in tandem, that things grind to a crawl. It will be interesting to see if the advent of a native Go-powered Libasciidoc will improve things on that front.

#10

Have you tried asciidoctorj, while it’s probably not interesting for few documents it may prove useful for a large set.

Unlike you I decided to keep existing markdown content so I just have a few ones now mostly in draft. AsciidoctorJ was prohibitive locally, I haven’t looked much though if I could improve the command line though.

I’ve written about it here tackling Hugo integration of Asciidoctor if that can help someone.