starlight-site-graph dependency

I've recently been working on a website to preview all existing Starlight themes on the same site, and hit various issues when trying to add the Starlight Obsidian Theme.

I'm creating this single issue to report them all (and also sharing some feedback) rather than spamming the issue tracker, but let me know if you'd prefer separate issues.

The package has a non-optional peer dependency on starlight-site-graph but the Getting Started guide doesn't mention it.
As the website I'm creating is meant to compare themes on a fixed set of content, I immediately went ahead to the note at the end of the guide to disable the graph and backlinks:
- If graphs can be disabled, I guess starlight-site-graph should probably be an optional peer dependency?
- When having graph: false, the starlight-site-graph-integration seems to still be running, I would not expect that to happen.
- Even with graphs disabled, it looks like the theme is still importing its CSS, or relying on some feature of it. I guess that should be conditional and only loaded when graphs are enabled?
I guess this last issue would be resolved if the graph integration was not running with graph: false, but sharing it anyway as it's still a problem:
- My website is using a custom srcDir, and the starlight-site-graph-integration is complaining about "Content root "./src/content/docs" does not exist, please check your configuration.". I guess that when I'm using a custom srcDir, if the theme adds the graph integration, it should probably specify the content root based on the srcDir value or maybe just have the starlight-site-graph use the srcDir from the Astro config itself?
Some feedback regarding the step 3 of the Getting Started guide:
- It would be nice to explain what is the purpose of the theme schema, I personally have no idea what it is for, or maybe move that part to a dedicated section if it's optional.
- The example could probably be updated to use the src/content.config.ts file instead of the legacy one.

Sorry for the long message, and in the end it's mostly one single large issue but I prefered to share all my findings and feedback in one go.

Really eager to add the Obsidian theme to my preview site as it's a wonderful theme 🌟

Hi, thanks for the issue, I appreciate the comments and insights! This single issue is fine, as it is indeed all part of the same general problem.

My spare time has become quite limited recently, but I am currently in the process of fixing up starlight-site-graph, and I will get to this as soon as I am able to. But to answer some of your questions:

The package has a non-optional peer dependency on starlight-site-graph but the Getting Started guide doesn't mention it.

This is something I have been struggling with. I remember that I did try to make it fully optional in the past, though I forgot exactly what the blocker was there. In any case, I have some ideas on how to implement this - and hopefully I'll be more successful this time!

As the website I'm creating is meant to compare themes on a fixed set of content, I immediately went ahead to the note at the end of the guide to disable the graph and backlinks:

If graphs can be disabled, I guess starlight-site-graph should probably be an optional peer dependency?

When having graph: false, the starlight-site-graph-integration seems to still be running, I would not expect that to happen.

Even with graphs disabled, it looks like the theme is still importing its CSS, or relying on some feature of it. I guess that should be conditional and only loaded when graphs are enabled?

Normally, when you disable both the graph and backlinks, the starlight-site-graph extension will still run, but not execute any of its sitemapping code. But yes, all this behaviour could (and should) be made optional or removed.

I guess this last issue would be resolved if the graph integration was not running with graph: false, but sharing it anyway as it's still a problem:

My website is using a custom srcDir, and the starlight-site-graph-integration is complaining about "Content root "./src/content/docs" does not exist, please check your configuration.". I guess that when I'm using a custom srcDir, if the theme adds the graph integration, it should probably specify the content root based on the srcDir value or maybe just have the starlight-site-graph use the srcDir from the Astro config itself?

Whoops, yeah, this is not a very descriptive error message. You also bring up a good point, I am not entirely sure why I am not using the srcDir as a default (maybe to avoid scanning files in components and other files). Regardless, I don't think there is a reason to not use this - thanks!

Some feedback regarding the step 3 of the Getting Started guide:

It would be nice to explain what is the purpose of the theme schema, I personally have no idea what it is for, or maybe move that part to a dedicated section if it's optional.

In the past, this schema was mandatory (there were some frontmatter data you could define to interact with starlight-site-graph, but those have since been moved into the package itself). I'll probably rewrite that section once the site-graph package has been decoupled from the theme.

The example could probably be updated to use the src/content.config.ts file instead of the legacy one.

Good catch, thanks!

Again, thanks for all the feedback. As a side note: the preview site looks great, thank you for creating it!

