I recently worked on an issue where a perfectly fine ASCIIDoc file didn’t render properly in GitHub. At first I thought it was a broken file reference, but when I used the preview in my IDE I noticed that the syntax and link to the file are both correct. And yes, you can tell I’m new to ASCIIDoc :)

Here’s a screenshot of my document not rendering the way I intended in GitHub:

The Terraform example in section 2.3 should have displayed the contents of ./main.tf instead of a line starting with link:

As it turns out this is a long standing problem, see issue 1095 in GitHub. The relevant section from the source file reads:

=== Python Example

This is equally useless Python code.

[source, python]
----
import os
print ("hello ASCII doc")
----

=== Terraform Example

Unlike the previous examples the Terraform code is imported. This might not render properly in Github.

[source, hcl]
----
include::./main.tf[lines=1..-1]
----

You should see the configuration of a `provider {}` block

I didn’t go to great length with the Terraform code, all it does is show the definition of the Oracle Cloud Infrastructure provider:

#
# configure the Terraform Provider for Oracle Cloud Infrastructure
#
provider "oci" {
  fingerprint          = var.api_fingerprint
  private_key_path     = var.api_private_key_path
  region               = var.region
  tenancy_ocid         = var.tenancy_id
  user_ocid            = var.user_id
}

# add some actual code next...

Interestingly most IDEs render the ASCIIDoc correctly, they shown the combined text from both files even in preview mode. It’s really down to the aforementioned issue in GitHub that my file doesn’t render the way I have in mind.

Working around the problem

In an attempt at trying to save you 5 minutes I’d like to show you a potential workaround using asciidoctor-reducer. I opted to install it in a container, this way it should be easier to use it in my CI pipeline. The exact way you choose to invoke the tool does not matter, the actual call is most likely very similar to this:

$ asciidoctor-reducer my.adoc -o my-reduced.adoc

If you can use GitHub actions in your project you might want to have a look at an example featuring GitHub actions instead.

The asciidoctor-reducer post-processor combined the files, instead of an include directive the contents of main.tf was present in the ASCIIDoc file.

$ diff my.adoc my-reduced.adoc
55c55,67
< include::./main.tf[lines=1..-1]
---
> 
> #
> # configure the Terraform Provider for Oracle Cloud Infrastructure
> #
> provider "oci" {
>   fingerprint          = var.api_fingerprint
>   private_key_path     = var.api_private_key_path
>   region               = var.region
>   tenancy_ocid         = var.tenancy_id
>   user_ocid            = var.user_id
> }
> 
> # add some actual code next...
63d74
< 

This is a solution that works quite well for me personally. All I have to do is plug the container into my CI pipeline and have the tool create the combined document for me. Since I can review/test all inputs separately there is no need for me to check the generated file back into git. An alternative way of automating the generation of the reduced document is to create a pre-commit git hook. As with everything, possibilities are endless. Just pick the one that works for you.

Summary

Until there is no support for the include directive in GitHub, ASCII Doc workarounds are needed for documents to be rendered with the correct information. Using asciidoctor-reducer is a great option since it generates the desired results without requiring duplication of content.

As with all open-source tools make sure their license is compatible with your use case/company. I haven’t tested the tool thoroughly yet, so please ensure you comfortable with the way it works, especially with regards to unwanted side effects. This post is not an endorsement of either ASCIIDoc nor asciidoctor-reducer: use at your own risk and always have a backup ;)