It is possible to cross-reference chapters in Asciidoc. The way I do it is as follows. First of all I have a top level index.adoc which is the root file that does nothing but include the various chapters one after another. I run the asciidoctor-pdf program on index.adoc. The include directive literally includes the content of another file. What this means is that if you have a 10 line index.adoc which is just including 10 chapters, the end result is as if you had manually copied and pasted the content of those 10 chapters into index.adoc and then run asciidoctor-pdf on top of it.
So in the end its as if asciidoctor-pdf was run on a single file. The normal rules of cross-referncing apply. In documentation you will read that to cross-reference a section from another chapter you have to prefix with filename of the chapter like so <<chap10.adoc#results>>. However you precisely don’t have to do this – at least if you are using the setup described above. Everything ends up as one single file you can can cross-reference content of another chapter like <<results>>. Indeed if you have two chapters and you give the same ID to two sections then there is a collision and conflict at time of cross-referencing. asciidoctor-pdf will issue an error.
Before beginning each chapter I have following preamble stored in a common-settings.adoc:
:figure-number: 0
:listing-number: 0
:table-number: 0
:figure-caption: Figure {counter:chapter}.
:listing-caption: Listing {chapter}.
:table-caption: Table {chapter}.
The figure-number , listing-number and table-number seem to be in-built counters whereas chapter is a counter I define in my book’s preamble.
One tip: With this setup, AsciiDoctorPDF runs into trouble cross-referencing listings and tables of other chapters (cross-referencing within chapter works as expected). Rather than hacking your way around it – which is very difficult – cross-reference the relevant section.
