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 Astro’s srcDir + /content/docs for Starlight (i.e. ./src/content/docs), and srcDir + /pages for vanilla Astro sites (i.e. ./src/pages).

Normally, you should not have to change this setting, as this will have an effect on how the paths of pages are constructed.

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 (relative to the contentRoot). 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>
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).