This project is a reimplementation of the Asciidoctor’s built-in (pre)processor for the include::[] directive in extensible and more clean way. It provides the same features, but you can easily adjust it or extend for your needs. For example, you can change how it loads included files or add another ways how to select portions of the document to include.

You may ask why I reimplemented something that is already in the Asciidoctor core.

Well… Code for decision if the include is allowed, parsing attributes for partial selection, reading the file to be included, filtering its content according to lines or tags attribute, handling errors… all of this is implemented directly in a single 210 lines long method Asciidoctor::Reader#preprocess_include_directive with really horrible perl-like spaghetti code. 🍝 💩

How can you adjust it or reuse outside of the Asciidoctor codebase? For example, what if you can’t read documents directly from file system? Then you’re out of luck. There’s no way how to do that without reimplementing this whole mess on your own (monkey-patching Kernel.open and File.file? is not a sensible option…).

I wrote this extension to allow implementing a complete support of include::[] directive in GitLab. And also to open doors for adding some custom selectors, e.g. selecting lines using regular expression in addition to ranges of line numbers and tags.

To install (or update to the latest version):

or to install the latest development version:

Just require 'asciidoctor-include-ext'. If you invoke Asciidoctor from command-line, use option -r to load the extension:

If you don’t want the extension to be automatically registered in Asciidoctor, don’t require asciidoctor-include-ext, but asciidoctor/include_ext/include_processor.

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.