Low commit activity in last 3 years
This Asciidoctor extension exposes a variable `indir`, which holds the path to the directory where the current asciidoc file is located. The value of this variable changes to always reflect the location of the current, included subdocument. (Note, this is in contrast to the `docfile` variable, which remains the same throughout an entire document).
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

~> 1.5.0.alpha.16
~> 2.0
~> 12.0
~> 3.0

Runtime

>= 1.5.6, < 3.0.0
 Project Readme

Asciidoctor::IndirExt

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.