Customize ASCIIDoctor Parameters?

support
1

I’m building a blog in Hugo for a big company website. We have a lot of articles that are markdown which work great, but we also have some more complex documents written in asciidoc which would be very difficult to move to markdown due to the features they use.

We’re using some custom asciidoctor tooling in our current jekyll site, and I’m trying to figure out how to make things work nicely with Hugo.

Basically, the Hugo docs showcase how it renders asciidoc files using asciidoctor: Content formats | Hugo

If there was a way for me to customize the commands that Hugo shells out to in order to handle the processing, I’d be able to update the commands to use what I need to get the job done. Is there anyway to customize the commands/arguments that Hugo calls when shelling out for asciidoc support? I can’t seem to find docs anywhere.

2

Looks like others have mentioned similar things in the forum before, so maybe you’ll find something useful in search?

I don’t use asciidoctor but apparently it’s just a script which you can fiddle with:
http://ratfactor.com/hugo-adoc-html5s/

3

asciidoctor itself is a program, but the link to asciidoctor-html5s shows you how to encapsulate the asciidoctor program in a script that uses asciidoctor parameters.

4

I am currently working on pull request that solves the Asciidoctor working folder problem but also adds possibilities to customize the parameters. Please have a look and give me comments: https://github.com/gohugoio/hugo/pull/6561

1 Like
5

In the meantime, here’s another workaround for adding CLI parameters to the asciidoctor call:

#!/usr/bin/env bash

# Get real asciidoctor:
# (credits: https://unix.stackexchange.com/a/108933/17409)
ad="$(
    PATH=":${PATH}:"
    PATH="${PATH//:$(pwd):/:}"
    PATH="${PATH#:}"
    PATH="${PATH%:}"
    which asciidoctor
)"

"${ad}" \
    --attribute=experimental=true \
    "$@"

This assumes that this script is called asciidoctor, lives in the Hugo project root folder, which is also the working directory and on the PATH when you call hugo. Then, Hugo will call this script, which will then in turn call the real program with an added option.

6

I really had hoped for a better integration between the two. I blogged several aspects of the challenges I had to resolve to meet what I would expect from this successful integration, I think it covers a bit more than some precious blog posts on the topic (but they all helped me a lot)

Some stuff are still not there, some may require some improvement, some are still in progress. I even considered asciidoctorj, it works but it is way to slow locally, I need to check how to improve that eventually. The most challenging thing for me was to port/adapt the ccs too the theme I chose. And there’s still some stuff I’m not happy with. But I’m not a web developer so I may let thing as they are to focus on content.

1 Like
7

In the meantime, a better solution has been implemented, merged, and released.

My workaround can now be replaced by adding this to config.toml:

[markup.asciidocext.attributes]
experimental = true

Thanks to all involved!