Amazing, thanks for the quick response!

I am not entirely sure why I am not using the srcDir as a default (maybe to avoid scanning files in components and other files)

Considering that Starlight does not yet support customizable content location, you can assume the content directory will always be srcDir + /content/docs, e.g. that's what we do in Starlight itself.

If needed, do not hesitate to let me know if there are some points where you'd like me to take a look at or help with. No rush in any case, thank you for your work on this great theme!

feat: decouple starlight-site-graph from starlight-theme-obsidian (#14)

refactor: use Astro's `srcDir` option to set default `contentRoot` pr…

Hello, sorry to be the "any updates?" guy, I was just curious if there's any chance to get this released, it looks like some work was done in 3f0c7b6 which may solve some problems for me if it was released on npm. Currently this is blocking me from upgrading to Astro 6, I get npm warnings since this package pulls starlight-site-graph@0.5.0 which, in turn, pulls astro-integration-kit@0.18.0 that has "astro": "^4.12.0 || ^5.0.0" as a peer dep. The build also fails which I assume is because this package doesn't actually support Astro 6 (or maybe I'm doing something weird?):

> developer-portal@0.0.1 dev
> astro dev --mode dev

17:21:13 [ERROR] [@astrojs/starlight] An unhandled error occurred while running the "astro:config:setup" hook
[AstroUserError] Invalid options passed to "starlight-site-graph-integration" integration

  Hint:
    Invalid input: expected map, received object
  Location:
    C:\<location>\node_modules\starlight-site-graph\node_modules\astro-integration-kit\dist\core\index.js:2:751
  Stack trace:
    at file:///C:/<location>/node_modules/starlight-site-graph/node_modules/astro-integration-kit/dist/core/index.js:2:751
    at config:setup (C:/<location>/node_modules/starlight-theme-obsidian/index.ts:26:56)
    at async runPlugins (C:/<location>/frontend/node_modules/@astrojs/starlight/utils/plugins.ts:64:5)

I'm not using the site graph so seeing it removed from the deps would be nice, but even some package upgrade may help too! I understand that may be easier said than done though.

Either way, thank you for this great theme ⭐

@MarcusCaspeco

Hi, no worries @MarcusCaspeco! Apologies for the long wait and lack of updates here. I am currently in the process of finishing up a rewrite starlight-site-graph's graph engine; once that is done, I am doing a final pass and releasing a new version for both packages. This blocker should hopefully not be a concern anymore in the future.

As far as the Astro 6 is concerned, there shouldn't be any breaking changes. I have just pushed a commit that bumps the dependencies of the package. I am not sure whether it will work out of the box, but if you want, you can directly depend on this commit for now:

npm install github:fevol/starlight-theme-obsidian#path:packages/starlight-theme-obsidian

This should really only be temporary, I am not planning to take another couple months to get a new release out of the door 😅

@Fevol

@Fevol Hi, thank you for your work on this, this is a really cool project. I was wondering if there are any updates on your progress on the re-write? We're currently using Quartz for some stuff, but in terms of DX I feel like it's not that great, so I was wondering if Astro might be a bit better, and I saw this theme, which would be perfect for us.

@bennymi

Hi @bennymi, sorry for the late reply! I have been continuing to chip away at the starlight-site-graph changes in the background (though in a slower pace than I'd like...). The update completely ballooned in scope, and while I do believe it is for the better, I am not fully comfortable releasing it in a half-baked state - especially since I have been testing out LLMs for development.

I've gotten to really dislike making promises, because I am genuinely awful at keeping them, and I don't want to betray your expectations. That being said, my hope (and plan) is to finish the rewrites I wanted to do before I head off on vacation in about two weeks time.

In the meantime, you can depend on the latest Astro version using the npm install I mentioned above - it should work. (I believe you need to do the same install for starlight-site-graph compatibility).

Navigation Menu

Repository navigation

`starlight-site-graph` dependency #14

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

starlight-site-graph dependency #14

Description

Activity

Fevol commented on Oct 7, 2025

HiDeoo commented on Oct 7, 2025

MarcusCaspeco commented on Apr 21, 2026

Fevol commented on Apr 21, 2026

bennymi commented on Jul 23, 2026

Fevol commented on Jul 24, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

`starlight-site-graph` dependency #14