johannesjh / asciidoctor-indir_ext

Asciidoctor extension that adds a variable "indir" that points at the directory of included asciidoc files.

Asciidoctor::IndirExt

Status and Maintenance

This is unmaintained software. Don't use it. Feel free to fork. I am not actively working on this anymore.

This asciidoctor extension has served its purpose of demonstrating the need and providing a temporary solution, but I currently don't use it anymore, and I have not updated it for a while. As of December 2023, it is not compatible with current versions of Asciidoctor anymore, compare pull request 4 in this repository.

In my opinion, the ability to include subdocuments (and to use relative paths for including images etc in these subdocuments) should be implemented at the level of Asciidoctor (the compiler) and Asciidoc (the language). Corresponding tickets exist, see e.g., issue 650. Unfortunately, the feature has not landed for years. I have grewn increasingly frustrated about it. A compiler extension (such as this repo here) can only be seen as a temporary workaround. As a proper solution, an official language or compiler feature is needed so that everybody can rely on it in the long term. From a user perspective, this is needed to be able to use the feature without having to install extensions. From a developer perspective, this is needed in order to create a thriving ecosystem where multiple compilers (not just asciidoctor) and multiple extensions (besides asciidoctor-indir_ext) can benefit from the feature using offically documented, standardized syntax.

About

An Asciidoctor extension that adds a variable indir, which always points to the directory of the currently included asciidoc file.

This extension solves the problem that standard asciidoctor allows no relative paths in subdocuments, see asciidoctor issue #650.

Installation

If using bundler, add this line to your application's Gemfile:

gem 'asciidoctor-indir_ext'

And then execute:

$ bundle install

If you do not wish to use bundler, install as:

$ gem install asciidoctor-indir_ext

Usage

1. In the beginning of a subdocument, add this line: ifndef::indir[:indir: .]

2. Include images like this: image::{indir}/images/example.svg[]

3. When compiling a master document (that includes other subdocuments), require this extension.

For example:

bundle exec asciidoctor -r asciidoctor-indir_ext master.adoc

...or without bundler:

asciidoctor -r asciidoctor-indir_ext master.adoc

As a result, the extension provides an indir variable, which always points at the directory of the included asciidoc file. This allows image paths like {indir}/images/example.svg to be resolved relative to the included subdocument.

Development

It is possible to start a docker container using docker-compose run --rm dev bash. This allows to run the following commands inside the docker container and thus avoids messing with the local system setup.

• Run bundle install to install dependencies
• To list all available rake tasks, run bundle exec rake -T
• To build a gem package on your local machine, run bundle exec rake build
• To install this gem onto your local machine, run bundle exec rake install
• To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/johannesjh/asciidoctor-indir_ext.

Credits

This extension is based on another asciidoctor extension called jirutka/asciidoctor-include-ext, which provides a cleaner implementation of asciidoctor's include processing, and thus makes it easier to overwrite according behavior through an extension.

Special thanks goes to @mojavelinux for pointing out this solution in asciidoctor issue #650 and for providing valuable feedback.

License

The gem is available as open source under the terms of the MIT License.

asciidoctor-indir_ext's Issues

Failed to load AsciiDoc document - wrong number of arguments (given 1, expected 0)

I get an error in the initiliaze call of the extension above line:

${HOME}/.gem/ruby/3.0.0/gems/asciidoctor-include-ext-0.3.1/lib/asciidoctor/include_ext/include_processor.rb:25:in `initialize': asciidoctor: FAILED: ${HOME}/tmp/test-repo/asciidoc-test2/main.adoc: Failed to load AsciiDoc document - wrong number of arguments (given 1, expected 0) (ArgumentError)
        from ${HOME}/.gem/ruby/3.0.0/gems/asciidoctor-indir_ext-0.1.3/lib/asciidoctor/indir_ext/extension.rb:11:in `initialize'
        from /usr/lib/ruby/gems/3.0.0/gems/asciidoctor-2.0.17/lib/asciidoctor/extensions.rb:1359:in `new'
        from /usr/lib/ruby/gems/3.0.0/gems/asciidoctor-2.0.17/lib/asciidoctor/extensions.rb:1359:in `add_document_processor'
        from /usr/lib/ruby/gems/3.0.0/gems/asciidoctor-2.0.17/lib/asciidoctor/extensions.rb:946:in `include_processor'
...

This seems to be similar to the issue from asciidoctor/asciidoctorj#451 (comment) and if I apply the solution from there it works. so the simple fix would be to change super to super() here:

asciidoctor-indir_ext/lib/asciidoctor/indir_ext/extension.rb

Line 11 in a800e77

super

Non-asciidoc imports affected?

https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/_includes/include-directive.adoc describes how to include code in your files, e.g. using

[source,java]
----
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
----

But if I do that in a project that uses indir_ext, I get

:indir: /some/path/to/the/code

in the listing. That’s of course horrible!

According to https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/_includes/include-directive.adoc#asciidoc-vs-non-asciidoc-files asciidoc only treats files ending in .asciidoc, .adoc, .ad, .asc, or .txt as Asciidoc; presumably this extension should do the same.