asciidoctor-multipage

A multipage HTML converter for Asciidoctor—extends the Html5Converter to generate multiple HTML pages from the document tree.

See also:

• asciidoctor/asciidoctor#626
• asciidoctor/asciidoctor-extensions-lab#96
• https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/multipage-html5-converter.rb

Features

• Generates a root (top level) landing page with a list of child sections.
• Generates branch (intermediate level) landing pages as required, each with a list of child sections.
• Generates leaf (content level) pages with the actual content.
• Allows the chunking depth to be configured with the multipage-level document attribute (the default is 1—split into chapters).
• Supports variable chunking depth between sections in the document (by setting the multipage-level attribute on individual sections).
• Uses section IDs to name each page (eg. "introduction.html").
• Supports cross-references between pages.
• Generates a full Table of Contents for each page, but with relevant entries only (the TOC collapses as required for each page).
• Includes a description for each section on the branch/leaf landing pages (from the desc attribute, if set).
• Generates previous/up/home/next navigation links for each page.
• Allows the TOC entry for the current page to be styled with CSS.
• Supports standalone and embedded (--no-header-footer) HTML output.
• Retains correct section numbering throughout.

Notes and limitations

• Tested with Asciidoctor v1.5.7.1; inline anchors in unordered list items require the fix for asciidoctor issue #2812.
• This extension is tightly coupled with Asciidoctor internals, and future changes in Asciidoctor may require updates here. Hopefully this extension exposes ways in which the Asciidoctor API can be improved.
• Footnotes are currently not supported.
• Please contribute fixes and enhancements!

Usage

Be sure to use Asciidoctor v1.5.7.1. Other versions are not yet supported.

There is an extensive sample document under test/ that showcases the extension's functionality.

$ gem list asciidoctor$
asciidoctor (1.5.7.1)

$ asciidoctor -r ./asciidoctor-multipage.rb -b multipage_html5 \
    test/sample.adoc

Work needed

If you are interested in working on this extension, please consider the following:

• Update for use with the latest Asciidoctor release
• Add support for footnotes
• Add a test suite