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.

Why?

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.

Installation

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

Warning

Versions prior 0.4.0 are vulnerable for Command Injection (see c7ea001 for more information). If you use an older version, update to 0.4.0 immediately!

Usage

Just require 'asciidoctor-include-ext'. 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 asciidoctor-include-ext, but asciidoctor/include_ext/include_processor.

Important

Bundler automatically requires all the specified gems. To prevent it, use gem 'asciidoctor-include-ext', require: false.

License

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

License

digitalmoksha/asciidoctor-include-ext

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages