GitLab

Problem

Is it possible to include:: within a nav.adoc file? I would actually like to include navigation files from another component but I even fail to include a local file in the same directory. Whatever combination of relative or absolute paths I try I keep getting asciidoctor: ERROR: nav.adoc: line 5: include target not found: modules/ROOT/nav.1.adoc as a message during the build.

I found #263 and #281 (closed) as related issues but they do not seem to address the issue of composing the overall navigation by including nav files at specific location in the nav tree.

Question

Is this unsupported or am I just missing the correct usage for:

1. include local nav files
2. include nav files from other components using antora component IDs to include nav entries
3. use levelOffset during include (nice to have)

Background / Reasoning

My use case is to generate SW docs for a multi repo software system. I have one docs repository that holds overall architecture and components are developed in separate repos. However I want to create one overall navigation bar that displays the overall docs together with the individual component pages. The only solution I could come up with is to reference all component docs from an overall nav.adoc. But I do not like the fact that I have to create a commit in two different repos if I add new files to the component docs. Instead I would prefer to manage the list of component docs navigation entries in the component repo and just reference it as a whole in the overall docs nav file.

Example

* xref:ROOT:intro.adoc[Introduction]
* Architecture
** xref:ROOT:strategy.adoc[Decomposition Strategy]
** include:component1:ROOT:../nav.adoc[] // include entire nav tree from a module/component

should result in

* xref:ROOT:intro.adoc[Introduction]
* Architecture
** xref:ROOT:strategy.adoc[Decomposition Strategy]
** xref:component1:ROOT:welcome.adoc[Component1] < entry in remote adoc
*** xref:component1:ROOT:setup.adoc[Setup Guide] < entry in remote adoc
*** xref:component1:ROOT:roadmap.adoc[Feature Roadmap] < entry in remote adoc