# Libasciidoc - a Golang Asciidoc renderer

**URL:** <https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702>\
**Category:** feature\
**Tags:** asciidoc\
**Created:** [November 9, 2019, 11:01am UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702 "2019-11-09T11:01:49Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![pgr](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/pgr/32/5329_2.png) [@pgr](https://discourse.gohugo.io/u/pgr)\
**Post date:** [November 9, 2019, 11:01am UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/1 "2019-11-09T11:01:49Z")

</div>

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:

> **[GitHub - bytesparadise/libasciidoc: A Golang library for processing Asciidoc...](https://github.com/bytesparadise/libasciidoc)**
>
> A Golang library for processing Asciidoc files. Contribute to bytesparadise/libasciidoc development by creating an account on GitHub.

I’m going to invite [the author](https://github.com/xcoulon) to participate here also, he’s mentioned that Hugo integration is a priority for him.

Since the [Asciidoc Specification](https://asciidoctor.org/news/tag/specification/) will be [long and complex](https://asciidoctor.org/docs/user-manual/), 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.

---

<div class="post-metadata">

**Author:** ![pgr](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/pgr/32/5329_2.png) [@pgr](https://discourse.gohugo.io/u/pgr)\
**Post date:** [November 9, 2019, 11:15am UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/2 "2019-11-09T11:15:42Z")

</div>

I work on an `asciidoctor` based site ([source](https://github.com/salesagility/SuiteDocs/), [site](https://docs.suitecrm.com/)). 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?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [November 9, 2019, 5:30pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/3 "2019-11-09T17:30:08Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![pgr](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/pgr/32/5329_2.png) [@pgr](https://discourse.gohugo.io/u/pgr)\
**Post date:** [November 9, 2019, 5:42pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/4 "2019-11-09T17:42:40Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [November 9, 2019, 5:51pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/5 "2019-11-09T17:51:04Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![xcoulon](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/xcoulon/32/3942_2.png) [@xcoulon](https://discourse.gohugo.io/u/xcoulon)\
**Post date:** [November 10, 2019, 2:55pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/6 "2019-11-10T14:55:43Z")

</div>

@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](https://github.com/bytesparadise/libasciidoc/issues) to request features/etc. that would help with the Hugo integration. I’ve created a [label](https://github.com/bytesparadise/libasciidoc/labels/integration%2Fhugo) to triage/track such issues 😉

---

<div class="post-metadata">

**Author:** ![pgr](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/pgr/32/5329_2.png) [@pgr](https://discourse.gohugo.io/u/pgr)\
**Post date:** [January 14, 2020, 4:25pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/7 "2020-01-14T16:25:03Z")

</div>

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?

Thanks a million!

---

<div class="post-metadata">

**Author:** ![jcampbell](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jcampbell/32/404_2.png) [@jcampbell](https://discourse.gohugo.io/u/jcampbell)\
**Post date:** [May 8, 2020, 2:43pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/8 "2020-05-08T14:43:05Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![stiobhart](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/stiobhart/32/161_2.png) [@stiobhart](https://discourse.gohugo.io/u/stiobhart)\
**Post date:** [May 10, 2020, 5:19pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/9 "2020-05-10T17:19:04Z")

</div>

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:

> **[Them's Good Broth! | Hugo and AsciiDoc](https://stiobhart.net/2020-04-18-hugo-asciidoctor/)**
>
> Image Credit: half the bloody internet Table of ContentsIntroAsciiDoc Meets HugoWhat’s the matter with my Shortcodes?More problemsClunky Initial workaroundThe cause of the WARNINGsYour humble author again vainly asks for helpFirst attempt at a...

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

One thing that I noted from the original post here:

> [@pgr](#):
>
> 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’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.

---

<div class="post-metadata">

**Author:** ![bric3](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bric3/32/11033_2.png) [@bric3](https://discourse.gohugo.io/u/bric3)\
**Post date:** [May 11, 2020, 8:20pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/10 "2020-05-11T20:20:10Z")

</div>

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](https://blog.arkey.fr/2020/04/23/tackling-hugo-integration-of-asciidoctor/) if that can help someone.

---

<div class="post-metadata">

**Author:** ![Boyd\_Kelly](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/boyd_kelly/32/9034_2.png) [@Boyd\_Kelly](https://discourse.gohugo.io/u/Boyd_Kelly)\
**Post date:** [November 21, 2020, 12:49pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/11 "2020-11-21T12:49:47Z")

</div>

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!

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [November 21, 2020, 1:05pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/12 "2020-11-21T13:05:55Z")

</div>

> [@Boyd\_Kelly](#):
>
> Is there anything that a non (go) programmer can do to try libasciidoc in hugo for fun and feedback?

I don’t think so.

---

<div class="post-metadata">

**Author:** ![Boyd\_Kelly](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/boyd_kelly/32/9034_2.png) [@Boyd\_Kelly](https://discourse.gohugo.io/u/Boyd_Kelly)\
**Post date:** [November 21, 2020, 3:31pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/13 "2020-11-21T15:31:49Z")

</div>

uh… You could’ve at least said: “Learn go, we’d appreciate all the help possible…”

---

<div class="post-metadata">

**Author:** ![xcoulon](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/xcoulon/32/3942_2.png) [@xcoulon](https://discourse.gohugo.io/u/xcoulon)\
**Post date:** [November 23, 2020, 7:28am UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/14 "2020-11-23T07:28:34Z")

</div>

Hello @Boyd_Kelly 👋

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!

---

<div class="post-metadata">

**Author:** ![pgr](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/pgr/32/5329_2.png) [@pgr](https://discourse.gohugo.io/u/pgr)\
**Post date:** [May 1, 2022, 9:05pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/15 "2022-05-01T21:05:11Z")

</div>

@xcoulon any news on this front?

---

<div class="post-metadata">

**Author:** ![Boyd\_Kelly](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/boyd_kelly/32/9034_2.png) [@Boyd\_Kelly](https://discourse.gohugo.io/u/Boyd_Kelly)\
**Post date:** [May 1, 2022, 10:11pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/16 "2022-05-01T22:11:22Z")

</div>

Would love to be able to do something along these lines as well.

---

<div class="post-metadata">

**Author:** ![xcoulon](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/xcoulon/32/3942_2.png) [@xcoulon](https://discourse.gohugo.io/u/xcoulon)\
**Post date:** [May 24, 2022, 1:20pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/17 "2022-05-24T13:20:33Z")

</div>

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)

---

<div class="post-metadata">

**Author:** ![Boyd\_Kelly](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/boyd_kelly/32/9034_2.png) [@Boyd\_Kelly](https://discourse.gohugo.io/u/Boyd_Kelly)\
**Post date:** [May 24, 2022, 1:38pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/18 "2022-05-24T13:38:36Z")

</div>

Awesome!!! Exciting news!

---

<div class="post-metadata">

**Author:** ![pgr](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/pgr/32/5329_2.png) [@pgr](https://discourse.gohugo.io/u/pgr)\
**Post date:** [December 31, 2023, 5:56pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/19 "2023-12-31T17:56:54Z")

</div>

Good news regarding speed when integrating Hugo with the ruby asciidoctor:

> [@Asciidoctor Server](https://discourse.gohugo.io/t/asciidoctor-server/47475):
>
> I came up with asciidoctor-server to try improve the integration between asciidoctor and hugo. If you couldn’t guess by the name it uh … runs asciidoctor as a server. I use asciidoctor and hugo together, and really enjoy the combo. However, the performance is quite poor since hugo forks a process per file. Asciidoctor has a long startup time, in the 100’s of ms, and this adds up. I’d appreciate as much feedback and assistance as possible (the installation instructions make me cringe). Try it o…

@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

Happy new year everyone! 🎉

---

<div class="post-metadata">

**Author:** ![hybras](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/hybras/32/14551_2.png) [@hybras](https://discourse.gohugo.io/u/hybras)\
**Post date:** [January 7, 2024, 3:59pm UTC](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702/20 "2024-01-07T15:59:32Z")

</div>

> [@pgr](#):
>

I appreciate your enthusiasm, but my solution is in the alpha/POC stage. I should’ve made that clearer.

[Next page](https://discourse.gohugo.io/t/libasciidoc-a-golang-asciidoc-renderer/21702.md?page=2)