asciidoctor-include-ext

= Asciidoctor Include Extension :source-language: shell // custom :gem-name: asciidoctor-include-ext :gh-name: jirutka/{gem-name} :gh-branch: master :codacy-id: 45320444129044688ef6553821b083f1

ifdef::env-github[] image:https://github.com/{gh-name}/workflows/CI/badge.svg[CI Status, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22] image:https://api.codacy.com/project/badge/Coverage/{codacy-id}["Test Coverage", link="https://www.codacy.com/app/{gh-name}"] image:https://api.codacy.com/project/badge/Grade/{codacy-id}["Codacy Code quality", link="https://www.codacy.com/app/{gh-name}"] image:https://img.shields.io/gem/v/{gem-name}.svg?style=flat[Gem Version, link="https://rubygems.org/gems/{gem-name}"] image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://www.rubydoc.info/github/{gh-name}/{gh-branch}"] endif::env-github[]

This project is a reimplementation of the http://asciidoctor.org[Asciidoctor]’s built-in (pre)processor for the http://asciidoctor.org/docs/user-manual/#include-directive[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 https://github.com/asciidoctor/asciidoctor/blob/911d0bd509f369e9da15d2bb71f81aecb7c45fec/lib/asciidoctor/reader.rb#L824-L1034[Asciidoctor::Reader#preprocess_include_directive] with really horrible perl-like spaghetti code. :spaghetti: :hankey:

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):

[source, subs="+attributes"] gem install {gem-name}

or to install the latest development version:

[source, subs="+attributes"] gem install {gem-name} --pre

WARNING: Versions prior 0.4.0 are vulnerable for Command Injection (see https://github.com/{gh-name}/commit/c7ea001a597c7033575342c51483dab7b87ae155[c7ea001] for more information). If you use an older version, update to 0.4.0 immediately!

== Usage

Just require '{gem-name}'. If you invoke Asciidoctor from command-line, use option -r to load the extension:

[source, subs="+attributes"] asciidoctor -r {gem-name} README.adoc

If you don’t want the extension to be automatically registered in Asciidoctor, don’t require {gem-name}, but asciidoctor/include_ext/include_processor.

IMPORTANT: Bundler automatically requires all the specified gems. To prevent it, use gem '{gem-name}', require: false.

== License

This project is licensed under http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.