starlight-links-validator 0.17.0 → 0.17.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # starlight-links-validator
 
+## 0.17.2
+
+### Patch Changes
+
+- [#115](https://github.com/HiDeoo/starlight-links-validator/pull/115) [`b042c61`](https://github.com/HiDeoo/starlight-links-validator/commit/b042c61d479ad6584a4065bf84dadb6f3078145a) Thanks [@trueberryless](https://github.com/trueberryless)! - Fixes validation issue for links to Starlight page's title anchor, e.g. `/getting-started/#_top`.
+
+## 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

package/index.ts

@@ -1,119 +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 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 { 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.')
@@ -195,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/remark.ts

@@ -36,6 +36,9 @@ 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]
@@ -46,7 +49,7 @@ export const remarkStarlightLinksValidator: Plugin<[RemarkStarlightLinksValidato
     const slug: string | undefined =
       typeof file.data.astro?.frontmatter?.['slug'] === 'string' ? file.data.astro.frontmatter['slug'] : undefined
 
-    const fileHeadings: string[] = []
+    const fileHeadings: string[] = ['_top']
     const fileLinks: Link[] = []
     const fileDefinitions = new Map<string, string>()
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-links-validator",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "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"