Repository navigation
tabbed-nav: generate nav/docsets.json for the docsets modal - #158
Merged
Merged
Conversation
Adds a flat per-docset listing (name, title, group, versions with url and optional pdf) built from the aggregated tabs.json, written by both the in-build aggregate stage and the post-publish S3 aggregator. A pdf is only listed when the file exists (output dir in-build, bucket listing in the aggregator). Adds a docsetsFile option. Bumps to 0.4.0.
tabs.json only carries a component's latest version, so docsets.json built from it listed one version for most docsets. Each component now also writes a <component>/docset.json shard listing all its versions (from Antora's content catalog), and both the in-build aggregate stage and the S3 aggregator merge those. Components that have not published a shard yet fall back to what tabs.json knows.
…file Each component's latest tabs.json entry now has docsetVersions (every version with its first page), so docsets.json is built from the aggregated tabs.json alone, in both the in-build stage and the S3 aggregator. Replaces the per-component docset.json shard from the previous commit.
…tabs-group Both work; page-version-group wins when both are set. It is copied onto pages as page-tabs-group, which the UI layouts and nav helpers still read.
…ay-group page-docset-version-group is the preferred name for page-tabs-group (still accepted); page-docset-display-group sets the group shown in the docsets modal.
Collaborator
|
Thanks for the documentation updates. The preview documentation has now been torn down - reopening this PR will republish it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a generated
nav/docsets.jsonto the@neo4j-antora/tabbed-navextension (0.3.9 to 0.4.0), alongsidenav/tabs.json. It feeds the "All Neo4j documentation" modal in docs-ui (docs-restructurebranch), which now reads it instead oftabs.json.Shape, one entry per Antora component:
[{ "name": "cypher-manual", "title": "Cypher Manual", "group": "Query", "versions": [{ "version": "25", "latest": true, "url": "/cypher-manual/25/intro/", "pdf": "/cypher-manual/25/neo4j-cypher-manual-25.pdf" }] }]urlis the first linkable internal page of that version.pdfis only set when the PDF exists: in the build output for the in-build stage, in the bucket listing for the S3 aggregator. Stored at<component>/<version>/_exports/neo4j-<component>[-<version>].pdf, public URL without_exports. The version segment is omitted for unversioned docsets.groupcomes from the docset'spage-docset-display-groupattribute (antora.yml or playbook); empty when unset.How
docsets.jsbuilds the file from the aggregatedtabs.json, shared byindex.js(in-build aggregate stage) andaggregate.js(post-publish S3 aggregator).tabs.jsononly keeps a component's latest version (plus all versions of version-grouped docsets), so each component's latest entry now also carriesdocsetVersions: every version with its first page. The nav code ignores the new field, and components not yet rebuilt fall back to whattabs.jsonalready has.docsetsFileoption (defaultnav/docsets.json,falseto skip).Attribute names
page-docset-version-groupis now the preferred name for the existingpage-tabs-group(version matching across docsets). Both work; the new one wins if both are set. It is copied onto pages aspage-tabs-group, which the UI layouts and nav helpers still read, so docs-ui needs no change for it.page-docset-display-groupis new and sets the group shown in the modal.Testing
docsets.jsmerge logic was checked on sample data and against the live devtabs.json(44 docsets) with a local script.aggregate.jsagainst S3 (needs AWS credentials). Hence draft.Follow-ups
docsets.json,docsetsFileand the two attributes in docs-playbook (reference/pages/antora/extensions/tabbed-nav.adoc,docs-restructure/pages/set-up-docset.adoc), frommain.page-docset-display-groupset before real groups appear; the modal currently uses a temporary placeholder mapping.