Generate single PDF from multiple Asciidoc files

Question

I'm trying to convert my existing asciidoc documentation into pdf. Asciidoctor-pdf seems quite easy and I'm able to convert single files into pdf.

asciidoctor-pdf -a pdf-theme='./theme/styles.yml' -a pdf-fontsdir='GEM_FONTS_DIR, theme/fonts/' 01-intro.adoc

But my docs are spread across many files. I want do create a single pdf from all those files. Does anyone know how to do this?

Secondly I don't want the generated pdf to be located next du the adoc file. I want to specify a target path.

I'd appreciate every hint. Thanks and best regards. Sebastian

Answer 1

The easiest and most convenient way is to use the VSCode editor with the AsciiDoc extension installed. This extension is developed by the same team that develops the AsciiDoctor text processor. This is a GUI-based approach to solve all your problems so I'm pretty sure u're gonna love it.

(Step 1) After the extension is installed, use the keyboard shortcut Cmd + , to go to the settings and then enter asciidoc.use_asciidoctorpdf in the search bar and tick the check box (see the demonstration below)

(Step 2) To create a single pdf file from multiple .adoc files, just simply put all of them in a single .adoc file with include::directory-to-the-adoc-file.adoc[] (see the illustration below)

(Step 3) Press F1, then type in as pdf and hit Enter to export this single .adoc file as a single PDF file, this will allow u to specify the target export directory for the PDF. Please be patient and wait for a few seconds for the export to complete, the editor will immediately inform u as soon as the export is complete (see the image at the bottom)

Answer 2

Have you considered to work with includes?

Just add to your document "01-intro.adoc" an any position this line:

include::02-next-file.adoc[]

When you build the 01-intro.adoc with your regular command, the contents of 02-next-file.adoc will be put to the position of the include line. Using this method we create a file with many includes and just build that file. We're very happy with that.