Hugo has great support for Markdown. It works out-of-the-box altogether. However, I like Asciidoc more so I tried to set up the platform for writing pages with lots of source code listings. It became a task for masochists. If you are okay with Markdown, you should probably stay in that realm and enjoy simplicity.

I tried several approaches. None of them seemed to work for me.

What helped in the end, was rendering the source code highlights directly with Asciidoctor and embedding the styles into html tags. I found this article and basically followed the steps with several modifications.

Installing the necessary tools/libraries
gem install asciidoctor asciidoctor-html5s asciidoctor-diagram pygments.rb

Hugo launches asciidoctor in default settings so the code syntax highlighting does not work. There is however a workaround. You need to 'hack' the asciidoctor launcher. Create a file called asciidoctor in the Hugo project root and then set the $PATH to look for this file.

I have set up the syntax highlighting to pygments with monokai style. Choose whatever style suits you and your page.

asciidoctor file in your project root
#!/usr/bin/env bash

/usr/local/bin/asciidoctor \
-r asciidoctor-html5s \
-b html5s
-r asciidoctor-diagram \
-a source-highlighter=pygments \
-a pygments-linenums-mode=inline \
-a pygments-css=style \
-a pygments-style=monokai "$@"

Don’t forget to set the execute permissions

chmod u+x asciidoctor

Set up the Path so that the custom asciidoctor is looked up first.

launch-hugo-server
1 #!/usr/bin/env bash
2 export PATH=$PWD:$PATH
3 hugo server -D

Make the script executable.

chmod u+x launch-hugo-server

Now you can call ~/wherever/my/project/is/launch-hugo/server to start the hugo server and live-view the rendered pages. If you would like just to build the pages without serving them, modify the script accordingly.

Links⌗