Asciidoctor Include Extension
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.
Code for decision if the include is allowed, parsing attributes for partial selection, reading the file to be included, filtering its content according to
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
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):
gem install asciidoctor-include-ext
or to install the latest development version:
gem install asciidoctor-include-ext --pre
If you invoke Asciidoctor from command-line, use option
-r to load the extension:
asciidoctor -r asciidoctor-include-ext README.adoc
If you don’t want the extension to be automatically registered in Asciidoctor, don’t require
Bundler automatically requires all the specified gems.
To prevent it, use