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.

Note

The styling on this website is provided by Starlight Theme Obsidian, which includes this plugin out of the box.

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.

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

   yarn

   yarn add starlight-site-graph

   pnpm

   pnpm add starlight-site-graph

2. Configure 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 page’s frontmatter, 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 you have a plugin which overrides the default <PageSidebar> component, it will likely not work, depending on how the plugin is implemented. Check out this plugin’s <PageSidebar> component for reference.

Installation (Astro)

While the plugin is mainly developed with Starlight support in mind, it is also possible to add the <PageGraph> or <PageBacklinks> components to regular Astro projects (without a sidebar), though it will require a little more manual setup.

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

   yarn

   yarn add starlight-site-graph

   pnpm

   pnpm add starlight-site-graph

2. Add the sitemap generation integration of the plugin in your astro.config.mjs file. You may need to enable prefetch if you are encountering errors.

   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. The difference lies in the fact the official integration maps contents while the package’s integration maps connections.

3. Add the Site Graph content schema to your pages to enable type checking on the page’s frontmatter, 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. 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/content/docs/my-page.mdx

   ---
   title: "My Page"
   ---
   import { PageGraph } from 'starlight-site-graph/components'
   
   <!-- This will render a graph centered on the current page -->
   <PageGraph />
   
   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam nec dui...

   For more info, check out the components guide.
5. Start the development server to see the graph in action.