Allow referencing content between modules
Antora currently doesn't support referencing content between modules. I would suggest that this is an important aspect which would be expected by users and will improve its flexibility.
For example if I have:
. ├── ROOT │ ├── assets │ │ ├── attachments │ │ └── images │ └── pages │ └── _partials └── setting_guide ├── assets │ ├── attachments │ └── images └── pages └── _partials
It does not appear to be possible to have a page in the
ROOT module link to content in the
setting_guide module. Neither is there a "common area" defined to allow referencing of material that multiple modules might want to use.
Why does this matter?
- Modules within a component appear to function a little like a "namespace". This is convenient and provides better abstractions and separation of concerns (good!)
- However many tree structures (due to leaky abstractions, or the law of unintended consequences) end up with inadequacies which make necessary linking to other leaves of branches closer to the trunk (and by the time that is recognised, the hierarchy is often something the user is "stuck with" or has become inflexible).
- Antora presently appears to require the user to choose between having "nicely namespaced content" and "readily referenced content" which is an undesirable situation.
@danyill Feb 20 12:14 I'm not seeing it in the docs, but I'm looking to have shared resources across modules in a component. Is this possible. One way might be if if a file wasn't found in e.g. the attachments folder for a particular module it would be searched for in the attachments folder for the ROOT module. My use case is that I have existing repositories which I have organised as a bunch of folders with name of topic/document, then inside the folder the Asciidoc with the name of the document and a media folder for images etc. I thought originally of putting these in the ROOT module but with different folders there is a potential collision of names with the content found in the media folder. Because of this I thought "I'll use separate modules for the documents". However this seems to preclude references to shared resources with Antora's present architecture (although I may well have misunderstood).
@danyill Feb 20 14:05 I guess what I want to be able to do is link to resources in the same way as I use the xref macro to go between documents, is it worthy to consider a similar syntax for paths using link: as for xref:?
Yes because you can always extend Antora to manipulate the virtual file catalog however you want. No not yet the default behavior. The problem is actually not with Antora but with Asciidoctor. Asciidoctor doesn't actually look for images. It just constructs a URL to them based on the imagesdir and target. So we don't actually know if any image resolves at all, not to mention a fallback.
@mojavelinux responded with:
@danyill I'm not seeing it in the docs, but I'm looking to have shared resources across modules in a component. Is this possible.
Yes and no. Yes because you can always extend Antora to manipulate the virtual file catalog however you want. No not yet the default behavior. The problem is actually not with Antora but with Asciidoctor. Asciidoctor doesn't actually look for images. It just constructs a URL to them based on the imagesdir and target. So we don't actually know if any image resolves at all, not to mention a fallback.
However, what we could do is add an extension that does hook into the image URL processing and actually check for the image in the catalog. At that time, we could then look into the ROOT module if the image is not found in a non-ROOT module. There's a small cost associated with that, but it seems like a good tradeoff. We already override the Asciidoctor converter, so there's an opportunity for doing something like this in the AsciiDoc loader component. I'll note down to file an issue where we can discuss.
@danyill However this seems to preclude references to shared resources with Antora's present architecture
But yes, currently by design, the images are scoped to a module. This is actually to make the preview work in the editor / IDE. But we don't have to be bound to the needs of the preview.
I am keen to see Antora's core support this, so this issue is focussed on considering options, I see five potential options:
- Allow referencing to content my module in a similar fashion to what is done for content referencing using cross references (see Antora Docs).
- Have the ROOT directory as a fallback for images which are not found within the module.
- Provide attributes which allow reference of other modules -- e.g.
modulename_partialswithin an Asciidoc file.
- Provide an explicit module for common content and potentially allow referencing it using a folder (and include this in possibly the
- Provide a more flexible structure for documentation (see #28).
My use case is as follows (and I apologise if this is quite verbose):
- I mainly use Asciidoc to distribute packaged, offline documentation which is a combination of binary files, PDFs, occasionally some XML and also some Asciidoc documents. I have developed my own opinionated folder structure which might be something like:
. ├── assets │ └── fonts ├── build_tools ├── dnp_map ├── IEC61850 ├── logic_diagram ├── manual ├── setting_guide │ └── media ├── operating_information │ └── media ├── settings │ └── TYP123 └── stylesheets
- In this case
assetscontains shared information in a git subtree (it has common re-used files which I include into Asciidoc documents)
- In the
operating_informationfolders are Asciidoc documents with
imagesdir == media.
- In the root folder I have a
- Other folders are commonly used resources, sometimes (but not always) referenced in
operating_informationand potentially referenced from other locations.
- As part of migrating to the standard Antora folder structure I wish to be able to refer to content in:
assetsfrom within module Asciidoc files.
- At present Antora requires that I choose a module for them and cannot refer to them from other modules (there is effectively a brick wall between modules).
- At present the content in the
assetsfolder cannot be made available to all modules unless I carry out some intelligent processing. My workaround at present is to copy this content into all modules (e.g. copy potentially includable files into all
_partialsdirectories, all images etc.). Perhaps once the issue relating to symbolic links is resolved I could symlink them (see #163 (closed)) but this suggests that if users wish to do this then more configurability around paths might be a more general solution to existing ad hoc content structures (see #28). But I don't think that is necessarily the case, I think Antora's opinionated structure can work quite well and just a little more sophistication is needed for what I expect to be a relatively common use case.
- The point at which this really bites for me is that I typically distribute this content in a zip file. As part of moving this content to Antora based web content I am automatically generating a new document to allow this to be downloaded from a web page.
- Ideally I want this content to be able to stored in a "common area" and referenced within a variety of modules and documents and also downloaded in a standalone fashion from a "list of files provided".
I'm interested in discussing the best option for this, workarounds for the meantime and any further thoughts anyone has.
(Antora is looking great, thanks for the great work, thanks for supporting OSS, please don't read this as a complaint!)