Support integration with starlight-sidebar-topics plugin #9

Activity

1. Fevol commented on Mar 22, 2025

   

   Fevol

   on Mar 22, 2025

   Owner

   More actions

   I understand that this would be very interesting to have from a convenience standpoint, but in my eyes, I feel like Starlight plugins in general should be as self-contained as possible.

   Adding more packages would risk making the theme more bloated and even less compatible with other packages. Personally, I already feel quite iffy about including the starlight-site-graph plugin out-of-the-box.

   I am not sure what the optimal solution would be, some ideas:

   1. Just add the starlight-sidebar-topics package to this theme as-is.
   2. Split the starlight-theme-obsidian into one that is just the centered reading and CSS styling, and another that adds all packages that one might want to fully create an Obsidian Publish-esque website.
   3. Create an extensions/ directory which provides compatible Sidebar overrides for e.g. starlight-sidebar-topics
   4. Somehow allow the Sidebar override to users to add in their own components in the sidebar in an extendible way, I guess name slots could work for that?

   Example code for 3/4

   // starlight-theme-obsidian/overrides/Sidebar.astro

   ---
   import Default from '@astrojs/starlight/components/Sidebar.astro';
   import Search from 'virtual:starlight/components/Search';
   import SiteTitle from 'virtual:starlight/components/SiteTitle';
   import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
   
   import config from 'virtual:starlight/user-config';
   
   const shouldRenderSearch = config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
   ---
   
   {/* (STARLIGHT-THEME-OBSIDIAN): Reorder site sidebar to always contain site title */}
   <div class="sidebar-top">
       <div class="title-wrapper ">
           <SiteTitle/>
       </div>
   
       {shouldRenderSearch && <Search/>}
   
       <MobileMenuFooter/>
   </div>
   
   <slot name="top"/>
   <Default><slot /></Default>
   <slot name="bottom"/>

   // YOUR-WEBSITE/overrides/Sidebar.astro

   ---
   import Default from 'starlight-theme-obsidian/overrides/Sidebar.astro'
   
   import StarlightSidebarTopicsSidebar from '../components/starlight/Sidebar.astro'
   ---
   
   <Default>
       <StarlightSidebarTopicsSidebar slot="top" />
       <slot />
   </Default>

   I could see the benefits for each of the four ideas, I'll need to think about this (and perhaps discuss this with some of the Starlight maintainers)

   ❤️React with ❤️1Reacted by Huakun
2. HuakunShen commented on Mar 22, 2025

   

   HuakunShen

   on Mar 22, 2025

   Last edited by HuakunShen

   ContributorAuthor

   More actions

   I don't know about others, but for me I just want a theme with good features out of the box, and configurable.
   Really like the site graph option.
   We can provide options in config to control whether the sidebar should be rendered.

   For a large documentation site, I believe this sidebar by topics feature is a necessary.
   For me, I put blog and tutorials into separate topics. https://docs.kunkun.sh/guides/get-started/
   Otherwise they could be hidden under a long list of notes, and don't get discovered by readers.
3. Martin-Pitt commented on Jul 9, 2025

   

   Martin-Pitt

   on Jul 9, 2025

   More actions

   I'm not a fan of the site graph's current implementation. I do see the premise and it's super nifty but it needs some work and is also not suitable to my usecase right now.

   Speaking of, I'm trying to work on a documentation site for a scripting language with hundreds of functions, so that's a lot of pages to cover. So I really need sidebar topics in my case to help scope down a larger site. I also really like this theme which has a slick minimalistic style that gets out of the way and helps to focus on the content.

   So what I have done to resolve the co-existence is create a custom override of the sidebar component that combines both the theme and the plugin together:

   ---
   import Default from '@astrojs/starlight/components/Sidebar.astro';
   import Search from '@astrojs/starlight/components/Search.astro';
   import SiteTitle from '@astrojs/starlight/components/SiteTitle.astro';
   import MobileMenuFooter from '@astrojs/starlight/components/MobileMenuFooter.astro';
   import config from 'virtual:starlight/user-config';
   import Topics from './Topics.astro';
   
   const shouldRenderSearch = config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
   const { hasSidebar } = Astro.locals.starlightRoute;
   const { isPageWithTopic } = Astro.locals.starlightSidebarTopics;
   ---
   
   {/* (STARLIGHT-THEME-OBSIDIAN): Reorder site sidebar to always contain site title */}
   <div class="sidebar-top">
       <div class="title-wrapper ">
           <SiteTitle/>
       </div>
   
       {shouldRenderSearch && <Search/>}
   
       <MobileMenuFooter/>
   </div>
   
   {hasSidebar && isPageWithTopic && <Topics />}
   <Default><slot /></Default>

   Of course the danger here is if the theme or plugin are updated I have to mind maintaining this override. I'm also thinking of replacing the search component in the future so this may find itself dealing with a third integration on top as well.
4. Fevol commented on Jul 9, 2025

   

   Fevol

   on Jul 9, 2025

   Owner

   More actions

   I'm not a fan of the site graph's current implementation. I do see the premise and it's super nifty but it needs some work and is also not suitable to my usecase right now.

   Yeah, I completely understand where you are coming from. I wish I could say that I have been able to come up with a better solution to decouple this theme from the sitegraph, but I haven't yet.

   If you don't mind, could you elaborate a bit on what parts of the site graph needs more work? Do you specifically mean the way it is implemented in the theme, the way it looks/works, how it parses your site, ...?

   ---

   So what I have done to resolve the co-existence is create a custom override of the sidebar component that combines both the theme and the plugin together:
   ...
   Of course the danger here is if the theme or plugin are updated I have to mind maintaining this override. I'm also thinking of replacing the search component in the future so this may find itself dealing with a third integration on top as well.

   That's a nice solution! In my opinion, I think the burden of maintenance for your override should be rather small. Barring a complete redesign of the vanilla Starlight theme, the structure of the <Sidebar> component should stay mostly the same -- I'm not planning to make any large changes to it, in any case.

   For the immediate future (a.k.a. until I figured out a better solution), I think I will try work on point (3.) and see if it is feasible to expose some 'official' support for various plugins via custom <Sidebar>/<PageSidebar>/... overrides.

   As a final note: I can also recommend checking out the Starlight NextJS Theme, which also sports a centered reading feature, but doesn't override any components to do so.
5. Fevol

   added a commit that references this issue on Oct 15, 2025

   feat: support starlight-sidebar-topics (#9)

   ...

   7a7d84a