Skip to content
Starlight Site Graph

Inclusion

This page details configuration options for changing what is included in the sitemap.

Content Root

Section titled “Content Root”

The contentRoot option specifies from which directory files should be parsed to generate the sitemap. By default, this is set to ./src/content/docs. If you have your pages stored elsewhere, you will likely have to change this option.

Example:

  • Directorysrc
    • Directorycontent
      • Directorydocs
        • Directoryprivate These files are included in the sitemap
          • basic-secretive-page.md
          • reactive-hidden-page.mdx
          • yet-another-special-page.mdoc
          • astronomically-exclusive.astro
          • …
        • Directorypublic These files are included in the sitemap
          • index.md
          • about.mdx
          • contact.mdoc
          • faq.astro
          • …

Page Inclusion Rules

Section titled “Page Inclusion Rules”

The pageInclusionRules option allows you to specify which pages should be included in the sitemap based on their file path. The rules are specified as a list of strings, where each string is a glob pattern. The first rule that was matched, determines whether the page is included or not.

If the inclusion of a page was specified in its frontmatter, it will take precedence over the rules specified here.

All files are included in the sitemap.

  • Directorysrc
    • Directorycontent
      • Directorydocs
        • Directoryprivate
          • basic-secretive-page.md
          • reactive-hidden-page.mdx
          • yet-another-special-page.mdoc
          • astronomically-exclusive.astro
          • …
        • Directorypublic
          • index.md
          • about.mdx
          • contact.mdoc
          • faq.astro
          • …

New Ignore Links in Selectors

Section titled “ Ignore Links in Selectors”

The ignoreLinksInSelectors option allows you to specify CSS-like selectors to ignore links that are contained within HTML elements that match the selector. This is useful if you want to ignore links in specific parts of your pages, such as the header, footer, or sidebar.

The possible types of selectors are:

  • Tag selectors (e.g. header, footer, nav, aside, etc.)
  • Class selectors (e.g. .class-name)
  • ID selectors (e.g. #id-name)

A selector may only consist of a single tag, class, or ID - complex selectors (e.g. header nav, .class1.class2, #id1 #id2, etc.) are not supported.

If a link (<a> element in the generated HTML) is contained within an element that matches any of the specified selectors, it will be ignored and not included in the final sitemap.

By default, this setting is set to ['header', 'footer', 'nav', '.right-sidebar', '.site-title'], which will result in all common Starlight links being ignored (i.e. table of contents, edit link, social links, pagination links, etc.).

All links are included.

<header>
  <nav>
    <a href="/link1">Header Link</a>
  </nav>
</header>
<main>
  <raw>
    Lorem ipsum dolor sit <a href="/link2">amet</a>.
  </raw>
  <aside class="right-sidebar">
    <a href="/link3">Sidebar Link</a>
  </aside>
</main>
<div id="footer">
  <a href="/link4">Footer Link</a>
</div>

Deprecated Ignore Starlight Links

Section titled “ Ignore Starlight Links”

By default, Starlight adds additional links to every page, such as the “Edit this page”, “Built with Starlight”, and icons links. Since this is not necessarily useful (meaningful) for the graph, as it will clutter pages together, you can choose to ignore these types of links via the ignoreStarlightLinks option - this setting is true by default.

Here are all the types of links that are ignored:

  • Edit this page (created by editLink: { 'baseUrl': '...' })
  • Built with Starlight (created by credits: true)
  • Social links (created by social: { ... })
  • Pagination links connecting previous and next pages (created by pagination: true)
  • Links to the landing page/root page (always added for title)

These ignores are added as part of the linkInclusionRules configuration. If you want to override the behaviour (i.e. keep a link that would otherwise be ignored), you can do so by specifying the link as a positive rule in the linkInclusionRules configuration (without a ! prefix).

As an example, specifying linkInclusionRules: ["https://starlight.astro.build", "**/*"] will result in the credits link not being ignored.

Finally, if you are not using Starlight, this setting will have no effect.

Section titled “Link Inclusion Rules”

The linkInclusionRules option allows you to specify which links should be included in the sitemap based on their target path. The rules are specified as a list of strings, where each string is a glob pattern. The first rule that was matched, determines whether the link is included or not.

If a link was specified in the frontmatter of a page, it will always be included, regardless of the rules specified here.

All links are matched.

a-linked-document.md
This document contains many [links](/link) to other pages.
Here is one that goes to [another link here](/here/another/link).
This one goes to [Astro](https://astro.build).
And this one goes [nowhere](https://no.w/here/).
Section titled “Include External Links”

The includeExternalLinks option toggles whether external links will be included in the sitemap.

a-cool-document.md
This is a *cool* document
  which links to [a boring page](/another-page).
Because I am a **very cool** document,
  I will also link to [Starlight](https://starlight.astro.build).