Skip to content
Starlight Site Graph

Sitemap

If you are making use of the <PageGraph> or <PageBacklinks> components (which, if you have installed the package the regular way in Starlight, you likely already are), these components will need a sitemap which tells them how pages of your website are connected.

Sitemap Generation

Regardless of whether you have installed the package as a regular plugin in Starlight, or as an integration with Astro, every time you run a development server, or build your website, the package will generate a sitemap for you.

Development Server

Summary

  • Links are generated from markdown content every time the development server is started
  • Generated sitemap is accessible from virtual:starlight-site-graph/config
  • Only links formatted as [text](url) are included in the sitemap
  • Links generated by components, loops, etc are not included in the sitemap

Details

Whenever the development server is started, the package will go through all markdown-based content (i.e. .md, .mdx and .mdoc files) in your content directory (see also the contentDir option).

For each file, it will first determine whether the file should be included in the sitemap based on some criteria, and then extract all [text](url) links from the file.

This also means that links in listed in imported .astro components will never be included in the sitemap while running in dev mode. The pages are still only compiled on demand, so links that are dynamically or conditionally generated, will not be included in the sitemap.

src/content/docs/my-page.mdx
---
title: My Page
---


import { LinkCard } from '@astrojs/starlight/components';


This is a link to [another page](/another-page).
<LinkCard title='Link to another page' href='/another-page' />
Importing the sitemap

When running in dev mode, the sitemap will be stored inside the config.sitemapConfig object within the virtual:starlight-site-graph/config virtual module. This can for example be imported as follows:

src/content/docs/my-astronomical-page.astro
---
import config from 'virtual:starlight-site-graph/config';
import { Graph } from "starlight-site-graph/components";
---


<Graph sitemap={config.sitemapConfig.sitemap} ... />

Production Build

Summary

  • Links are generated from statically generated .html files in the dist directory
  • Generated sitemap is bundled separately in dist/sitegraph/sitemap.json for reducing build size, components can still use virtual:starlight-site-graph/config
  • All <a>-type links are included in the sitemap
  • Dynamically generated links (i.e. created from scripts) will not be included in the sitemap

Details

When building your website, the package will go through all .html files in the dist directory (this corresponds to the directory you set as the outDir in the Astro configuration).

For each file, it will first determine whether the file should be included in the sitemap based on some criteria, and then extract all <a>-type links from the file.

Keep in mind that links generated dynamically (via JavaScript) cannot be included in the sitemap, as the package only considers the statically generated HTML files.

Importing the sitemap

After the site is built, the sitemap will be stored in a separate file within outDir/sitegraph/sitemap.json. Then, the <PageGraph> and <PageBacklinks> components will lazily import the sitemap once the page is loaded. This is done to prevent the sitemap from being bundled into every page, which needlessly increases the size of the build.

This behaviour is implemented as follows:

src/content/docs/my-astronomical-page.astro
---
import config from 'virtual:starlight-site-graph/config';
---


<Graph
  slug={slug}
  sitemap={import.meta.env.DEV ? config.sitemapConfig.sitemap : {}}
  config={{ ... }}
/>


<script>
    window.addEventListener('DOMContentLoaded', async () => {
        if (import.meta.env.PROD) {
            let base_url = import.meta.env.BASE_URL;
            if (!base_url.endsWith('/')) {
                base_url += '/';
            }


            const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
            onIdle(async () => {
                const sitemap = await (await fetch(base_url + 'sitegraph/sitemap.json')).json();
                const sitemap_string = JSON.stringify(sitemap);
                document.querySelectorAll('graph-component').forEach((graph) => {
                    if (graph.getAttribute('data-sitemap') === '{}') {
                        graph.setAttribute('data-sitemap', sitemap_string);
                    }
                });
            });
        }
    });
</script>

Sitemap Structure

The sitemap is a JSON object with the following structure:

  • key: The path of the page, must either be an absolute path or an external URL.
    • title: The title of the page in the graph.
    • exists: Whether the page exists or not (also known as an unresolved node).
    • external: Whether the page is an external link.
    • links: An array of paths to pages that this page links to.
    • backlinks: An array of paths to pages that link to this page.
    • tags: An array of tags associated with the page.
    • nodeStyle: The style of the node in the graph, overrides any other styles applied to the node. For more information on how to style nodes, check out the styling documentation.

An example of how this might look in practice:

{
  "/": {
    "title": "Home",
    "exists": true,
    "external": false,
    "links": ["/about", "https://starlight.astro.build/"],
    "tags": ["home"],
    "nodeStyle": {
      "color": "red"
    }
  },
  "/about": {
    "title": "About",
    "exists": true,
    "external": false,
    "backlinks": ["/"],
    "tags": ["about"],
    "nodeStyle": {
      "shapeColor": "nodeColor2"
    }
  },
  "https://starlight.astro.build/": {
    "title": "Starlight",
    "exists": true,
    "external": true,
    "backlinks": ["/"]
  }
}