Any way to force Asciidoctor EPUB3 to split chapter files?

Previous Topic Next Topic
classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

Any way to force Asciidoctor EPUB3 to split chapter files?


I'm finishing  the manual of a software project of mine. The Asciidoctor source
is built automatically by combining several documents of the project, including
parts of the README, with a lot of information extracted from the source code,
and marking the cross references during the process. Then the resulting
Asciidoctor document is converted into EPUB, PDF and other formats.

The result is great, except one problem with the EPUB format:

One of the chapters is a huge glossary, which becomes a 2-MiB XHTML file
in the EPUB. This makes the document too slow to open and navigate.

Is there any way to force the splitting of the contents into XHTML files
at a certain heading level?

Pandoc has an option for that:


        Specify the heading level at which to split the EPUB into separate "chapter"
files.  The default is to split into chapters  at  level-1  head‐ ings.   This
option only affects the internal composition of the EPUB, not the way chapters
and sections are displayed to users.  Some readers may be slow if the chapter
files are too large, so for large documents with few level-1 headings, one
might want to use a chapter level  of  2 or 3.

Unfortunately the cross references don't work in the EPUBs made from DocBook by
the current version of Pandoc.

On the other hand, the dbtoepub converter, which I also use in this project to
provide an alternative, simpler and lighter EPUB version of the manual, splits
the files at subchapter level by default.

Marcos Cruz