Getting Started

Starlight Site Graph is a Starlight plugin that seamlessly adds a customizable graph to your site, visualizing links between your pages for easy navigation.

Check out the configuration guide to learn more about the plugin’s features, or move on to the installation instructions below to integrate it into your own (Starlight) site.

Note

The theme of this website is provided by Starlight Theme Obsidian, which is designed to integrate well with this plugin.

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Warning

This plugin requires a Starlight version of at least ^0.28.0 - due to the use of the i18next localization system in several components. An Astro version equal or higher than ^4.14.0 is also required for type injection.

New features for this plugin will only be added to recent versions of Starlight/Astro, backwards compatibility is not guaranteed. Refer to the CHANGELOG for more information about specific changes.

Installation (Starlight)

1. Starlight Site Graph is a Starlight plugin that you can install using your favorite package manager:
   npm

   npm i starlight-site-graph

   pnpm

   pnpm add starlight-site-graph

   yarn

   yarn add starlight-site-graph

   bun

   bun add starlight-site-graph

2. Include the plugin in your Starlight configuration in the astro.config.mjs file.

   astro.config.mjs

   import starlight from '@astrojs/starlight'
   import { defineConfig } from 'astro/config'
   import starlightSiteGraph from 'starlight-site-graph'
   
   export default defineConfig({
       integrations: [
           starlight({
               plugins: [starlightSiteGraph()],
               title: 'My Docs',
           }),
       ],
   })

3. Add the Site Graph content schema to your pages to enable type checking on the frontmatter of your pages, you will need to define the src/content/config.ts file if it doesn’t exist yet.

   content/docs/config.ts

    import { docsSchema } from '@astrojs/starlight/schema';
    import { defineCollection } from 'astro:content';
    import { pageSiteGraphSchema } from 'starlight-site-graph/schema';
   
    export const collections = {
      docs: defineCollection({
        schema: docsSchema({
          extend: pageSiteGraphSchema
        })
      })
    };

4. Start the development server to see the graph in action.

That’s it! You should now see the Starlight Site Graph is now added to your Starlight website.

If you want to configure the graph component, sitemap generation or backlinks, check out the configuration guide.

Warning

If another plugin on your site overrides the default <PageSidebar> component (that is, it adds a custom component to the right sidebar of the site), it will likely not work, depending on how the plugin is implemented. Check out this plugin’s <PageSidebar> component to see how the <PageGraph> or <PageBacklinks> components can be added manually.

Installation (Astro)

While the plugin is mainly developed with Starlight support in mind, regular Astro projects can also use this package’s features, though some additional setup is required.

1. Starlight Site Graph is a package that contains an integration and several components, which you can install using your favorite package manager:

   npm

   npm i starlight-site-graph

   pnpm

   pnpm add starlight-site-graph

   yarn

   yarn add starlight-site-graph

   bun

   bun add starlight-site-graph

2. Add the sitemap generation integration of the plugin in your astro.config.mjs file. The prefetch option is required and will be enabled automatically if it wasn’t set already, as the plugin requires it to function properly.

   astro.config.mjs

   import sitegraphSitemapIntegration from 'starlight-site-graph/integration';
   import { defineConfig } from 'astro/config'
   export default defineConfig({
      prefetch: true,
      integrations: [
         // ...
         sitegraphSitemapIntegration()
      ]
   })

   Note

   The Sitemap integration provided by this package is not the same as the official @astrojs/sitemap integration. Where the official sitemap integration maps page contents, this package’s integration maps page connections.

3. Add the Site Graph content schema to your pages to enable type checking on the frontmatter of your pages, you will need to define the src/content/config.ts file if it doesn’t exist yet.
   If you already have a collection defined, you can extend the existing schema with the siteGraphSchema:

   content/docs/config.ts

    import { defineCollection } from 'astro:content';
    import { pageSiteGraphSchema } from 'starlight-site-graph/schema';
   
    export const collections = {
      your-collection: defineCollection({
        schema: someSchema.extend(pageSiteGraphSchema),
      })
    };

4. Add the default style variables for this package into your CSS file (e.g. src/styles/global.css), or add your own:

   src/styles/global.css

   /* Inlude the package's default variables */
    @import "starlight-site-graph/styles/variables.css";
   
   /* ... your other styles ... */
   
   /* Example of overriding some variables */
    :root {
      --slsg-graph-minimized-bg-color: #f0f0f0;
    }

   You can also import the stylesheet only for the pages where you want to add a graph:

   src/pages/my-page.astro

   ---
   import "starlight-site-graph/styles/variables.css";
   import { PageGraph } from 'starlight-site-graph/components';
   ---
   
   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec dui...

5. You can now add the plugin’s components directly to your .astro, .mdx or .mdoc pages (for the latter two, the proper integrations need to be added).
   An example:

   src/pages/my-page.astro

   ---
   import "starlight-site-graph/styles/variables.css";
   import { PageGraph } from 'starlight-site-graph/components';
   ---
   
   <!-- Renders a graph focused on a node matching the current page -->
   <PageGraph />
   
   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec dui...

   For more info, check out the components guide.

6. Start the development server to see the graph in action; only links from markdown content is included while in dev mode (see also: sitemap explanation).

Common Issues

Unexpected graph structure

When enabling this integration for the first time, it is useful to set the depth to the maximum (i.e. depth: 5), so you can see all connections in the graph.

In some cases, it is possible that you have too many or too few connections in the graph:

• Every node is connected to every other node
• There are long chain-like structures in the graph
• All nodes are isolated

The integration’s sitemap generation parses links in both frontmatter, Markdown content and the rendered HTML of your pages. It is possible that you will have to change the sitemapConfig to include/exclude certain links or pages.

Disallowed MIME Type error

If the graph does not show up, and you see the following error in the browser console:

Script from "http://localhost:4321/node_modules/starlight-site-graph/assets/svgs/XYZ.svg?import&raw"
was blocked because of a disallowed MIME type ("inage/svg+xml").

You should delete the .astro folder in the root of your project, and if necessary, restart the development server.

process is not defined error

If the graph does not show up, and you see the following error in the browser console:

Uncaught ReferenceError: process is not defined

This is likely due to an outdated version of the picomatch dependency, included by Astro via the anymatch package (which depends on an old version of picomatch).

To fix this issue, define an overrides in your package.json file to force the use of picomatch version ^4.0.3 or higher:

{
  "dependencies": {
    "...": "..."
    "starlight-site-graph": "^0.5.0",
    "...": "..."
  },
  "overrides": {
    "picomatch": "^4.0.3"
  }
}

Then, force reinstall your dependencies by running the appropriate command for your package manager, or by manually deleting the node_modules folder.

After that, the issue should be resolved.

Visual inconsistencies

If elements included by this package look or feel off, it is likely due to an incorrect @layer order in your CSS.

For example, if you are using Tailwind CSS, make sure that its layers are defined before the sitegraph layer:

@layer base, components, utilities, sitegraph;