Navigation Bar - Use nav.adoc always in left nav bar

[rgleason]

Maybe it is personal preference, but I like the Righthand Nav bar the way you've got it setup for the Internal Plugins which uses the expandible format that is setup in nav.adoc.

I realize that for some reason when we select an external plugin, the right hand navigation bar changes.
Is there a reason for this? Isn't there some way to keep the nav.adoc version here? (prefered IMHO). Is there a reason to show this less versatile nav?

Note. I will be pushing the Simplified Navigation shortly, so wait a bit on this problem. Thanks.

[rgleason]

Maybe we can get the nav.adoc to be used in the Left hand navigation bar, for all plugins, by editing this antora?

│ ├─── ROOT <---Where all navigation for Plugins is done
│ │ ├───── nav.adoc <--Uses partials files nav-main.adoc, nav-beta.adoc, nav-all.adoc. Left hand Nav bar
│ │ ├───── antora.yml

and adding some directions that work?
I am not not that familiar with this....

but what is used in the left hand navigation bar when an external plugin is showing in the center?
We want to change whatever that is, so that nav.adoc is used.

[rgleason]

Here are two live examples:

Internal Plugin: Dashboard using nav.adoc for the Navigation Bar
https://opencpn-manuals.github.io/plugins/opencpn-plugins/0.1/dashboard/dashboard.html

External Plugin: oeSENC using something else for the Navigation Bar
https://opencpn-manuals.github.io/plugins/oesenc/0.1/index.html

We want all external plugins to use nav.adoc in the Navigation Bar for consistency.

[rgleason]

I think I know what is happening. The external plugins are all under "sources" directory.

..plugins\sources\<plugin_name_pi>i\manual\modules\ROOT\pages\index.adoc

There is an antora file just above modules that generally reads

name: autopilot_route
title: Autopilot Route
version: '0.1'

and the site.yml next to it does not have any nav designation.

site:
  title: Autopilot Route
  url:  https://nowhere.net
  start_page: autopilot_route:ROOT:index.adoc

Perhaps we could figure out the correct path for the

nav: - ????

Field to point to

`..\manual\plugins\modules\ROOT\nav.adoc

so the nav bar stays the same. We would then have to get all distributed plugins using this, but over time it would get fixed.
`

[rgleason]

Mike, I am running some tests to see if we can get the Left Navbar used all the time.
Started by adding a nav: to

sources\watchdog_pi\manual\antora.yml

so that the nav.doc in

..\manuals\plugins\modules\ROOT\nav.adoc is used.

It does not seem to be changing the Left Nav bar however, Any idea.s? Path wrong?

Plugin Sources

####OM-plugins\sources\watchdog_pi\manual\antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav:
  - ::manual/plugins/modules/ROOT/nav.adoc <---WHAT I AM TRYING  IS THIS PATH WRONG?

####OM-plugins\sources\watchdog_pi\manual\site.yml

site:
  title: Watchdog
  url:  https://nowhere.net
  start_page: watchdog:ROOT:index.adoc
content:
  sources:
    - url: ../
      start_path: manual
      branches: HEAD
      edit_url: https://github.com/opencpn-manuals/watchdog_pi/edit/master/{path}
ui:   
  bundle:
    url: https://gitlab.com/leamas/antora-ui-default/-/raw/master/latest/ui-bundle.zip
    snapshot: true
output:
  dir: ./docs
  clean: true        

Navigation and other documentation section

####OM-plugins\site.yml

Big main site.yml

site:
  title: OpenCPN
  url: https://opencpn-manuals.github.io/plugins
  start_page:  opencpn-plugins::index.adoc

content:
  sources:
    # Keep listed sorted to avoid duplicates and for better diffs.

   - url: sources/watchdog_pi/
      branches: master
      start_path: manual
      edit_url: https://github.com/rgleason/watchdog_pi/edit/master/{path}

####OM-plugins\antora.yml

name: opencpn-plugins
title: OpenCPN Manuals
version: '0.1'
start-page: manual/plugins
nav:
  - modules/ROOT/nav.adoc  <---Existing which works for most of the Left nav bar

####OM-plugins\manual\plugins\antora.yml

