Support Antora and images relative to the catalog root

[vincent-smit]

Currently, it's not possible to preview images when you use this plugin to create AsciiDoc documents for use with Antora. This is because, and I quote Dan Allen (creator of AsciiDoctor):

the tools need to evolve. that's my position. this is critical, because that's how the image macro was always designed to work. to be relative to the catalog root, not a relative path fishing around the filesystem for the image.

Solution

Support AsciiDoctors image macro so images can be found within a ./images folder that is relative to the root directory of the documents. If this plugin detects an .adoc file (or other extension) is contained within a ./pages folder, it should look in the root directory for a ./images folder and interpreter image references to that folder.

For more information; check the AsciiDoctor manual regarding the imagedir attribute.

[mojavelinux]

Understand that when I say, the "tools need to evolve" it isn't because they did anything wrong or aren't keeping up. It's merely that we are evolving the reach of the language and the tools will need to evolve in response. So hopefully it's implied that we'll work together on this.

We shouldn't frame this as "supports Antora's xref macro" or "supports Antora's image macro". It's 100% valid AsciiDoc. What we are aiming to support is an implicit project structure. In other words, certain settings that can be auto-configured based on the plugin recognizing the Antora structure. That's the key value of having a standard project structure for documentation, as we first pitched here: https://opendevise.com/blog/standard-project-structure-for-docs/

[mojavelinux]

I should point out that the project structure can be used even if you're not using Antora (though likely most will be).

[prudhomm]

is there a workaround ? I added #280 which may be a duplicate of this issue. I am enforcing a certain layout to my documents in antora (thanks to antora) and the relative path to reach the images in github works fine most of the time however I haven't managed to do it in vscode, yet