Forbidden Trailing Slash

The forbidden trailing slash error indicates that a link points to an existing page, but includes a trailing slash that is not allowed by Astro’s trailingSlash option when it is set to 'never'. If your site uses trailingSlash: 'never', /guides/usage/ should be written as /guides/usage.

Example

For example, given the following project structure:

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryguides/

        • installation.md
        • 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()],
      title: 'My Docs',
    }),
  ],
  trailingSlash: 'never',
})

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

src/content/docs/getting-started.md

---
title: Getting Started
---

## Next Steps

- [Usage guide](/guides/usage/)
- [Installation guide](/guides/installation)

Running a production build reports the following error:

astro build

  ╭─ getting-started.md
  ·
7 | /guides/usage/
  ·             ╰── forbidden trailing slash

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

How to fix

To fix forbidden trailing slash errors, update each affected link so it matches the trailing slash style required by your Astro configuration.

For this example:

• Update /guides/usage/ to /guides/usage.