How to change images path when converting AsciiDoc file containing diagrams to html using Asciidoctor Ruby API? - ruby

Question

Lets suppose there is a web based documentation available at docs.project
Directory structure
/ - project root
/docs - documentation files in asciidoc format
index.adoc - documentation entry point
/public - public directory
generate.rb
Desirable workflow
I change documentation source in /docs directory.
I commit and push changes.
When pushing, the server runs ruby <project_root>/generate.rb command that rewrites the html presentation of the documentation.
index.adoc
= Documetation
Some text
[plantuml]
....
Client --> Server: Request
Server --> Client: Response
....
generate.rb
require 'asciidoctor'
require 'asciidoctor-diagram'
ROOT = File.dirname(__FILE__)
entry = ROOT + '/docs/index.adoc'
outdir = ROOT + '/public'
Asciidoctor.convert_file entry, to_dir: outdir, mkdirs: true
Problem
Current generate.rb script puts index.html file in public while images go to docs thus they are not available when you open docs.project in browser.
How to specify the images path?

Answer 1

You can use imagesdir
You could move all your images that are being used in your index.adoc into the public folder(since this is your output folder) and can set imagesdir document attribute like:
:imagesdir: ../public/
inside your index.adoc file. You could learn more about imagesdir here

Answer 2

Your problem should be that when using the Ruby API, the default safe mode is set to :secure, which should prevent access to files which reside outside of the parent directory of the source file. I am assuming to_dir is allowed to write the file, while plantuml goes through a different generation process (probably initially generates the image and then includes it, preventing access to the directory). In any case, you have two options.
Use unsafe mode with:
Asciidoctor.convert_file entry, to_dir: outdir, mkdirs: true, safe: :unsafe
It is probably not the best solution, use only if you are running it with controlled content (and no one can put something like include::/etc/passwd[] in the adoc source).
Change the base_dir with:
Asciidoctor.convert_file entry, base_dir: '.', to_dir: outdir, mkdirs: true
Which should work, assuming your directory structure looks like:
.
├── docs
│   └── index.adoc
├── generate.rb
└── public