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.
Prerequisites
Section titled “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.
Installation (Starlight)
Section titled “ Installation (Starlight)”- Starlight Site Graph is a Starlight plugin that you can install using your favorite package manager:
Terminal window npm i starlight-site-graphTerminal window pnpm add starlight-site-graphTerminal window yarn add starlight-site-graphTerminal window bun add starlight-site-graph - 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',}),],}) - 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})})}; - 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.
Installation (Astro)
Section titled “ 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, though it will require a bit more manual setup.
-
Starlight Site Graph is a package that contains an integration and several components, which you can install using your favorite package manager:
Terminal window npm i starlight-site-graphTerminal window pnpm add starlight-site-graphTerminal window yarn add starlight-site-graphTerminal window bun add starlight-site-graph -
Add the sitemap generation integration of the plugin in your
astro.config.mjs
file. Theprefetch
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()]}) -
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 thesiteGraphSchema
: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),})}; -
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';---<some-content /> -
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 { 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.
-
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
Section titled “Common Issues”Disallowed MIME Type error
Section titled “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
Section titled “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
Section titled “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;