We merged #196 because it should make a big improvement in the size of the generated artifacts and site, but I had a few feature requests for @gpx1000 which are pulled out here, so we don't lose them:
- Spell "extensions" correctly in REUSE.toml line 42:
path = ["docs-site/extnesions/antora-static-nav/lib/index.js", "docs-site/extnesions/antora-static-nav/test/integration.test.js", "docs-site/extnesions/antora-static-nav/test/unit.test.js", "docs-site/extnesions/antora-static-nav/package.json"]
-
Change name of antora-static-nav job in antora-static-nav.yml (filename and 'name' field in the .yml) - this is just running tests, so would be more clear with a name capturing that fact.
-
The static-nav script has a heuristic (ca. line 163) to determine whether to do the nav block refactoring, and which page to source it from. I suggest we instead have a per-component opt-in for antora.yml specifying that the refactoring should be done. If so, I think it would be safe to always source it from the component's index.html. If there isn't an index.html it could probably just as well be sourced from the first HTML page in the pages/ directory - I'm not aware of circumstances in which the nav index could vary from page to page in a component.
-
Also, I suggested searching the DOM of the page from which the index is sourced - I am sure there's a JS package supporting that, or at worst an XSLT package - to find and replace the nav blocks over the current regexp-based approach, which is more fragile against upstream changes from asciidoctor.js and Antora in how they generate HTML.
-
Finally, if the extension cannot find the nav block when it has been requested for replacement, that should be treated as an error and reported to the effect of "fix the extension, or don't use it on this component". Currently I think the extension skips over a component where it fails the heuristic to identify the nav index.
None of this is critical (although the spelling fix in REUSE.toml would be great because the path in there right now does not exist - I may just push a point fix for that). But it's all in the interest of being robust and futureproofing.
We merged #196 because it should make a big improvement in the size of the generated artifacts and site, but I had a few feature requests for @gpx1000 which are pulled out here, so we don't lose them:
Change name of antora-static-nav job in antora-static-nav.yml (filename and 'name' field in the .yml) - this is just running tests, so would be more clear with a name capturing that fact.
The static-nav script has a heuristic (ca. line 163) to determine whether to do the nav block refactoring, and which page to source it from. I suggest we instead have a per-component opt-in for antora.yml specifying that the refactoring should be done. If so, I think it would be safe to always source it from the component's index.html. If there isn't an index.html it could probably just as well be sourced from the first HTML page in the pages/ directory - I'm not aware of circumstances in which the nav index could vary from page to page in a component.
Also, I suggested searching the DOM of the page from which the index is sourced - I am sure there's a JS package supporting that, or at worst an XSLT package - to find and replace the nav blocks over the current regexp-based approach, which is more fragile against upstream changes from asciidoctor.js and Antora in how they generate HTML.
Finally, if the extension cannot find the nav block when it has been requested for replacement, that should be treated as an error and reported to the effect of "fix the extension, or don't use it on this component". Currently I think the extension skips over a component where it fails the heuristic to identify the nav index.
None of this is critical (although the spelling fix in REUSE.toml would be great because the path in there right now does not exist - I may just push a point fix for that). But it's all in the interest of being robust and futureproofing.