feat!: add errors for relative internal links

docs/src/content/docs/configuration.md

@@ -51,3 +51,27 @@ export default defineConfig({
   ],
 })
 ```
+
+### `errorOnRelativeLinks`
+
+**Type:** `boolean`  
+**Default:** `true`
+
+Relative internal links, such as `./test` or `../test`, are usually considered confusing as they can be difficult to reason about, figure out where they point to and require more maintenance when a page is moved.
+
+By default, the Starlight Links Validator plugin will error if a relative internal link is found.
+If you want to allow relative internal links, you can set this option to `false` but note that theses links will not be validated.
+
+```js {6}
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [
+        starlightLinksValidator({
+          errorOnRelativeLinks: false,
+        }),
+      ],
+    }),
+  ],
+})
+```

packages/starlight-links-validator/index.ts

@@ -17,6 +17,12 @@ const starlightLinksValidatorOptionsSchema = z
      * @see https://starlight.astro.build/guides/i18n/#fallback-content
      */
     errorOnFallbackPages: z.boolean().default(true),
+    /**
+     * Defines whether the plugin should error on internal relative links.
+     *
+     * When set to `false`, the plugin will ignore relative links (e.g. `./foo` or `../bar`).
+     */
+    errorOnRelativeLinks: z.boolean().default(true),
   })
   .default({})
 

packages/starlight-links-validator/libs/remark.ts

@@ -131,7 +131,7 @@ export function getValidationData() {
 }
 
 function isInternalLink(link: string) {
-  return nodePath.isAbsolute(link) || link.startsWith('#')
+  return nodePath.isAbsolute(link) || link.startsWith('#') || link.startsWith('.')
 }
 
 function normalizeFilePath(filePath?: string) {

packages/starlight-links-validator/libs/validation.ts

@@ -84,7 +84,7 @@ export function logErrors(errors: ValidationErrors) {
  * Validate a link to another internal page that may or may not have a hash.
  */
 function validateLink(context: ValidationContext) {
-  const { errors, filePath, link, outputDir, pages } = context
+  const { errors, filePath, link, options, outputDir, pages } = context
 
   const sanitizedLink = link.replace(/^\//, '')
   const segments = sanitizedLink.split('#')
@@ -96,6 +96,14 @@ function validateLink(context: ValidationContext) {
     throw new Error('Failed to validate a link with no path.')
   }
 
+  if (path.startsWith('.')) {
+    if (options.errorOnRelativeLinks) {
+      addError(errors, filePath, link)
+    }
+
+    return
+  }
+
   if (isValidAsset(path, outputDir)) {
     return
   }

packages/starlight-links-validator/tests/basics.test.ts

@@ -11,12 +11,12 @@ test('should build with valid links', async () => {
 })
 
 test('should not build with invalid links', async () => {
-  expect.assertions(4)
+  expect.assertions(5)
 
   try {
     await loadFixture('basics-invalid-links')
   } catch (error) {
-    expect(error).toMatch(/Found 20 invalid links in 3 files./)
+    expect(error).toMatch(/Found 25 invalid links in 4 files./)
 
     expect(error).toMatch(
       new RegExp(`▶ test/
@@ -49,5 +49,14 @@ test('should not build with invalid links', async () => {
   ├─ #some-other-content
   └─ /guides/namespacetest/#another-content`),
     )
+
+    expect(error).toMatch(
+      new RegExp(`▶ relative/
+  ├─ .
+  ├─ ./relative
+  ├─ ./test
+  ├─ ./guides/example
+  └─ ../test`),
+    )
   }
 })

packages/starlight-links-validator/tests/fixtures/basics-invalid-links/src/content/docs/relative.md

@@ -0,0 +1,9 @@
+---
+title: Relative
+---
+
+- [Link to the same page](.)
+- [Link to the same page with its name](./relative)
+- [Link to another page in the same directory](./test)
+- [Link to another page in another directory](./guides/example)
+- [Link to another page in a parent directory](../test)

packages/starlight-links-validator/tests/fixtures/relative-ignore/astro.config.ts

@@ -0,0 +1,13 @@
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+
+import starlightLinksValidator from '../..'
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [starlightLinksValidator({ errorOnRelativeLinks: false })],
+      title: 'Starlight Links Validator Tests - relative ignore',
+    }),
+  ],
+})

packages/starlight-links-validator/tests/fixtures/relative-ignore/src/content/docs/guides/example.md

@@ -0,0 +1,7 @@
+---
+title: Example
+---
+
+## Description
+
+This is an example page.

packages/starlight-links-validator/tests/fixtures/relative-ignore/src/content/docs/relative.md

@@ -0,0 +1,9 @@
+---
+title: Relative
+---
+
+- [Link to the same page](.)
+- [Link to the same page with its name](./relative)
+- [Link to another page in the same directory](./test)
+- [Link to another page in another directory](./guides/example)
+- [Link to another page in a parent directory](../test)

packages/starlight-links-validator/tests/fixtures/relative-ignore/src/content/docs/test.md

@@ -0,0 +1,19 @@
+---
+title: Test
+---
+
+# Some links
+
+- [External link](https://starlight.astro.build/)
+
+- [Example page](/guides/example)
+- [Example page](/guides/example/)
+
+- [Example page with hash](/guides/example#description)
+- [Example page with hash](/guides/example/#description)
+
+- [Unknown page](/unknown)
+- [Unknown page](/unknown/)
+
+- [Example page with unknown hash](/guides/example#unknown)
+- [Example page with unknown hash](/guides/example/#unknown)

packages/starlight-links-validator/tests/relative.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from 'vitest'
+
+import { loadFixture } from './utils'
+
+test('should ignore relative links when the `errorOnRelativeLinks` option is set to `false`', async () => {
+  expect.assertions(2)
+
+  try {
+    await loadFixture('relative-ignore')
+  } catch (error) {
+    expect(error).toMatch(/Found 4 invalid links in 1 file./)
+
+    expect(error).toMatch(
+      new RegExp(`▶ test/
+  ├─ /unknown
+  ├─ /unknown/
+  ├─ /guides/example#unknown
+  └─ /guides/example/#unknown`),
+    )
+  }
+})

packages/starlight-links-validator/tests/trailing.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from 'vitest'
 
 import { loadFixture } from './utils'
 
-test('should validate links when the `trailingSlash` option is set to `never`', async () => {
+test('should validate links when the `trailingSlash` Astro option is set to `never`', async () => {
   expect.assertions(2)
 
   try {
@@ -20,7 +20,7 @@ test('should validate links when the `trailingSlash` option is set to `never`',
   }
 })
 
-test('should validate links when the `trailingSlash` option is set to `always`', async () => {
+test('should validate links when the `trailingSlash` Astro option is set to `always`', async () => {
   expect.assertions(2)
 
   try {