The project is in a healthy, maintained state
A tool that reduces an AsciiDoc document with includes to a single AsciiDoc document by expanding the includes reachable from the specified parent document.


~> 13.0.0
~> 3.10.0


 Project Readme

Asciidoctor Reducer

Asciidoctor Reducer is a tool that reduces an AsciiDoc document with includes to a single document by expanding the includes reachable from the specified parent document. If the document does not contain any includes, the tool returns the original source.


To install and run Asciidoctor Reducer, you need Ruby 2.5 or better installed and the Asciidoctor gem. The instructions for installing the gems is covered in the next section.

To check whether you have Ruby installed, and which version, run the following command:

$ ruby -v

If Ruby is not installed, you can install it using RVM (or, if you prefer, the package manager for your system). We generally recommend using RVM because it allows you to install gems without requiring elevated privileges or messing with system libraries.


Asciidoctor Reducer is published to as the gem named asciidoctor-reducer.

You can install the latest version of the gem using the following command:

$ gem install asciidoctor-reducer --pre

Installing this gem makes the asciidoctor-reducer command available on your $PATH. You can also require the gem to use it as an Asciidoctor extension.


As command

You can run this tool using the provided command (i.e., CLI), named asciidoctor-reducer. To learn how to use the command, and to verify it’s available, run the command with the -h option:

$ asciidoctor-reducer -h

On the first line of the help text, you’ll see a synopsis of the command:

asciidoctor-reducer [OPTION]... FILE

The argument FILE is the AsciiDoc file you want to reduce. To use the command, pass the AsciiDoc file as the sole argument:

$ asciidoctor-reducer input.adoc

By default, the command will output the reduced AsciiDoc document to the terminal (via stdout). To write the output to a file, specify an output file using the -o option.

$ asciidoctor-reducer -o output.adoc input.adoc

The command can also read the input document from stdin instead of a file. To use the command in this way, pass - as the first argument:

$ cat input.adoc | asciidoctor-reducer -

To write the output to a file, also specify the -o option:

$ cat input.adoc | asciidoctor-reducer -o output.adoc -

Note that top-level include files in the input AsciiDoc document are resolved relative to current working directory.

As extension

You can use this tool as an Asciidoctor extension when using the Asciidoctor API. To do so, require it before calling the Asciidoctor.load method.

require 'asciidoctor/reducer'

Next, load a parent document that contains includes.

doc = Asciidoctor.load_file 'sample.adoc', safe: :safe

Finally, you can retrieve the reduced source from the returned document.

puts doc.source

You can write this source to a file to save the reduced document.

Copyright © 2021-present Dan Allen. Use of this software is granted under the terms of the MIT License.

See the LICENSE for the full license text.


AsciiDoc® and AsciiDoc Language™ are trademarks of the Eclipse Foundation, Inc.