ENHANCEMENT: Page hierarchy based on nav.adoc

[andreas-hempel]

Hello @PacoVK,

in Antora I define the navigation for the generated HTML in the nav.adoc file.

* xref:index.adoc[]
** xref:segments.adoc[]
*** xref:segments/message-header.adoc[]
** xref:tables.adoc[]

When I transfer the documentation to confluence, the page hierarchy from the nav.adoc file is lost.

Is there a possibility in a future version that the page hierarchy in confluence will correspond to the one defined in the nav.adoc file?

In the attachment you will find an example project to illustrate.

confluence-issue.zip

WORAROUND:
I currently have to move the pages manually. If I execute the transfer from Antora again, the page hierarchy is retained, new pages are then inserted at the top level and have to be edited manually. It would be great if this could be done automatically, especially for larger documentation.

Kind Regards,
Andreas

[PacoVK]

@andreas-hempel thanks for this input. I also thought into that direction, yet failed to find a suitable approach for that. There is a simple technical reason, the output plugin interface receives the already translated .html files and i do not have access to the asciidoc source (at least no convinient). However, i keep this in mind and will try to make this possible, since this would be a really nice feature.

[andreas-hempel]

Hello @PacoVK,

the generated navigation is contained in the <nav> tag in every HTML file. There, the navigation is mapped in corresponding <ul> and <li> tags. The target file can then be found in the corresponding href attributes. Would this be an idea for building the navigation in confluence?

<div class="nav-container" data-component="confluence-issue" data-version="main">
   <aside class="nav">
      <div class="panels">
         <div class="nav-panel-menu is-active" data-panel="menu">
            <nav class="nav-menu">
               <button class="nav-menu-toggle" aria-label="Toggle expand/collapse all" style=""></button>
               <h3 class="title"><a href="index.html">Confluence Issue</a></h3>
               <ul class="nav-list">
                  <li class="nav-item is-active is-current-path" data-depth="0">
                     <ul class="nav-list">
                        <li class="nav-item is-current-page is-active" data-depth="1">
                           <button class="nav-item-toggle"></button>
                           <a class="nav-link" href="index.html">Einleitung</a>
                           <ul class="nav-list">
                              <li class="nav-item is-active" data-depth="2">
                                 <button class="nav-item-toggle"></button>
                                 <a class="nav-link" href="segments.html">HL7-Segmente</a>
                                 <ul class="nav-list">
                                    <li class="nav-item" data-depth="3">
                                       <a class="nav-link" href="segments/message-header.html">MSH – Nachrichtenkopfinformationen</a>
                                    </li>
                                 </ul>
                              </li>
                              <li class="nav-item" data-depth="2">
                                 <a class="nav-link" href="tables.html">HL7-Tabellen</a>
                              </li>
                           </ul>
                        </li>
                     </ul>
                  </li>
               </ul>
            </nav>
         </div>
         <div class="nav-panel-explore" data-panel="explore">
            <div class="context">
               <span class="title">Confluence Issue</span>
               <span class="version">main</span>
            </div>
            <ul class="components">
               <li class="component is-current">
                  <div class="title"><a href="index.html">Confluence Issue</a></div>
                  <ul class="versions">
                     <li class="version is-current is-latest">
                        <a href="index.html">main</a>
                     </li>
                  </ul>
               </li>
            </ul>
         </div>
      </div>
   </aside>
</div>

Unfortunately, this approach is only indirect, but could be used as an experimental feature.

Kind Regards,
Andreas

[DrackThor]

I guess the idea is good 🤔 would also very much like this feature!
although I can't help with the coding, I'd be happy to help with testing, docs and feedback 😄

[PacoVK]

I really put many thoughts into this, because i do see value in here. However i still could not manage to get a satisfying solution to that.
Here are my current blockers, in case someone has an idea how to overcome this:

The navigation is totally free and up to the user how to structure and title. This can lead to lots of duplicates and naming conflicts. While Antora could handle that easily, Confluence cannot due to the constraint how pages are designed and Captain could eg. not guess what is a cross-ref and which is the main link in. a nav. This means every page that get linked in a nav more than once across the whole Antora docs, would be duplicated and would also need a prefix, which in the end also means changes to that page are very hard to propagate and track.

any idea/ recommendation would be appreciated :)

[slonopotamus]

not guess what is a cross-ref and which is the main link in. a nav

Hmm... In Antora, page has breadcrumbs at its top. So it knows what is its "primary" path, no?

UPD: Yep, I've just tried. The first page reference in nav.adoc wins and becomes primary.