name: opencpn-plugins
title: OpenCPN Plugins
version: '0.1'
nav: 
- modules/ROOT/nav.adoc    <---Existing which works for most of the Left nav bar

####OM-plugins\manual\plugins\modules\ROOT\nav.adoc
Full path to nav.adoc

[rgleason]

Have also tried watchdog's antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav:
  - manual/plugins/modules/ROOT/nav.adoc

Still does not use OM-plugins/manual/plugins/modules/ROOT/nav.adoc

[rgleason]

Have also tried watchdog's antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav:
- manual\plugins\modules\ROOT\nav.adoc

Still does not use OM-plugins\manual\plugins\modules\ROOT\nav.adoc

[rgleason]

Have also tried watchdog's antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav:
- ::manual\plugins\modules\ROOT\nav.adoc <---With two colons

Still does not use OM-plugins\manual\plugins\modules\ROOT\nav.adoc

What am I missing here?

[leamas]

https://docs.antora.org/antora/2.3/navigation/xrefs-and-link-text/

[rgleason]

Thankyou Alec, that was helpful and I have read a number of other pages, but I haven't found the answer to this particular case. There are some very interesting diagrams here when you zoom in on the diagram it helps.

I clearly do not understand antora that well.
Last night in desperation I tried

1. copying modules/nav.adoc and modules/partials into sources
2. add an antora.yml that would use that new nav.adoc

for the left hand navigation of all the plugins documentation. It has not worked, antora site.yml completes but the left nav still refers to the plugins antora.yml.

I tried a number of variations. I guess I still do not know what the hierarchy is that triggers the use or non use of nav stuff. If you guys have any insights into this that you could share it would be helpful.

I am now considering trying to move all of "sources" to be under "modules" alongside of the other documentation that does work with the left side navbar. What are the problems with this? (Yes I know scripts would have to change.)

├───manual
│   │   .gitignore
│   │   .nojekyll
│   │   beta_plugins.txt
│   │   dokuwiki plugins.txt
│   │   README.md
│   │   ui-bundle.zip
│   │
│   └───plugins
│       │   antora.yml
│       │
│       └───modules
|             |───sources      **<--- TO  HERE**
|             |         ├─ .gitkeep
|             |         ├─DR_pi
│           ├───advanced
│           ├───authoring
│           ├───chart_downloader_tab
│           ├───dashboard
│           ├───grib_weather
│           ├───misc
│           │
│           ├───ROOT
│           │   │   nav.adoc
│           │   │
│           │   ├───pages
│           │   │       index.adoc
│           │   │       index-main.adoc
│           │   │       index-beta.adoc
│           │   │
│           │   └───partials
│           │           nav-all.adoc
│           │           nav-beta.adoc
│           │           nav-main.adoc
|           |
│           ├───sat2chart
│           └───wmm
└───sources      **<--- FROM HERE**
    │   .gitkeep
    │
    ├───DR_pi

[leamas]

Your problem is not about navigation, your problem is that you need to make cross-module xref link i . e., a link to a pacge in another module.

https://docs.antora.org/antora/2.3/page/page-id/

[rgleason]

In sources\watchdog\manual\antora.yml

name: watchdog
title: Watchdog
version: '2.4.29'
nav:
 - xref:ROOT:partials:nav-all.adoc

Have tried

nav:
 - xref:ROOT:nav.adoc

Have also tried

nav:
  - xref:manual:plugins:ROOT:nav.adoc

nav:
  - xref:plugins:ROOT:nav.adoc

nav:
  - xref:plugins:ROOT:nav.adoc

nav:
  - xref:ROOT:nav.adoc

nav:
  - xref:nav.adoc

The file I am trying to cross reference to or xref is
OM-plugins\manual\plugins\modules\ROOT\nav.adoc
so that all the nav files will be used in the left side navigation for all plugins.

Any thoughts about what I am doing wrong?

[rgleason]

Also tried

nav:
 - xref::manual:plugins:ROOT:nav.adoc
 
nav:
 - xref::plugins:ROOT:nav.adoc

nav:
 - xref::ROOT:nav.adoc

nav:
 - xref::nav.adoc