starlight-versions 0.10.1 → 0.10.2

package/.npmignore

@@ -0,0 +1,5 @@
+eslint.config.mjs
+fixtures
+tests
+tsconfig.json
+tsconfig.tsbuildinfo

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # starlight-versions
 
+## 0.10.2
+
+### Patch Changes
+
+- [#86](https://github.com/HiDeoo/starlight-versions/pull/86) [`27959fb`](https://github.com/HiDeoo/starlight-versions/commit/27959fb72e19fbad44a79fe673a2246ab64ad05a) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes versioning of public assets in media elements using both `src` and `srcset` attributes.
+
+- [#84](https://github.com/HiDeoo/starlight-versions/pull/84) [`7cc6fdf`](https://github.com/HiDeoo/starlight-versions/commit/7cc6fdfe49f66df7a77b1f1b18891ebe50a37b1e) Thanks [@dgesteves](https://github.com/dgesteves)! - Fixes versioning of Markdown files using syntax that is not valid in MDX, like `<->` arrows.
+
+- [#86](https://github.com/HiDeoo/starlight-versions/pull/86) [`27959fb`](https://github.com/HiDeoo/starlight-versions/commit/27959fb72e19fbad44a79fe673a2246ab64ad05a) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes versioning of public assets in `srcset` attributes with multiple images or descriptors.
+
+- [#86](https://github.com/HiDeoo/starlight-versions/pull/86) [`27959fb`](https://github.com/HiDeoo/starlight-versions/commit/27959fb72e19fbad44a79fe673a2246ab64ad05a) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes versioning of images inside links.
+
+- [#86](https://github.com/HiDeoo/starlight-versions/pull/86) [`27959fb`](https://github.com/HiDeoo/starlight-versions/commit/27959fb72e19fbad44a79fe673a2246ab64ad05a) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes versioning of public assets in inline media elements in MDX files.
+
 ## 0.10.1
 
 ### Patch Changes

package/libs/markdown.ts

@@ -1,6 +1,8 @@
 import assert from 'node:assert'
 
-import type { Image, Link, Root } from 'mdast'
+import type { Element } from 'hast'
+import { fromHtml } from 'hast-util-from-html'
+import type { Html, Image, Link, Root } from 'mdast'
 import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx-jsx'
 import type { MdxjsEsm } from 'mdast-util-mdxjs-esm'
 import { remark } from 'remark'
@@ -12,6 +14,7 @@ import type { VFile } from 'vfile'
 
 import {
   ensureTrailingSlash,
+  getExtension,
   isAbsoluteLink,
   stripLeadingAndTrailingSlashes,
   stripLeadingSlash,
@@ -22,12 +25,17 @@ import type { Version, VersionAsset } from './versions'
 
 const importPathRegex = /(from ?["'])([^"']*)(["'];?\s?)$/gm
 const astroAssetRegex = /\.(png|jpg|jpeg|tiff|webp|gif|svg|avif|.+\?raw)$/i
+const htmlAttributeRegex = /^(?<prefix>[^=]+=\s*(?<quote>["']?))(?<value>.*)\k<quote>$/s
+const srcsetUrlRegex = /(?<=(?:^|,)\s*)[^\s,]\S*?(?=,*(?:\s|$))/g
 
 const mediaElements = new Set(['img', 'source', 'Image', 'audio', 'video'])
 
-const processor = remark().use(remarkDirective).use(remarkMdx).use(remarkFrontmatter).use(remarkStarlightVersions)
+const markdownProcessor = remark().use(remarkDirective).use(remarkFrontmatter).use(remarkStarlightVersions)
+const mdxProcessor = markdownProcessor().use(remarkMdx)
 
 export async function transformMarkdown(markdown: string, context: TransformContext) {
+  const processor = getExtension(context.url.pathname) === '.mdx' ? mdxProcessor : markdownProcessor
+
   const file = await processor.process({
     data: { ...context },
     value: markdown,
@@ -46,17 +54,11 @@ export function remarkStarlightVersions() {
         case 'link': {
           return handleLinks(node, file)
         }
-        case 'mdxJsxTextElement': {
-          if (node.name === 'a') {
-            return handleLinkElements(node, file)
-          }
-
-          return CONTINUE
-        }
         case 'mdxjsEsm': {
           return handleImports(node, file)
         }
-        case 'mdxJsxFlowElement': {
+        case 'mdxJsxFlowElement':
+        case 'mdxJsxTextElement': {
           if (node.name === 'a') {
             return handleLinkElements(node, file)
           }
@@ -70,6 +72,9 @@ export function remarkStarlightVersions() {
         case 'image': {
           return handleImages(node, file)
         }
+        case 'html': {
+          return handleHtml(node, file)
+        }
         default: {
           return CONTINUE
         }
@@ -102,7 +107,7 @@ function handleFrontmatter(tree: Root, file: VFile) {
         if (file.data.locale && segments[0] === file.data.locale) {
           segments.splice(1, 0, file.data.version.slug)
         } else {
-          segments.splice(0, 0, file.data.version.slug)
+          segments.unshift(file.data.version.slug)
         }
 
         frontmatter.slug = segments.join('/')
@@ -144,7 +149,7 @@ function handleFrontmatter(tree: Root, file: VFile) {
 function handleLinks(node: Link, file: VFile) {
   node.url = transformLink(node.url, file)
 
-  return SKIP
+  return CONTINUE
 }
 
 function handleLinkElements(node: MdxJsxFlowElement | MdxJsxTextElement, file: VFile) {
@@ -194,18 +199,74 @@ function handleImages(node: Image, file: VFile) {
   return SKIP
 }
 
-function handleMediaElements(node: MdxJsxFlowElement, file: VFile) {
-  const srcOrSrcset = node.attributes.find(
-    (attribute) => attribute.type === 'mdxJsxAttribute' && (attribute.name === 'src' || attribute.name === 'srcset'),
-  )
+function handleMediaElements(node: MdxJsxFlowElement | MdxJsxTextElement, file: VFile) {
+  for (const attribute of node.attributes) {
+    if (attribute.type !== 'mdxJsxAttribute' || typeof attribute.value !== 'string') continue
 
-  if (!srcOrSrcset || typeof srcOrSrcset.value !== 'string' || !isPublicAsset(srcOrSrcset.value)) return CONTINUE
+    if (attribute.name === 'src' && isPublicAsset(attribute.value)) {
+      attribute.value = addVersionToPublicAsset(attribute.value, file)
+    } else if (attribute.name === 'srcset' || attribute.name === 'srcSet') {
+      attribute.value = addVersionToPublicSrcset(attribute.value, file)
+    }
+  }
 
-  srcOrSrcset.value = addVersionToPublicAsset(srcOrSrcset.value, file)
+  return CONTINUE
+}
+
+// Raw HTML nodes only exist in non-MDX files (MDX parses HTML as JSX) and are not re-serialized to preserve them as
+// authored, e.g. unclosed inline tags, and only the transformed attribute values are updated.
+function handleHtml(node: Html, file: VFile) {
+  const tree = fromHtml(node.value, { fragment: true, verbose: true })
+  // Updates are keyed by attribute offset as misnested HTML can lead the parser to recreate elements which share the
+  // source position of the original element and would be updated multiple times.
+  const updates = new Map<number, HtmlAttribute>()
+
+  visit(tree, 'element', (element) => {
+    if (element.tagName === 'a') {
+      const href = getHtmlAttribute(node.value, element, 'href')
+      if (!href || updates.has(href.start)) return
+
+      updates.set(href.start, { ...href, value: transformLink(href.value, file) })
+    } else if (mediaElements.has(element.tagName)) {
+      const src = getHtmlAttribute(node.value, element, 'src')
+
+      if (src && !updates.has(src.start) && isPublicAsset(src.value)) {
+        updates.set(src.start, { ...src, value: addVersionToPublicAsset(src.value, file) })
+      }
+
+      const srcset = getHtmlAttribute(node.value, element, 'srcSet')
+
+      if (srcset && !updates.has(srcset.start)) {
+        updates.set(srcset.start, { ...srcset, value: addVersionToPublicSrcset(srcset.value, file) })
+      }
+    }
+  })
+
+  // Update attributes from the end to keep the offsets of the previous ones valid.
+  const sortedUpdates = updates
+    .values()
+    .toArray()
+    .toSorted((a, b) => b.start - a.start)
+
+  for (const { end, start, value } of sortedUpdates) {
+    node.value = `${node.value.slice(0, start)}${value}${node.value.slice(end)}`
+  }
 
   return SKIP
 }
 
+function getHtmlAttribute(html: string, element: Element, property: string): HtmlAttribute | undefined {
+  const position = element.data?.position.properties?.[property]
+  if (position?.start.offset === undefined || position.end.offset === undefined) return
+
+  const match = htmlAttributeRegex.exec(html.slice(position.start.offset, position.end.offset))
+  if (!match?.groups?.['prefix'] || !match.groups['value']) return
+
+  const start = position.start.offset + match.groups['prefix'].length
+
+  return { end: start + match.groups['value'].length, start, value: match.groups['value'] }
+}
+
 function handleImports(node: MdxjsEsm, file: VFile) {
   node.value = node.value.replaceAll(importPathRegex, (match, start, importPath: string, end) => {
     if (!importPath.startsWith('../')) return match
@@ -232,8 +293,7 @@ function addVersionToLink(link: string, file: VFile) {
 
   const segments = link.split('/')
 
-  let slugVersionIndex = 1
-  if (file.data.locale && segments[1] === file.data.locale) slugVersionIndex = 2
+  const slugVersionIndex = file.data.locale && segments[1] === file.data.locale ? 2 : 1
 
   segments.splice(slugVersionIndex, 0, file.data.version.slug)
 
@@ -252,11 +312,11 @@ function addVersionToAstroAsset(asset: string, file: VFile) {
   if (source.href.startsWith(file.data.docsDir.href)) return asset
 
   const segments = asset.split('/')
-  segments.splice(-1, 0, file.data.version.slug)
+  segments.splice(Math.max(segments.length - 1, 0), 0, file.data.version.slug)
 
   addVersionAsset(file, { source, dest: new URL(segments.join('/'), file.data.url) })
 
-  segments.splice(0, 0, '..')
+  segments.unshift('..')
 
   return segments.join('/')
 }
@@ -267,13 +327,17 @@ function addVersionToPublicAsset(asset: string, file: VFile) {
   const source = new URL(`.${asset}`, file.data.publicDir)
 
   const segments = asset.split('/')
-  segments.splice(-1, 0, file.data.version.slug)
+  segments.splice(Math.max(segments.length - 1, 0), 0, file.data.version.slug)
 
   addVersionAsset(file, { source, dest: new URL(`.${segments.join('/')}`, file.data.publicDir) })
 
   return segments.join('/')
 }
 
+function addVersionToPublicSrcset(srcset: string, file: VFile) {
+  return srcset.replaceAll(srcsetUrlRegex, (url) => (isPublicAsset(url) ? addVersionToPublicAsset(url, file) : url))
+}
+
 function addVersionAsset(file: VFile, asset: VersionAsset) {
   file.data.assets?.push(asset)
 }
@@ -298,6 +362,12 @@ export interface TransformContext {
   version: Version
 }
 
+interface HtmlAttribute {
+  end: number
+  start: number
+  value: string
+}
+
 declare module 'vfile' {
   interface DataMap extends TransformContext {}
 }

package/libs/plugin.ts

@@ -17,7 +17,8 @@ export function overrideComponents(
 ): StarlightUserConfig['components'] {
   const components = { ...starlightConfig.components }
   for (const { name, fallback } of overrides) {
-    if (starlightConfig.components?.[name]) {
+    const override = starlightConfig.components?.[name]
+    if (override) {
       logger.warn(`A \`<${name}>\` component override is already defined in your Starlight configuration.`)
       logger.warn(
         `To use \`starlight-versions\`, either remove this override or manually render the content from \`starlight-versions/components/${fallback}.astro\`.`,

package/libs/starlight.ts

@@ -59,7 +59,7 @@ export function getURLSlug(url: URL) {
   } else if (segments.at(-1)?.endsWith(htmlExt)) {
     // Remove trailing `.html`.
     const last = segments.pop()
-    if (last) segments.push(last.slice(0, -1 * htmlExt.length))
+    if (last) segments.push(last.slice(0, -htmlExt.length))
   }
 
   return segments.filter(Boolean).join('/')
@@ -70,7 +70,7 @@ export function getDocLocale(slug: string, starlightConfig: StarlightUserConfig)
 
   if (locales.length === 0) return undefined
 
-  const localeSegment = slug.split('/')[0]
+  const localeSegment = slug.split('/', 1)[0]
 
   if (!localeSegment) return undefined
 
@@ -89,24 +89,29 @@ export function addPrefixToSidebarConfig(
   return sidebar.map((item) => {
     if (typeof item === 'string') {
       return isExcludedInternalSidebarSlug(item, excludedSlugs) ? item : addPrefixToSlug(prefix, item)
-    } else if ('items' in item) {
+    }
+    if ('items' in item) {
       return {
         ...item,
         items: addPrefixToSidebarConfig(prefix, item.items, excludedSlugs),
       }
-    } else if (isSidebarLegacyAutoGroup(item)) {
+    }
+    if (isSidebarLegacyAutoGroup(item)) {
       return addPrefixToLegacyAutogeneratedGroup(prefix, item)
-    } else if ('autogenerate' in item) {
+    }
+    if ('autogenerate' in item) {
       return {
         ...item,
         autogenerate: addPrefixToAutogenerate(prefix, item.autogenerate),
       }
-    } else if ('slug' in item) {
+    }
+    if ('slug' in item) {
       return {
         ...item,
         slug: isExcludedInternalSidebarSlug(item.slug, excludedSlugs) ? item.slug : addPrefixToSlug(prefix, item.slug),
       }
-    } else if (isAbsoluteLink(item.link)) {
+    }
+    if (isAbsoluteLink(item.link)) {
       return item
     }
 

package/libs/versions.ts

@@ -82,16 +82,17 @@ export async function ensureNewVersion(
 ) {
   const docsDir = new URL('content/docs/', astroConfig.srcDir)
   const newVersion = await checkForNewVersion(config, docsDir)
-  const locales = Object.keys(starlightConfig.locales ?? {})
 
   if (!newVersion) return
 
+  const locales = Object.keys(starlightConfig.locales ?? {})
+
   const excludedDocs = await getExcludedDocs(
     config,
     locales.filter((locale) => locale !== 'root'),
     docsDir,
   )
-  const excludedSlugs = [...excludedDocs.values()].toSorted()
+  const excludedSlugs = excludedDocs.values().toArray().toSorted()
 
   const assets: VersionAsset[] = []
 
@@ -112,7 +113,7 @@ export async function ensureNewVersion(
       }
 
       // Skip root version directories.
-      if (entry.name in config.versionsBySlug) return true
+      if (Object.hasOwn(config.versionsBySlug, entry.name)) return true
 
       const localeDir = locales.find((locale) => locale === entry.name)
 
@@ -213,12 +214,8 @@ export function getVersionURL(
   const canonicalSlug = getCanonicalSlug(config, starlightConfig, url)
 
   if (version && isSlugExcludedFromVersion(config, version, canonicalSlug)) {
-    return getVersionURL(
-      { ...config, current: { ...config.current, redirect: 'same-page' } },
-      starlightConfig,
-      url,
-      undefined,
-    )
+    config = { ...config, current: { ...config.current, redirect: 'same-page' } }
+    version = undefined
   }
 
   const versionURL = new URL(url)
@@ -236,7 +233,7 @@ export function getVersionURL(
   let localeSegment: string | undefined
 
   const isHTML = getExtension(versionURL.pathname) === '.html'
-  const [, firstSegment, secondSegment] = versionURL.pathname.split('/')
+  const [, firstSegment, secondSegment] = versionURL.pathname.split('/', 3)
 
   if (starlightConfig.isMultilingual || starlightConfig.locales) {
     const versionOrLocale = firstSegment?.replace('.html', '')
@@ -254,11 +251,11 @@ export function getVersionURL(
   const isRootHTML = baseSegment && getExtension(baseSegment) === '.html'
   const baseSlug = baseSegment && isRootHTML ? stripExtension(baseSegment) : baseSegment
 
-  if (baseSlug && baseSlug in config.versionsBySlug) {
+  if (baseSlug && Object.hasOwn(config.versionsBySlug, baseSlug)) {
     if (versionSlug) {
       versionURL.pathname =
         versionRedirect === 'same-page'
-          ? versionURL.pathname.replace(baseSlug, versionSlug)
+          ? versionURL.pathname.replace(baseSlug, () => versionSlug)
           : `${versionSlug}${isHTML ? '.html' : '/'}`
     } else if (isRootHTML) {
       versionURL.pathname = '/index.html'
@@ -458,7 +455,7 @@ export function getVersionFromPaginationLink(
 
   if (locale) {
     // Remove the locale segment if the current locale is not a root locale.
-    segments.splice(0, 1)
+    segments.shift()
   }
 
   const versionSegment = segments[0]
@@ -488,11 +485,14 @@ async function getExcludedDocs(config: StarlightVersionsConfig, locales: string[
       const docPath = getDocPath(docsDir, entryURL)
 
       if (isDirectory) {
-        const [firstSegment, secondSegment] = docPath.split('/')
+        const [firstSegment, secondSegment] = docPath.split('/', 2)
 
         if (
-          (firstSegment && firstSegment in config.versionsBySlug) ||
-          (firstSegment && locales.includes(firstSegment) && secondSegment && secondSegment in config.versionsBySlug)
+          (firstSegment && Object.hasOwn(config.versionsBySlug, firstSegment)) ||
+          (firstSegment &&
+            secondSegment &&
+            locales.includes(firstSegment) &&
+            Object.hasOwn(config.versionsBySlug, secondSegment))
         ) {
           continue
         }
@@ -505,7 +505,7 @@ async function getExcludedDocs(config: StarlightVersionsConfig, locales: string[
       if (
         !entry.isFile() ||
         !docsExtensions.has(getExtension(docPath)) ||
-        !config.exclude.some((excludeGlob) => path.posix.matchesGlob(docPath, excludeGlob))
+        config.exclude.every((excludeGlob) => !path.posix.matchesGlob(docPath, excludeGlob))
       ) {
         continue
       }
@@ -532,12 +532,15 @@ async function checkForNewVersion(config: StarlightVersionsConfig, docsDir: URL)
   }
 
   for (const version of config.versions) {
-    if (!docsDirDirectories.has(version.slug)) {
-      if (newVersion) {
-        throw new Error('Only one new version can be configured at a time.')
-      }
-      newVersion = version
+    if (docsDirDirectories.has(version.slug)) {
+      continue
+    }
+
+    if (newVersion) {
+      throw new Error('Only one new version can be configured at a time.')
     }
+
+    newVersion = version
   }
 
   return newVersion

package/middleware.ts

@@ -74,7 +74,7 @@ function getPaginationFromSidebar(
     route.pagination.prev,
   )
   const next = applyPaginationConfig(
-    currentIndex > -1 ? entries[currentIndex + 1] : undefined,
+    currentIndex === -1 ? undefined : entries[currentIndex + 1],
     starlightConfig.pagination,
     route.entry.data.next,
     route.pagination.next,
@@ -93,11 +93,12 @@ function applyPaginationConfig(
   // Explicitly remove the link.
   if (config === false) return undefined
   // Use the generated link if any.
-  else if (config === true) return link
+  if (config === true) return link
   // If a link exists, update its label if needed.
-  else if (typeof config === 'string' && link) {
+  if (typeof config === 'string' && link) {
     return { ...link, label: config }
-  } else if (typeof config === 'object') {
+  }
+  if (typeof config === 'object') {
     if (link) {
       // If a link exists, update both its label and href if needed.
       return {
@@ -107,7 +108,8 @@ function applyPaginationConfig(
         // Explicitly remove sidebar link attributes for prev/next links.
         attrs: {},
       }
-    } else if (config.link && config.label) {
+    }
+    if (config.link && config.label) {
       // If there is no link and the frontmatter contains both a URL and a label, use it.
       return existing
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-versions",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "license": "MIT",
   "description": "Starlight plugin to version documentation pages.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",
@@ -22,6 +22,7 @@
   "dependencies": {
     "@pagefind/default-ui": "^1.3.0",
     "github-slugger": "^2.0.0",
+    "hast-util-from-html": "^2.0.3",
     "mdast-util-mdx-jsx": "^3.2.0",
     "mdast-util-mdxjs-esm": "^2.0.1",
     "remark": "^15.0.1",
@@ -33,6 +34,7 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
+    "@types/hast": "^3.0.4",
     "@types/mdast": "^4.0.4",
     "fast-glob": "^3.3.3",
     "vitest": "^4.0.18"
@@ -40,9 +42,6 @@
   "peerDependencies": {
     "@astrojs/starlight": ">=0.39.0"
   },
-  "engines": {
-    "node": ">=22.12.0"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -64,6 +63,6 @@
   "bugs": "https://github.com/HiDeoo/starlight-versions/issues",
   "scripts": {
     "test": "vitest",
-    "lint": "eslint . --cache --max-warnings=0"
+    "lint": "eslint . --max-warnings=0"
   }
 }