Skip to content
GitLab
    • GitLab: the DevOps platform
    • Explore GitLab
    • Install GitLab
    • How GitLab compares
    • Get started
    • GitLab docs
    • GitLab Learn
  • Pricing
  • Talk to an expert
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
    • Switch to GitLab Next
    • Menu
    Projects Groups Snippets
  • Get a free trial
  • Sign up
  • Login
  • Sign in / Register
  • Antora Antora
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
    • Locked Files
  • Issues 155
    • Issues 155
    • List
    • Boards
    • Service Desk
    • Milestones
    • Iterations
    • Requirements
  • Merge requests 26
    • Merge requests 26
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
    • Test Cases
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Code review
    • Insights
    • Issue
    • Repository
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • Antora
  • AntoraAntora
  • Issues
  • #423
Closed
Open
Created May 02, 2019 by Andreas Offenhäuser@anoff

Compose navigation files across components

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
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information
Assignee
Assign to
Time tracking