A configurable multipage HTML converter for Asciidoctor
This is free, open-source software! If you use asciidoctor-multipage, please consider contributing. In particular, if someone is interested in funding it, I would rewrite some parts of this extension to remove current limitations and resolve open issues (see issue #46).
asciidoctor-multipage is an extension for Asciidoctor that adds a configurable multipage HTML converter. It extends the stock HTML converter to generate multiple HTML pages from a single, large source document. The behavior is similar to a printed book where top levels (such as parts and chapters) are separated by page breaks (and perhaps blank pages) and lower levels (such as sections and subsections) are all included in a single chunk with styled headers to establish a visual hierarchy within the chunk.
This extension has also been used to generate a hierarchical website (from a content perspective, essentially multiple documents) from a single Asciidoctor document. While in some cases this might work fine (and you are free to use it this way), please understand that it is designed to work with a single, well-structured Asciidoctor document rather than as a website generator.
For an example of this extension in use, see https://owenh.net/nxlog-user-guide.html.
multipage-level
document attribute (the default is 1—split into chapters).multipage-level
attribute on individual sections).desc
attribute, if set).--template-dir
option is currently not supported. See issue
#19.This extension is published on RubyGems as asciidoctor-multipage. Install the gem by adding it to your project's Gemfile or gemspec and running Bundler. Or install it directly:
$ gem install asciidoctor-multipage
(Run gem install --user-install asciidoctor-multipage
to install the gem in
your user's home directory.)
Be sure to use Asciidoctor v2.0.11 or later.
$ asciidoctor -V
Asciidoctor 2.0.11 [https://asciidoctor.org]
The following command generates HTML output from a sample document; view the
output by loading test/out/sample.html
in a browser.
$ asciidoctor-multipage -D test/out test/black-box-docs/sample/sample.adoc
Alternatively, use Asciidoctor's --require
option like this:
$ asciidoctor -r asciidoctor-multipage -b multipage_html5 \
-D test/out test/black-box-docs/sample/sample.adoc
The multipage-level
and desc
attributes are the most important for using
this extension. For an example of the these attributes in use, see
test/black-box-docs/sample/sample.adoc
. These attributes work as follows:
multipage-level
document attribute specifies the section level at
which the book is split into separate pages. The value should be an integer
and matches the Asciidoctor levels. Note that as a physical book would
normally only have page breaks for the top one or two levels in the hierarchy
(such as part and chapter or chapter and section), a
multipage-level
value greater than 2 is generally not recommended.
0
splits into parts (h1),1
splits into chapters (h2)—the default,2
splits into sections (h3), etc.multipage-level
section attribute specifies the section level to use
for splitting the children of that section only. The integer given must be
equal to or greater than the values of all parent levels.desc
section attribute can be used to provide a description for a
section when it is listed on its parent landing page.Some additional attributes are available for customizing the extension's behavior:
multipage-disable-css
document attribute if you are using a
custom stylesheet. You will need to include your own rules for styling the
elements that are specific to multipage output. The default behavior (without
this attribute set) is to add a few CSS rules in the document header just
after the regular stylesheet—whether linked or embedded, default or
custom—using an automatically registered DocinfoProcessor extension.multipage-nav-previous-label
, multipage-nav-up-label
,
multipage-nav-home-label
, and multipage-nav-next-label
document
attributes. See test/black-box-docs/nav-labels/nav-labels.adoc
.If this project is useful to you, please consider supporting it through GitHub Sponsors, Liberapay, or some other way.
Other ways to contribute:
Thank you for your support! ✨
bundler install
.bundler exec rake
.bundler exec rake test BB_TEST_ONLY=sample
, where sample
is the name of the test to run.bundler exec rake test BB_UPDATE_FILES=1
to generate (or update) output HTML files for the
black-box tests.bundler exec appraisal install
to install dependencies andbundler exec appraisal rake
to run the tests.bundler exec asciidoctor-multipage -D test/out test/black-box-docs/sample/sample.adoc
(for example).bundler exec rake build
; the gem will be
placed in the pkg/
directory.asciidoctor-multipage.gemspec
, remove .dev
from the
version in lib/asciidoctor-multipage/version.rb
, run bundler lock
, and
commit the changes;bundler exec rake release
; andlib/asciidoctor-multipage/version.rb
(adding
.dev
), run bundler lock
, and commit the changes.Appraisals
as required,bundler exec appraisal generate
,.travis.yml
as required, andCopyright 2019-2024 Owen T. Heisler. MIT license.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
This source code may be used according to the terms of the MIT license. You
should have received a copy of this license along with this program (see
LICENSE
).