1

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.

rdmueller
  • 10,742
  • 10
  • 69
  • 126
Germo Görtz
  • 19
  • 3

2 Answers2

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
EhmKah a.k.a. Michael Krauße
  • 2,837
  • 5
  • 34
  • 53
  • 1
    it was also my first idea to use pandoc Then I found this issue regarding my question https://github.com/asciidoctor/asciidoctor/issues/3312#issuecomment-760128757 it looks like there exists also a script > You can find a script that uses the preprocessor reader in this way here: https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb and I have some hope this could be an asciidoctor extension: > I also want to add that once I publish the new version of the coalescer, I will strongly consider graduating it to a separate extension. – Germo Görtz Jan 16 '21 at 16:30
  • The script looks promising. Did you try it? Then it should be an answer here. – EhmKah a.k.a. Michael Krauße Jan 18 '21 at 09:18
  • I don't know how I should or could use this script. I am a database architect and developer. The doctoolchain solution with gradle worked out of the box. I was very impressed that I could easy use it not knowing Ruby or other languages. – Germo Görtz Jan 20 '21 at 00:01
  • Follow installation steps from https://asciidoctor.org/#installation than download script to a file and run it from the terminal with ruby scriptname.rb - hope this helps – EhmKah a.k.a. Michael Krauße Jan 21 '21 at 08:56
  • 1
    Yes, it was easy to install asciidoc. And it looks like the scripts does the job. I will evaluate in detail later. Thank yo! – Germo Görtz Jan 22 '21 at 11:45
1

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

Germo Görtz
  • 19
  • 3