asciidoc, doctoolchain, target github readme.adoc - how to export asciidoc file containing includes into ONE file without include?

Question

GitHub supports asciidoc readme files, but it looks like "include" is not supported. I want to use doctoolchain which can render and export to html and pdf (and maybe into other formats). This tool works great.

I could use raw.githack.com to show the generated html file from the GitHub repository.

But I think it would be a good idea to have the result also as one (1) readme.adoc file.

How to export into one (1) asciidoc file, which I could use as it is as readme file so that github will render it and show? Best would be to use doctoolchain, when this tool will render my documentation it could also generate the one-file-asciidoc-documentation.

I think internally asciidoctor collects and merge all these "include" files. So maybe this file is already available in any place? The doctoolchain build folder contains only the target files.

Answer 1

You are right there is a long dicussion why includeis not supported by github.

You can achieve your goal with doctoolChain and pandoc(https://pandoc.org/). Following steps are required:

• configure your docDir/Config.groovy
  • inputFiles should have docbook defined
  • inputFiles = [[file: 'yourfile', formats['docbook']]]
• run the doctoolchain task generateDocbook - it creates ???.xml file somewhere in docDir/build
• generate from the generated docbook again an asciidoctor file - `pandoc <FILENAME_OF_GENERATED_DOCBOOK.XML> -f docbook -t asciidoctor -o <FILENAME_OF_ASCIIDOCTOR_WHICH_HAS_EVERYTHING>
• make sure it runs automatically and you commit it regulary
• now you are ready

Answer 2

This script can be used to resolve includes and to generate one (1) output file:

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb

some information about the script and possible next steps you can read here: AsciiDoc Backend (AsciiDoc 2 AsciiDoc) for preprocessing

to use it, ruby and asciidoc must be installed: asciidoctor.org/#installation