I use Hugo for my blog, hosted on GitHub pages. One of the reasons I’m really happy with it is that I can use Asciidoc to author my posts. I was writing a blog recently in which I wanted to include some code that’s hosted on GitHub. I could have copied & pasted it into the blog but that would be lame!

With Asciidoc you can use the include:: directive to include both local files:

    include::/tmp/go_routine_errors.go[]

as well as external URIs:

    include::https://raw.githubusercontent.com/confluentinc/demo-scene/master/pipeline-to-the-cloud/data/mssql/b00_create_db_demo.sql[]

Note that you can also use source code formatting for these included files:

    [source,go]
    ----
    include::/tmp/go_routine_errors.go[]
    ----

For content from URIs you need to make sure that the security permissions are set when Asciidoctor is invoked, detailed here.

For using it from Hugo you need to do two things:

  1. make sure you’re on a recent version (I was on 0.54 and scratching my head until I upgraded to v0.75)

  2. add to your site configuration the necessary security permissions to be passed to asciidoctor:

    markup:
  asciidocExt:
    attributes: {allow-uri-read}
    safeMode: unsafe