starlight-links-validator 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # starlight-links-validator
 
+## 0.17.1
+
+### Patch Changes
+
+- [#113](https://github.com/HiDeoo/starlight-links-validator/pull/113) [`3e0a88c`](https://github.com/HiDeoo/starlight-links-validator/commit/3e0a88cd2f7f6f84c57248ae72a8e8df32c22dbe) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Prevents plugin remark plugin from running on Markdown and MDX content when using the Astro [`renderMarkdown()`](https://docs.astro.build/en/reference/content-loader-reference/#rendermarkdown) content loader API.
+
+## 0.17.0
+
+### Minor Changes
+
+- [#108](https://github.com/HiDeoo/starlight-links-validator/pull/108) [`82f8ec5`](https://github.com/HiDeoo/starlight-links-validator/commit/82f8ec5cff97d5b9e343440666a3bb67de216b00) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for [excluding](https://starlight-links-validator.vercel.app/configuration#exclude) links from validation using a function.
+
+  When using the function syntax, the function should return `true` for any link that should be excluded from validation or `false` otherwise. The function will be called for each link to validate and will receive an object containing various properties to help determine whether to exclude the link or not.
+
+  Check out the [`exclude` configuration option](https://starlight-links-validator.vercel.app/configuration#exclude) documentation for more details and examples.
+
 ## 0.16.0
 
 ### Minor Changes

package/index.ts

@@ -1,94 +1,19 @@
 import type { StarlightPlugin } from '@astrojs/starlight/types'
 import type { IntegrationResolvedRoute } from 'astro'
 import { AstroError } from 'astro/errors'
-import { z } from 'astro/zod'
 
 import { clearContentLayerCache } from './libs/astro'
+import { StarlightLinksValidatorOptionsSchema, type StarlightLinksValidatorUserOptions } from './libs/config'
 import { pathnameToSlug, stripTrailingSlash } from './libs/path'
 import { remarkStarlightLinksValidator, type RemarkStarlightLinksValidatorConfig } from './libs/remark'
 import { logErrors, validateLinks } from './libs/validation'
 
-const starlightLinksValidatorOptionsSchema = z
-  .object({
-    /**
-     * Defines a list of additional components and their props that should be validated as links.
-     *
-     * By default, the plugin will only validate links defined in the `href` prop of the `<LinkButton>` and `<LinkCard>`
-     * built-in Starlight components.
-     * Adding custom components to this list will allow the plugin to validate links in those components as well.
-     *
-     * @default []
-     */
-    components: z.tuple([z.string(), z.string()]).array().default([]),
-    /**
-     * Defines whether the plugin should error on fallback pages.
-     *
-     * If you do not expect to have all pages translated in all configured locales and want to use the fallback pages
-     * feature built-in into Starlight, you should set this option to `false`.
-     *
-     * @default true
-     * @see https://starlight.astro.build/guides/i18n/#fallback-content
-     */
-    errorOnFallbackPages: z.boolean().default(true),
-    /**
-     * Defines whether the plugin should error on inconsistent locale links.
-     *
-     * When set to `true`, the plugin will error on links that are pointing to a page in a different locale.
-     *
-     * @default false
-     */
-    errorOnInconsistentLocale: z.boolean().default(false),
-    /**
-     * 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`).
-     *
-     * @default true
-     */
-    errorOnRelativeLinks: z.boolean().default(true),
-    /**
-     * Defines whether the plugin should error on invalid hashes.
-     *
-     * When set to `false`, the plugin will only validate link pages and ignore hashes.
-     *
-     * @default true
-     */
-    errorOnInvalidHashes: z.boolean().default(true),
-    /**
-     * Defines whether the plugin should error on local links, e.g. URLs with a hostname of `localhost` or `127.0.0.1`.
-     *
-     * @default true
-     */
-    errorOnLocalLinks: z.boolean().default(true),
-    /**
-     * Defines a list of links or glob patterns that should be excluded from validation.
-     *
-     * The links in this list will be ignored by the plugin and will not be validated.
-     *
-     * @default []
-     */
-    exclude: z.array(z.string()).default([]),
-    /**
-     * Defines the policy for external links with an origin matching the Astro `site` option.
-     *
-     * By default, all external links are ignored and not validated by the plugin.
-     * Setting this option to `error` will make the plugin error on external links with an origin matching the Astro
-     * `site` option and hint that the link can be rewritten without the origin.
-     * Setting this option to `validate` will make the plugin validate external links with an origin matching the Astro
-     * `site` option as if they were internal links.
-     *
-     * @default 'ignore'
-     * @see https://docs.astro.build/en/reference/configuration-reference/#site
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/origin
-     */
-    sameSitePolicy: z.enum(['error', 'ignore', 'validate']).default('ignore'),
-  })
-  .default({})
+export type { StarlightLinksValidatorOptions } from './libs/config'
 
 export default function starlightLinksValidatorPlugin(
   userOptions?: StarlightLinksValidatorUserOptions,
 ): StarlightPlugin {
-  const options = starlightLinksValidatorOptionsSchema.safeParse(userOptions)
+  const options = StarlightLinksValidatorOptionsSchema.safeParse(userOptions)
 
   if (!options.success) {
     throwPluginError('Invalid options passed to the starlight-links-validator plugin.')
@@ -170,6 +95,3 @@ function throwPluginError(message: string, additionalHint?: string): never {
 
   throw new AstroError(message, hint)
 }
-
-type StarlightLinksValidatorUserOptions = z.input<typeof starlightLinksValidatorOptionsSchema>
-export type StarlightLinksValidatorOptions = z.output<typeof starlightLinksValidatorOptionsSchema>

package/libs/config.ts

@@ -0,0 +1,106 @@
+import { z } from 'astro/zod'
+
+export const StarlightLinksValidatorOptionsSchema = z
+  .object({
+    /**
+     * Defines a list of additional components and their props that should be validated as links.
+     *
+     * By default, the plugin will only validate links defined in the `href` prop of the `<LinkButton>` and `<LinkCard>`
+     * built-in Starlight components.
+     * Adding custom components to this list will allow the plugin to validate links in those components as well.
+     *
+     * @default []
+     */
+    components: z.tuple([z.string(), z.string()]).array().default([]),
+    /**
+     * Defines whether the plugin should error on fallback pages.
+     *
+     * If you do not expect to have all pages translated in all configured locales and want to use the fallback pages
+     * feature built-in into Starlight, you should set this option to `false`.
+     *
+     * @default true
+     * @see https://starlight.astro.build/guides/i18n/#fallback-content
+     */
+    errorOnFallbackPages: z.boolean().default(true),
+    /**
+     * Defines whether the plugin should error on inconsistent locale links.
+     *
+     * When set to `true`, the plugin will error on links that are pointing to a page in a different locale.
+     *
+     * @default false
+     */
+    errorOnInconsistentLocale: z.boolean().default(false),
+    /**
+     * 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`).
+     *
+     * @default true
+     */
+    errorOnRelativeLinks: z.boolean().default(true),
+    /**
+     * Defines whether the plugin should error on invalid hashes.
+     *
+     * When set to `false`, the plugin will only validate link pages and ignore hashes.
+     *
+     * @default true
+     */
+    errorOnInvalidHashes: z.boolean().default(true),
+    /**
+     * Defines whether the plugin should error on local links, e.g. URLs with a hostname of `localhost` or `127.0.0.1`.
+     *
+     * @default true
+     */
+    errorOnLocalLinks: z.boolean().default(true),
+    /**
+     * Defines a list of links or glob patterns that should be excluded from validation or a function that will be
+     * called for each link to determine if it should be excluded from validation or not.
+     *
+     * The links in this list or links where the function returns `true` will be ignored by the plugin and will not be
+     * validated.
+     *
+     * @default []
+     */
+    exclude: z
+      .union([
+        z.array(z.string()),
+        z
+          .function()
+          .args(
+            z.object({
+              /**
+               * The absolute path to the file where the link is defined.
+               */
+              file: z.string(),
+              /**
+               * The link to validate as authored in the content.
+               */
+              link: z.string(),
+              /**
+               * The slug of the page where the link is defined.
+               */
+              slug: z.string(),
+            }),
+          )
+          .returns(z.boolean()),
+      ])
+      .default([]),
+    /**
+     * Defines the policy for external links with an origin matching the Astro `site` option.
+     *
+     * By default, all external links are ignored and not validated by the plugin.
+     * Setting this option to `error` will make the plugin error on external links with an origin matching the Astro
+     * `site` option and hint that the link can be rewritten without the origin.
+     * Setting this option to `validate` will make the plugin validate external links with an origin matching the Astro
+     * `site` option as if they were internal links.
+     *
+     * @default 'ignore'
+     * @see https://docs.astro.build/en/reference/configuration-reference/#site
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/URL/origin
+     */
+    sameSitePolicy: z.enum(['error', 'ignore', 'validate']).default('ignore'),
+  })
+  .default({})
+
+export type StarlightLinksValidatorUserOptions = z.input<typeof StarlightLinksValidatorOptionsSchema>
+export type StarlightLinksValidatorOptions = z.output<typeof StarlightLinksValidatorOptionsSchema>

package/libs/i18n.ts

@@ -1,5 +1,5 @@
 import { ensureLeadingSlash, ensureTrailingSlash, stripLeadingSlash } from './path'
-import type { Headings } from './remark'
+import type { ValidationData } from './remark'
 import type { StarlightUserConfig } from './validation'
 
 export function getLocaleConfig(config: StarlightUserConfig): LocaleConfig | undefined {
@@ -30,7 +30,7 @@ export function getLocaleConfig(config: StarlightUserConfig): LocaleConfig | und
 
 export function getFallbackHeadings(
   path: string,
-  headings: Headings,
+  validationData: ValidationData,
   localeConfig: LocaleConfig | undefined,
   base: string,
 ): string[] | undefined {
@@ -48,7 +48,7 @@ export function getFallbackHeadings(
           (localeConfig.defaultLocale === '' ? localeConfig.defaultLocale : `${localeConfig.defaultLocale}/`),
       )
 
-      return headings.get(fallbackPath === '' ? '/' : fallbackPath)
+      return validationData.get(fallbackPath === '' ? '/' : fallbackPath)?.headings
     }
   }
 

package/libs/remark.ts

@@ -25,10 +25,8 @@ const builtInComponents: StarlightLinksValidatorOptions['components'] = [
   ['LinkCard', 'href'],
 ]
 
-// All the headings keyed by file path.
-const headings: Headings = new Map()
-// All the internal links keyed by file path.
-const links: Links = new Map()
+// All the validation data keyed by file path.
+const data: ValidationData = new Map()
 
 export const remarkStarlightLinksValidator: Plugin<[RemarkStarlightLinksValidatorConfig], Root> = function (config) {
   const { base, options, srcDir } = config
@@ -38,10 +36,16 @@ export const remarkStarlightLinksValidator: Plugin<[RemarkStarlightLinksValidato
   )
 
   return (tree, file) => {
+    // If the content does not have a path, e.g. when rendered using the content loader `renderMarkdown()` API, skip it.
+    if (!file.path) return
+
     if (file.data.astro?.frontmatter?.['draft']) return
 
+    const originalPath = file.history[0]
+    if (!originalPath) throw new Error('Missing file path to validate links.')
+
     const slugger = new GitHubSlugger()
-    const filePath = normalizeFilePath(base, srcDir, file.history[0])
+    const filePath = normalizeFilePath(base, srcDir, originalPath)
     const slug: string | undefined =
       typeof file.data.astro?.frontmatter?.['slug'] === 'string' ? file.data.astro.frontmatter['slug'] : undefined
 
@@ -155,13 +159,16 @@ export const remarkStarlightLinksValidator: Plugin<[RemarkStarlightLinksValidato
       }
     })
 
-    headings.set(getFilePath(base, filePath, slug), fileHeadings)
-    links.set(getFilePath(base, filePath, slug), fileLinks)
+    data.set(getFilePath(base, filePath, slug), {
+      file: originalPath,
+      headings: fileHeadings,
+      links: fileLinks,
+    })
   }
 }
 
-export function getValidationData() {
-  return { headings, links }
+export function getValidationData(): ValidationData {
+  return data
 }
 
 function getLinkToValidate(link: string, { options, site }: RemarkStarlightLinksValidatorConfig): Link | undefined {
@@ -202,11 +209,7 @@ function getFilePath(base: string, filePath: string, slug: string | undefined) {
   return filePath
 }
 
-function normalizeFilePath(base: string, srcDir: URL, filePath?: string) {
-  if (!filePath) {
-    throw new Error('Missing file path to validate links.')
-  }
-
+function normalizeFilePath(base: string, srcDir: URL, filePath: string) {
   const path = nodePath
     .relative(nodePath.join(fileURLToPath(srcDir), 'content/docs'), filePath)
     .replace(/\.\w+$/, '')
@@ -234,8 +237,17 @@ export interface RemarkStarlightLinksValidatorConfig {
   srcDir: URL
 }
 
-export type Headings = Map<string, string[]>
-export type Links = Map<string, Link[]>
+export type ValidationData = Map<
+  string,
+  {
+    // The absolute path to the file.
+    file: string
+    // All the headings.
+    headings: string[]
+    // All the internal links.
+    links: Link[]
+  }
+>
 
 export interface Link {
   error?: ValidationErrorType

package/libs/validation.ts

@@ -11,7 +11,7 @@ import type { StarlightLinksValidatorOptions } from '..'
 
 import { getFallbackHeadings, getLocaleConfig, isInconsistentLocaleLink, type LocaleConfig } from './i18n'
 import { ensureTrailingSlash, stripLeadingSlash, stripTrailingSlash } from './path'
-import { getValidationData, type Headings, type Link } from './remark'
+import { getValidationData, type Link, type ValidationData } from './remark'
 
 export const ValidationErrorType = {
   InconsistentLocale: 'inconsistent locale',
@@ -36,7 +36,7 @@ export function validateLinks(
   process.stdout.write(`\n${bgGreen(black(` validating links `))}\n`)
 
   const localeConfig = getLocaleConfig(starlightConfig)
-  const { headings, links } = getValidationData()
+  const validationData = getValidationData()
   const allPages: Pages = new Set(
     pages.map((page) =>
       ensureTrailingSlash(
@@ -49,19 +49,19 @@ export function validateLinks(
 
   const errors: ValidationErrors = new Map()
 
-  for (const [filePath, fileLinks] of links) {
+  for (const [filePath, { links: fileLinks }] of validationData) {
     for (const link of fileLinks) {
       const validationContext: ValidationContext = {
         astroConfig,
         customPages,
         errors,
         filePath,
-        headings,
         link,
         localeConfig,
         options,
         outputDir,
         pages: allPages,
+        validationData,
       }
 
       if (link.raw.startsWith('#') || link.raw.startsWith('?')) {
@@ -194,23 +194,29 @@ function validateLink(context: ValidationContext) {
   }
 }
 
-function getFileHeadings(path: string, { astroConfig, headings, localeConfig, options }: ValidationContext) {
-  let heading = headings.get(path === '' ? '/' : path)
+function getFileHeadings(path: string, { astroConfig, localeConfig, options, validationData }: ValidationContext) {
+  let headings = validationData.get(path === '' ? '/' : path)?.headings
 
-  if (!options.errorOnFallbackPages && !heading && localeConfig) {
-    heading = getFallbackHeadings(path, headings, localeConfig, astroConfig.base)
+  if (!options.errorOnFallbackPages && !headings && localeConfig) {
+    headings = getFallbackHeadings(path, validationData, localeConfig, astroConfig.base)
   }
 
-  return heading
+  return headings
 }
 
 /**
  * Validate a link to an hash in the same page.
  */
-function validateSelfHash({ errors, link, filePath, headings }: ValidationContext) {
+function validateSelfHash(context: ValidationContext) {
+  const { errors, link, filePath, validationData } = context
+
+  if (isExcludedLink(link, context)) {
+    return
+  }
+
   const hash = link.raw.split('#')[1] ?? link.raw
   const sanitizedHash = hash.replace(/^#/, '')
-  const fileHeadings = headings.get(filePath)
+  const fileHeadings = validationData.get(filePath)?.headings
 
   if (!fileHeadings) {
     throw new Error(`Failed to find headings for the file at '${filePath}'.`)
@@ -248,8 +254,17 @@ function isValidAsset(path: string, context: ValidationContext) {
 /**
  * Check if a link is excluded from validation by the user.
  */
-function isExcludedLink(link: Link, context: ValidationContext) {
-  return picomatch(context.options.exclude)(stripQueryString(link.raw))
+function isExcludedLink(link: Link, { filePath, options, validationData }: ValidationContext) {
+  if (Array.isArray(options.exclude)) return picomatch(options.exclude)(stripQueryString(link.raw))
+
+  const file = validationData.get(filePath)?.file
+  if (!file) throw new Error('Missing file path to check exclusion.')
+
+  return options.exclude({
+    file,
+    link: link.raw,
+    slug: stripTrailingSlash(filePath),
+  })
 }
 
 function stripQueryString(path: string): string {
@@ -294,12 +309,12 @@ interface ValidationContext {
   customPages: Set<string>
   errors: ValidationErrors
   filePath: string
-  headings: Headings
   link: Link
   localeConfig: LocaleConfig | undefined
   options: StarlightLinksValidatorOptions
   outputDir: URL
   pages: Pages
+  validationData: ValidationData
 }
 
 export type StarlightUserConfig = Omit<StarlightUserConfigWithPlugins, 'plugins'>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-links-validator",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "license": "MIT",
   "description": "Starlight plugin to validate internal links.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
@@ -26,6 +26,8 @@
     "@types/mdast": "^4.0.4",
     "@types/node": "^18.19.68",
     "remark-custom-heading-id": "^2.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
     "unified": "^11.0.5",
     "vfile": "^6.0.3",
     "vitest": "2.1.6"