Skip to content
Starlight Links Validator

Same Site

The same site error indicates that a link uses a full external URL whose origin matches the one configured in Astro’s site option. For example, if your site is https://example.com, then https://example.com/guides/usage/ points to the same site and can usually be written as /guides/usage/ instead.

This behavior is controlled by the sameSitePolicy option. By default, all external links are ignored and are not validated. When sameSitePolicy is set to error, external links with the same origin as your site report a same site error. When it is set to validate, they are treated like internal links and validated as if they were written without the origin.

Example

Section titled “Example”

For example, given the following project structure:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryguides/
          • usage.mdx
        • getting-started.md
  • astro.config.mjs

With the following configuration in astro.config.mjs:

astro.config.mjs
import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightLinksValidator from 'starlight-links-validator'


export default defineConfig({
  integrations: [
    starlight({
      plugins: [starlightLinksValidator({ sameSitePolicy: 'error' })],
      title: 'My Docs',
    }),
  ],
  site: 'https://example.com',
})

And the following content in src/content/docs/getting-started.md:

src/content/docs/getting-started.md
---
title: Getting Started
---


## Next Steps


- [Usage guide](https://example.com/guides/usage/)
- [Updating](https://example.com/getting-started/#updating)


## Updating


Some content.

Running a production build reports the following errors:

astro build
  ╭─ getting-started.md
  ·
7 | https://example.com/guides/usage/
  ·                                ╰── https://example.com can be omitted
8 | https://example.com/getting-started/#updating
  ·                                            ╰── https://example.com can be omitted


╭─                                ─╮
· Found 2 invalid links in 1 file. ·
╰─                                ─╯

How to fix

Section titled “How to fix”

To fix same site errors, replace each same-origin absolute URL with the equivalent root-relative path.

For this example:

  • Update https://example.com/guides/usage/ to /guides/usage/.
  • Update https://example.com/getting-started/#updating to #updating because the target heading is in the same page and only the hash is needed.