Make sidebar version-aware with edition-specific navigation #108
Conversation
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
The sidebar now adapts based on the selected edition (version) of the AEP documentation. When users switch between editions using the version selector, the sidebar displays AEP links specific to that edition. Changes: - Added assembleSidebarsByEdition() function to generate separate sidebars for each edition with edition-aware link paths - Modified generate.ts to export sidebars-by-edition.json containing sidebar configurations for all editions - Updated astro.config.mjs to configure starlight-sidebar-topics plugin with edition-specific sidebars that switch based on the current path - Each edition's sidebar includes properly prefixed links (e.g., /aep-2026/123 for the 2026 edition, /123 for the default edition) The sidebar automatically switches when navigating between editions, providing a consistent navigation experience within each edition's content.
…JSON files Instead of generating separate sidebar JSON files during the build process, the sidebars are now built dynamically in astro.config.mjs from the site structure. This reduces the number of generated files and centralizes the sidebar logic. Changes: - Removed sidebar JSON generation from generate.ts (only generates site-structure.json now) - Updated astro.config.mjs to import assembleSidebarsByEdition and build sidebars at config time - Sidebars are constructed on-demand from the site structure for each edition This approach keeps the generate script focused on content processing while moving the presentation logic (sidebar assembly) to the configuration layer.
Instead of using the starlightSidebarTopics plugin (which doesn't support completely different sidebars per edition), we now use Astro middleware and a custom Sidebar component override to dynamically render edition-specific sidebars based on the current URL path. Changes: - Added src/middleware.ts to detect the edition from the URL path and store it in Astro.locals - Added src/components/overrides/Sidebar.astro to override Starlight's Sidebar component and inject edition-specific sidebar items - Updated astro.config.mjs to: - Remove starlightSidebarTopics plugin and its configuration - Add Sidebar component override - Simplify config by removing edition-aware sidebar building at config time How it works: 1. Middleware detects the edition folder from the URL path (/aep-2026/* vs /*) 2. Stores the edition identifier in Astro.locals.edition 3. Sidebar component reads locals.edition and loads the site structure 4. Sidebar component builds and renders the appropriate edition-specific sidebar 5. Each edition gets its own sidebar with properly prefixed links This approach properly integrates with Starlight's architecture and allows completely different sidebars per edition.
Reverted from the component override approach and now properly use the starlight-sidebar-topics plugin to provide edition-aware sidebars without custom component overrides. Changes: - Removed Sidebar.astro component override - Updated astro.config.mjs to: - Load site structure and build sidebars for all editions - Convert Sidebar[] format to Starlight format (strip icon/id fields) - Configure starlightSidebarTopics with separate sidebar items for each edition - Each edition topic has its own matcher function based on path - Kept middleware.ts for future use (edition detection) How it works: 1. Site structure is loaded and sidebars are built for each edition at config time 2. Sidebar format is converted to Starlight's expected format (removing icon/id) 3. starlightSidebarTopics plugin receives an array of topic configurations 4. Each topic has its own sidebar items and a matcher function 5. Plugin switches sidebars based on the current path (/ vs /aep-2026/) This approach uses the plugin as intended while providing completely different sidebar items for each edition.
The previous approach of passing topics array to the plugin was incorrect. Now using both the Sidebar component override (for edition-specific sidebars) and the starlight-sidebar-topics plugin (with its correct API) together. Changes: - Restored Sidebar.astro component override to inject edition-specific sidebars - Updated astro.config.mjs to use starlightSidebarTopics with correct API: - First param: empty sidebar array (override provides actual sidebar) - Second param: config with topics and exclude (for plugin's internal use) - Middleware detects edition and stores in Astro.locals - Sidebar override reads edition from locals and injects appropriate sidebar This combines both approaches: - Plugin handles topic organization and path filtering - Override provides edition-specific sidebar content - Middleware enables runtime edition detection
…ns pattern Refactored the middleware to follow the pattern used by other Starlight plugins like starlight-versions, where middleware is integrated via an Astro integration rather than a standalone middleware file. Changes: - Created src/integrations/edition-middleware.ts with edition detection middleware - Created src/integrations/starlight-edition-aware-sidebar.ts integration that: - Implements AstroIntegration interface - Adds the edition middleware using addMiddleware hook - Uses fileURLToPath to reference the middleware file - Updated astro.config.mjs to import and add the integration - Removed standalone src/middleware.ts (moved to integrations/) This pattern: - Follows Starlight plugin conventions (like starlight-versions) - Makes the middleware part of the edition-aware sidebar feature - Properly integrates with Astro's middleware system - Is more modular and maintainable
The starlight-sidebar-topics plugin requires that no sidebar configuration is defined in the Starlight config. Removed the 'sidebar: []' line which was causing the build to fail. Error: 'It looks like you have a sidebar configured in your Starlight configuration. To use starlight-sidebar-topics, create a new topic with your sidebar items.'
The starlight-sidebar-topics plugin requires all pages to either be in a topic or explicitly excluded. Added /aep_list to the exclude list since it's a special listing page that doesn't need topic-based routing. The edition-specific aep_list pages (e.g., /aep-2026/aep_list) are already excluded via the wildcard patterns for non-default editions. Error: 'Failed to find the topic for the aep_list page.'
…ting Updated implementation to properly use the starlight-sidebar-topics plugin API: 1. Pass default edition sidebar to plugin (not empty array) - Load and build sidebars for all editions at config time - Strip icon/id fields from default sidebar for Starlight compatibility - Plugin now has actual sidebar items to assign pages to topics 2. Updated Sidebar override to use Astro.locals.starlightSidebarTopics - Access topic route data to determine current topic - Map topics to edition names - Fallback to middleware edition detection - Render appropriate edition-specific sidebar 3. Plugin configuration: - Default sidebar: general edition (for default paths) - Topics.aeps: non-default editions (e.g., /aep-2026/**) - Exclude: special pages like /aep_list and /blog This combines the plugin's topic routing with our edition-aware sidebar override, following the custom topic list pattern from the docs.
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.
The sidebar now adapts based on the selected edition (version) of the AEP
documentation. When users switch between editions using the version selector,
the sidebar displays AEP links specific to that edition.
Changes:
for each edition with edition-aware link paths
configurations for all editions
edition-specific sidebars that switch based on the current path
for the 2026 edition, /123 for the default edition)
The sidebar automatically switches when navigating between editions, providing
a consistent navigation experience within each edition's content.