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:
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.
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.
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.
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.
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.
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.
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?
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
Every once in a while I come here and bump the Asciidoctor related threads…
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?
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:
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.
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.
Is there anything that a non (go) programmer can do to try libasciidoc in hugo for fun and feedback? I have my hugo asciidoc site running. Super happy with recent changes that allow customizing the asciidoctor parameters in config.yaml. Works great for me now. Thank you!
Thank you for your interest and for raising this question!
As the main developer of Libasciidoc, I’ve planned to work on a PoC to integrate the library in Hugo for a (long) while, but I’ve kept finding more issues to address before I could really start working on it. It’s however my plan for the next milestone and I’m looking forward to it!
Sorry for the late response, but yes, I’m finishing v0.8.0 and I think it will be time to finally move for good on the integration with Hugo! (Also, sorry for not making this happen faster)
Good news regarding speed when integrating Hugo with the ruby asciidoctor:
@bep the principle behind that is pretty simple (keep it running as a server, avoid the repeated startup costs) maybe it could be worked into the Hugo architecture for every integration? I’m not sure this makes sense, I’m just dreaming out loud
