Is it possible to have modular AsciiDoc book (that consists of few files)?

Question

Considering that a book in DocBook format can be done in a "modular" fashion, I hoped I can do similar with AsciiDoc and split chapters and first-level sections in separate files. Unfortunately documentation does not say anything about this. The only possible solution I see so far is to write my own AsciiDoc preprocessor that will merge all "part"-files and generate the book. Did someone solve this problem by now?

Baxie

Answer 1

Two example ways from the asciidoc cheatsheet: http://powerman.name/doc/asciidoc

include::footer.txt[]

or

[source,perl]
----
include::script.pl[]
----

Millepede

Answer 2

I have set up a book template that I use in all by book, you can find it here: asciidoc-book-template-with-rake-and-github

= Nome da disciplina
:doctype: book
:lang: pt-BR
:ascii-ids:
:showcomments:
:gitrepo: https://github.com/xxx/yyy
:code_dir: code
:image_dir: imagens

include::capitulos/prefacio.adoc[]

////
= Nome da Parte =
////

include::capitulos/cap1.adoc[]

include::capitulos/feedback.adoc[]

include::capitulos/cap2.adoc[]

include::capitulos/feedback.adoc[]

include::capitulos/cap3.adoc[]

include::capitulos/feedback.adoc[]

// ...

include::capitulos/glossario.adoc[]

include::capitulos/respostas.adoc[]

////
Always end files with a blank line to avoid include problems.
////

Note the blank lines between the include directives: they prevent the first and last lines of the included files from being adjoined. I don't split chapter on more files because when you include a file asciidoc takes the included file path to be the parent of new includes, look this tree:

.
|-- capitulos
|   |-- cap1.adoc
|   |-- cap2.adoc
|   |-- cap3.adoc
|   |-- code
|   |   `-- cap1
|   |       |-- helloworld.c
|   |       `-- Makefile
|   |-- feedback.adoc
|   |-- glossario.adoc
|   |-- prefacio.adoc
|   |-- respostas.adoc
|   `-- symbols.adoc
|-- docinfo.xml
|-- livro.asc
`-- wip.adoc

• When I'm at the file livro.adoc and I what to include feedback.adoc I will use include::capitulos/feedback.adoc[]
• But if I'm at the file cap1.adoc you will have to use include::feedback.adoc[] (since they are at the same directory).

I think it's more easy to keep all includes in one same place, it works for me. I only include codes using the other way.

Gravitt

A good folder structure. Especially, when you have additional source code documents for each chapter. – Dubitable

I'm not sure, but I think that asciidoc and asciidoctor tools includes files differently. You must use the structure that you tool supports. – Gravitt

Answer 3

Here is another example in case anyone is looking how to do this.

Book Title Goes Here
====================
Author's Name
v1.1, 2012-11
:doctype: book
:icons:
:max-width: 45em

// Push titles down one level
:leveloffset: 1
include::chapter1.asciidoc[tabsize=4]

include::chapter2.asciidoc[]

include::chapter3.asciidoc[]

include::../../common/appendix/MigrationNotes.asciidoc[]

include::glossary.asciidoc[]

// Return to normal title levels
:leveloffset: 0

Index
=====

Aloud

Answer 4

One option is covered in the user guide: https://asciidoc.org/userguide.html#X90

To paraphrase the user guide, create a top level wrapper document which uses include:: macros to add the desired content and :leveloffset: attributes to adjust the heading levels.

Another option would be to write a script that would cat all the part files together then pass the result to asciidoc using stdin. That might look something like cat part1.txt part2.txt part3.txt | asciidoc -. Please note that there appears to be issues sometimes when providing input via stdin. Also note extra line breaks may be needed at the end of each part file to prevent cat from affecting the formatting.

Sensuality