starlight-versions 0.9.1 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # starlight-versions
 
+## 0.10.1
+
+### Patch Changes
+
+- [#80](https://github.com/HiDeoo/starlight-versions/pull/80) [`dd385c8`](https://github.com/HiDeoo/starlight-versions/commit/dd385c88940cc36e5733d0f082a04907f44bb2f0) Thanks [@kozmagabor](https://github.com/kozmagabor)! - Fixes versioning of assets stored alongside documentation pages.
+
+## 0.10.0
+
+### Minor Changes
+
+- [#76](https://github.com/HiDeoo/starlight-versions/pull/76) [`a4134e7`](https://github.com/HiDeoo/starlight-versions/commit/a4134e7ac0df8778367f4ada77c3b5ee8976cc06) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for excluding pages from versioning.
+
+### Patch Changes
+
+- [#79](https://github.com/HiDeoo/starlight-versions/pull/79) [`4329441`](https://github.com/HiDeoo/starlight-versions/commit/4329441a853506584a2e9c43429b83a14a5152a6) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes pagination links when using Astro's `base` configuration option with multiple segments.
+
+- [#79](https://github.com/HiDeoo/starlight-versions/pull/79) [`4329441`](https://github.com/HiDeoo/starlight-versions/commit/4329441a853506584a2e9c43429b83a14a5152a6) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes invalid versioned links for paths similar to Astro's `base` configuration option.
+
 ## 0.9.1
 
 ### Patch Changes

package/components/VersionSearch.astro

@@ -10,7 +10,7 @@ import project from 'virtual:starlight/project-context'
 import starlightConfig from 'virtual:starlight/user-config'
 import starlightVersionsConfig from 'virtual:starlight-versions-config'
 
-import { getVersionFromSlug, getVersionIdentifier, getVersionURL } from '../libs/versions'
+import { getPagefindVersionIdentifiers, getVersionFromSlug, getVersionURL } from '../libs/versions'
 
 const { entry } = Astro.locals.starlightRoute
 
@@ -24,7 +24,11 @@ const pagefindTranslations = {
 }
 
 const pageVersion = getVersionFromSlug(starlightVersionsConfig, starlightConfig, entry.id)
-const pageVersionIdentifier = getVersionIdentifier(pageVersion)
+const [pageVersionIdentifier, ...otherPageVersionsIdentifiers] = getPagefindVersionIdentifiers(
+  starlightVersionsConfig,
+  pageVersion,
+  entry.id,
+)
 
 const dataAttributes: DOMStringMap = {
   'data-pagefind-filter': `version:${pageVersionIdentifier}`,
@@ -35,6 +39,7 @@ if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash
 ---
 
 <site-search class={Astro.props['class']} {...dataAttributes}>
+  {otherPageVersionsIdentifiers.map((version) => <span hidden data-pagefind-filter={`version:${version}`} />)}
   <button data-open-modal disabled aria-label={Astro.locals.t('search.label')} aria-keyshortcuts="Control+K">
     <Icon name="magnifier" />
     <span class="sl-hidden md:sl-block" aria-hidden="true">{Astro.locals.t('search.label')}</span>

package/components/VersionSelect.astro

@@ -3,37 +3,41 @@ import { Icon } from '@astrojs/starlight/components'
 import starlightConfig from 'virtual:starlight/user-config'
 import starlightVersionsConfig from 'virtual:starlight-versions-config'
 
-import { getVersionFromSlug, getVersionURL } from '../libs/versions'
+import { getVersionFromSlug, getVersionURL, isExcludedDocPath } from '../libs/versions'
 
-const { id } = Astro.locals.starlightRoute
+const { entry, id } = Astro.locals.starlightRoute
 
 const pageVersion = getVersionFromSlug(starlightVersionsConfig, starlightConfig, id)
+const isExcluded = pageVersion === undefined && isExcludedDocPath(starlightVersionsConfig, entry.filePath)
 ---
 
-<starlight-version-select>
-  <label>
-    <span class="sr-only">{Astro.locals.t('starlightVersions.select.accessibleLabel')}</span>
-    <Icon name="seti:clock" class="icon label-icon" />
-    <select value={pageVersion?.label ?? 'current'} autocomplete="off">
-      <option
-        selected={pageVersion === undefined}
-        value={getVersionURL(starlightVersionsConfig, starlightConfig, Astro.url, undefined).pathname}
-        >{starlightVersionsConfig.current.label}</option
-      >
-      {
-        starlightVersionsConfig.versions.map((version) => (
+{
+  !isExcluded && (
+    <starlight-version-select>
+      <label>
+        <span class="sr-only">{Astro.locals.t('starlightVersions.select.accessibleLabel')}</span>
+        <Icon name="seti:clock" class="icon label-icon" />
+        <select value={pageVersion?.label ?? 'current'} autocomplete="off">
           <option
-            selected={version.slug === pageVersion?.slug}
-            value={getVersionURL(starlightVersionsConfig, starlightConfig, Astro.url, version).pathname}
+            selected={pageVersion === undefined}
+            value={getVersionURL(starlightVersionsConfig, starlightConfig, Astro.url, undefined).pathname}
           >
-            {version.label ?? version.slug}
+            {starlightVersionsConfig.current.label}
           </option>
-        ))
-      }
-    </select>
-    <Icon name="down-caret" class="icon caret-icon" />
-  </label>
-</starlight-version-select>
+          {starlightVersionsConfig.versions.map((version) => (
+            <option
+              selected={version.slug === pageVersion?.slug}
+              value={getVersionURL(starlightVersionsConfig, starlightConfig, Astro.url, version).pathname}
+            >
+              {version.label ?? version.slug}
+            </option>
+          ))}
+        </select>
+        <Icon name="down-caret" class="icon caret-icon" />
+      </label>
+    </starlight-version-select>
+  )
+}
 
 <style>
   label {

package/libs/config.ts

@@ -18,6 +18,14 @@ export const StarlightVersionsConfigSchema = z
         label: z.string().default('Latest'),
       })
       .prefault({}),
+    /**
+     * A list of source file glob patterns that should be excluded from versioning.
+     *
+     * Excluded pages always use the latest content across all versions.
+     *
+     * @default []
+     */
+    exclude: z.array(z.string()).default([]),
     /**
      * A list of all archived versions of the documentation.
      */
@@ -25,10 +33,16 @@ export const StarlightVersionsConfigSchema = z
       message: 'At least one version of the documentation must be defined.',
     }),
   })
-  .transform((value) => ({
-    ...value,
-    versionsBySlug: Object.fromEntries(value.versions.map((version) => [version.slug, version])),
-  }))
+  .transform((value) => {
+    // This gets populated later when generating versioned sidebars.
+    const excludedSlugsByVersion: Record<string, string[]> = {}
+
+    return {
+      ...value,
+      excludedSlugsByVersion,
+      versionsBySlug: Object.fromEntries(value.versions.map((version) => [version.slug, version])),
+    }
+  })
 
 export type StarlightVersionsUserConfig = z.input<typeof StarlightVersionsConfigSchema>
 export type StarlightVersionsConfig = z.output<typeof StarlightVersionsConfigSchema>

package/libs/fs.ts

@@ -32,13 +32,17 @@ export async function copyDirectory(sourceDir: URL, destDir: URL, callback: Copy
       await copyDirectory(source, dest, callback, false)
     } else if (entry.isFile()) {
       const source = new URL(entry.name, sourceDir)
-      const content = await fs.readFile(source, 'utf8')
 
-      const updatedContent = await callback({ type: 'file', content, url: source })
+      const updatedContent = await callback({ type: 'file', url: source })
+      if (updatedContent === true) continue
 
-      if (typeof updatedContent !== 'string') continue
+      const dest = new URL(entry.name, destDir)
 
-      await fs.writeFile(new URL(entry.name, destDir), updatedContent)
+      if (updatedContent === undefined) {
+        await copyFile(source, dest)
+      } else if (typeof updatedContent === 'string') {
+        await fs.writeFile(dest, updatedContent)
+      }
     }
   }
 }
@@ -72,8 +76,12 @@ export async function isDirectoryEntry(entry: Dirent) {
   return stats.isDirectory()
 }
 
+/**
+ * Defines how entries are handled when copying a directory with `copyDirectory()`.
+ *
+ * - For files, return `undefined` to copy as-is, a string to write transformed content, or `true` to skip.
+ * - For directories, return `undefined` to use the default destination, a `URL` to override it, or `true` to skip.
+ */
 export type CopyDirectoryCallback = (
-  entry:
-    | { type: 'file'; content: string; url: URL }
-    | { type: 'directory'; name: string; isRoot: boolean; source: URL; dest: URL },
-) => Promise<string | boolean | URL>
+  entry: { type: 'file'; url: URL } | { type: 'directory'; name: string; isRoot: boolean; source: URL; dest: URL },
+) => Promise<string | true | URL | undefined>

package/libs/markdown.ts

@@ -10,7 +10,13 @@ import remarkMdx from 'remark-mdx'
 import { CONTINUE, SKIP, visit } from 'unist-util-visit'
 import type { VFile } from 'vfile'
 
-import { isAbsoluteLink, stripLeadingSlash, stripTrailingSlash } from './path'
+import {
+  ensureTrailingSlash,
+  isAbsoluteLink,
+  stripLeadingAndTrailingSlashes,
+  stripLeadingSlash,
+  stripTrailingSlash,
+} from './path'
 import { getFrontmatterNodeValue, parseFrontmatter } from './starlight'
 import type { Version, VersionAsset } from './versions'
 
@@ -51,6 +57,10 @@ export function remarkStarlightVersions() {
           return handleImports(node, file)
         }
         case 'mdxJsxFlowElement': {
+          if (node.name === 'a') {
+            return handleLinkElements(node, file)
+          }
+
           if (node.name && mediaElements.has(node.name)) {
             return handleMediaElements(node, file)
           }
@@ -99,19 +109,17 @@ function handleFrontmatter(tree: Root, file: VFile) {
       }
     }
 
-    if (typeof frontmatter.prev === 'object' && frontmatter.prev.link?.startsWith('/')) {
-      frontmatter.prev.link = addVersionToLink(frontmatter.prev.link, file)
+    if (typeof frontmatter.prev === 'object' && frontmatter.prev.link) {
+      frontmatter.prev.link = transformLink(frontmatter.prev.link, file)
     }
 
-    if (typeof frontmatter.next === 'object' && frontmatter.next.link?.startsWith('/')) {
-      frontmatter.next.link = addVersionToLink(frontmatter.next.link, file)
+    if (typeof frontmatter.next === 'object' && frontmatter.next.link) {
+      frontmatter.next.link = transformLink(frontmatter.next.link, file)
     }
 
     if (frontmatter.hero?.actions) {
       for (const action of frontmatter.hero.actions) {
-        if (action.link.startsWith('/')) {
-          action.link = addVersionToLink(action.link, file)
-        }
+        action.link = transformLink(action.link, file)
       }
     }
 
@@ -134,23 +142,50 @@ function handleFrontmatter(tree: Root, file: VFile) {
 }
 
 function handleLinks(node: Link, file: VFile) {
-  if (!isPublicAsset(node.url)) return SKIP
-
-  node.url = addVersionToLink(node.url, file)
+  node.url = transformLink(node.url, file)
 
   return SKIP
 }
 
-function handleLinkElements(node: MdxJsxTextElement, file: VFile) {
+function handleLinkElements(node: MdxJsxFlowElement | MdxJsxTextElement, file: VFile) {
   const href = node.attributes.find((attribute) => attribute.type === 'mdxJsxAttribute' && attribute.name === 'href')
 
-  if (!href || typeof href.value !== 'string' || !isPublicAsset(href.value)) return CONTINUE
+  if (!href || typeof href.value !== 'string') return CONTINUE
 
-  href.value = addVersionToLink(href.value, file)
+  href.value = transformLink(href.value, file)
 
   return CONTINUE
 }
 
+function transformLink(link: string, file: VFile) {
+  if (isAbsoluteLink(link)) return link
+
+  const excludedLink = getExcludedLink(link, file)
+  if (excludedLink) return excludedLink
+
+  return isPublicAsset(link) ? addVersionToLink(link, file) : link
+}
+
+function getExcludedLink(link: string, file: VFile) {
+  const { excludedSlugs, slug } = file.data
+
+  if (!excludedSlugs || !slug || link.startsWith('#') || link.startsWith('?')) return undefined
+
+  const isAbsolute = link.startsWith('/')
+  const url = new URL(link, `https://example.com/${stripLeadingAndTrailingSlashes(slug)}/`)
+  let pathname = url.pathname
+  const base = file.data.base ?? ''
+
+  if (base && (pathname === base || pathname.startsWith(ensureTrailingSlash(base)))) {
+    pathname = pathname.slice(base.length)
+  }
+
+  if (!excludedSlugs.includes(stripLeadingAndTrailingSlashes(pathname))) return undefined
+  if (isAbsolute) return link
+
+  return `${base}${pathname}${url.search}${url.hash}`
+}
+
 function handleImages(node: Image, file: VFile) {
   if (isAbsoluteLink(node.url)) return SKIP
 
@@ -189,10 +224,10 @@ function addVersionToLink(link: string, file: VFile) {
   assert.ok(file.data.version, 'A version must be provided to add a version to an Astro asset.')
 
   const base = file.data.base ?? ''
-  const hasBase = file.data.base && link.startsWith(file.data.base)
+  const hasBase = base && (link === base || link.startsWith(ensureTrailingSlash(base)))
 
   if (hasBase) {
-    link = link.replace(base, '')
+    link = link.slice(base.length)
   }
 
   const segments = link.split('/')
@@ -211,8 +246,10 @@ function addVersionToLink(link: string, file: VFile) {
 
 function addVersionToAstroAsset(asset: string, file: VFile) {
   assert.ok(file.data.version, 'A version must be provided to add a version to an Astro asset.')
+  assert.ok(file.data.docsDir, 'A docs directory must be provided to add a version to an Astro asset.')
 
   const source = new URL(asset, file.data.url)
+  if (source.href.startsWith(file.data.docsDir.href)) return asset
 
   const segments = asset.split('/')
   segments.splice(-1, 0, file.data.version.slug)
@@ -252,6 +289,8 @@ function isPublicAsset(asset: string) {
 export interface TransformContext {
   assets: VersionAsset[]
   base: string
+  docsDir: URL
+  excludedSlugs: string[]
   locale: string | undefined
   publicDir: URL
   slug: string

package/libs/path.ts

@@ -2,7 +2,7 @@ import path from 'node:path'
 
 import { slug } from 'github-slugger'
 
-const absoluteLinkRegex = /^https?:\/\//
+const absoluteLinkRegex = /^[a-z][a-z\d+.-]*:/i
 
 export function ensureTrailingSlash(filePath: string): string {
   if (filePath.endsWith('/')) {
@@ -28,6 +28,10 @@ export function stripTrailingSlash(filePath: string) {
   return filePath.slice(0, -1)
 }
 
+export function stripLeadingAndTrailingSlashes(filePath: string) {
+  return stripLeadingSlash(stripTrailingSlash(filePath))
+}
+
 export function slugifyPath(filePath: string): string {
   const segments = stripExtension(filePath).split('/')
 

package/libs/starlight.ts

@@ -7,7 +7,16 @@ import type { HookParameters } from '@astrojs/starlight/types'
 import type { z } from 'astro/zod'
 import yaml from 'yaml'
 
-import { isAbsoluteLink, slugifyPath } from './path'
+import {
+  ensureTrailingSlash,
+  isAbsoluteLink,
+  slugifyPath,
+  stripLeadingAndTrailingSlashes,
+  stripTrailingSlash,
+} from './path'
+
+const frontmatterRegex = /^---\r?\n(?<yaml>.*?)\r?\n---(?:\r?\n|$)/s
+const queryOrFragmentRegex = /[?#]/
 
 export function parseFrontmatter(frontmatter: string) {
   return yaml.parse(frontmatter) as StarlightFrontmatter
@@ -17,13 +26,45 @@ export function getFrontmatterNodeValue(frontmatter: StarlightFrontmatter) {
   return yaml.stringify(frontmatter).trim()
 }
 
+export function getDocPath(docsDir: URL, doc: URL) {
+  return path.relative(url.fileURLToPath(docsDir), url.fileURLToPath(doc)).replaceAll('\\', '/')
+}
+
 export function getDocSlug(docsDir: URL, doc: URL) {
-  const docPath = path.relative(url.fileURLToPath(docsDir), url.fileURLToPath(doc)).replaceAll('\\', '/')
-  const slug = slugifyPath(docPath)
+  const slug = slugifyPath(getDocPath(docsDir, doc))
 
   return slug === 'index' ? '/' : slug.replace(/\/index$/, '')
 }
 
+export function resolveDocSlug(docsDir: URL, doc: URL, content: string) {
+  const frontmatter = frontmatterRegex.exec(content)?.groups?.['yaml']
+  const customSlug = frontmatter ? parseFrontmatter(frontmatter).slug : undefined
+
+  return stripLeadingAndTrailingSlashes(typeof customSlug === 'string' ? customSlug : getDocSlug(docsDir, doc))
+}
+
+// https://github.com/withastro/starlight/blob/ff5090a8fd7ae068b29e3c5af7197c5e5afdfa4e/packages/starlight/utils/slugs.ts#L104
+export function getURLSlug(url: URL) {
+  let pathname = decodeURI(url.pathname)
+
+  const base = stripTrailingSlash(import.meta.env.BASE_URL)
+  if (pathname === base || pathname.startsWith(ensureTrailingSlash(base))) pathname = pathname.slice(base.length)
+
+  const segments = pathname.split('/')
+  const htmlExt = '.html'
+
+  if (segments.at(-1) === 'index.html') {
+    // Remove trailing `index.html`.
+    segments.pop()
+  } else if (segments.at(-1)?.endsWith(htmlExt)) {
+    // Remove trailing `.html`.
+    const last = segments.pop()
+    if (last) segments.push(last.slice(0, -1 * htmlExt.length))
+  }
+
+  return segments.filter(Boolean).join('/')
+}
+
 export function getDocLocale(slug: string, starlightConfig: StarlightUserConfig): string | undefined {
   const locales = Object.keys(starlightConfig.locales ?? {})
 
@@ -36,14 +77,22 @@ export function getDocLocale(slug: string, starlightConfig: StarlightUserConfig)
   return locales.find((locale) => locale === localeSegment)
 }
 
-export function addPrefixToSidebarConfig(prefix: string, sidebar: SidebarConfigInputItem[]): SidebarConfig {
+export function getSidebarLinks(sidebar: StarlightSidebar): Extract<StarlightSidebar[number], { type: 'link' }>[] {
+  return sidebar.flatMap((entry) => (entry.type === 'group' ? getSidebarLinks(entry.entries) : entry))
+}
+
+export function addPrefixToSidebarConfig(
+  prefix: string,
+  sidebar: SidebarConfigInputItem[],
+  excludedSlugs: string[] = [],
+): SidebarConfig {
   return sidebar.map((item) => {
     if (typeof item === 'string') {
-      return addPrefixToSlug(prefix, item)
+      return isExcludedInternalSidebarSlug(item, excludedSlugs) ? item : addPrefixToSlug(prefix, item)
     } else if ('items' in item) {
       return {
         ...item,
-        items: addPrefixToSidebarConfig(prefix, item.items),
+        items: addPrefixToSidebarConfig(prefix, item.items, excludedSlugs),
       }
     } else if (isSidebarLegacyAutoGroup(item)) {
       return addPrefixToLegacyAutogeneratedGroup(prefix, item)
@@ -55,12 +104,15 @@ export function addPrefixToSidebarConfig(prefix: string, sidebar: SidebarConfigI
     } else if ('slug' in item) {
       return {
         ...item,
-        slug: addPrefixToSlug(prefix, item.slug),
+        slug: isExcludedInternalSidebarSlug(item.slug, excludedSlugs) ? item.slug : addPrefixToSlug(prefix, item.slug),
       }
     } else if (isAbsoluteLink(item.link)) {
       return item
     }
 
+    const link = item.link.startsWith('./') ? item.link.slice(2) : item.link
+    if (isExcludedSidebarSlug(link, excludedSlugs)) return item
+
     const segments = item.link.split('/')
     segments.splice(/^[./]/.test(item.link) ? 1 : 0, 0, prefix)
 
@@ -71,6 +123,16 @@ export function addPrefixToSidebarConfig(prefix: string, sidebar: SidebarConfigI
   })
 }
 
+function isExcludedSidebarSlug(value: string, excludedSlugs: string[]) {
+  const pathname = value.split(queryOrFragmentRegex)[0] ?? ''
+  const slug = stripLeadingAndTrailingSlashes(pathname)
+  return excludedSlugs.includes(slug)
+}
+
+function isExcludedInternalSidebarSlug(slug: string, excludedSlugs: string[]) {
+  return isExcludedSidebarSlug(slug === 'index' ? '' : slug, excludedSlugs)
+}
+
 function isSidebarLegacyAutoGroup(item: SidebarConfigInputItem): item is SidebarLegacyAutoGroup {
   return typeof item === 'object' && 'autogenerate' in item && 'label' in item
 }

package/libs/versions.ts

@@ -1,9 +1,12 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
 import type { StarlightConfig } from '@astrojs/starlight/types'
 import type { AstroConfig, AstroIntegrationLogger } from 'astro'
 import { z } from 'astro/zod'
 
 import type { StarlightVersionsConfig } from '..'
-import type { DocsVersionsConfig } from '../schema'
+import { docsVersionsSchema, type DocsVersionsConfig } from '../schema'
 
 import {
   copyDirectory,
@@ -15,10 +18,19 @@ import {
   writeJSONFile,
 } from './fs'
 import { transformMarkdown } from './markdown'
-import { ensureTrailingSlash, getExtension, stripExtension, stripLeadingSlash, stripTrailingSlash } from './path'
+import {
+  ensureTrailingSlash,
+  getExtension,
+  stripExtension,
+  stripLeadingAndTrailingSlashes,
+  stripTrailingSlash,
+} from './path'
 import { throwPluginError } from './plugin'
 import {
   getDocSlug,
+  getDocPath,
+  getURLSlug,
+  resolveDocSlug,
   type StarlightSidebarUserConfig,
   type StarlightUserConfig,
   addPrefixToSidebarConfig,
@@ -28,6 +40,9 @@ import {
 
 const currentVersionSidebarGroupLabel = Symbol('StarlightVersionsCurrentVersionSidebarGroupLabel')
 
+// https://github.com/withastro/starlight/blob/23207221169b31e0cc210451a39a19c80fa1f69e/packages/starlight/loaders.ts#L6
+const docsExtensions = new Set(['.markdown', '.mdown', '.mkdn', '.mkd', '.mdwn', '.md', '.mdx'])
+
 export const VersionBaseSchema = z.object({
   /**
    * The version redirect strategy used when navigating to this version:
@@ -56,7 +71,7 @@ export const VersionSchema = z.object({
    * @example '2.0'
    * @example '3-1-2'
    */
-  slug: z.string().refine((value) => stripLeadingSlash(stripTrailingSlash(value))),
+  slug: z.string().refine((value) => stripLeadingAndTrailingSlashes(value)),
 })
 
 export async function ensureNewVersion(
@@ -71,6 +86,13 @@ export async function ensureNewVersion(
 
   if (!newVersion) return
 
+  const excludedDocs = await getExcludedDocs(
+    config,
+    locales.filter((locale) => locale !== 'root'),
+    docsDir,
+  )
+  const excludedSlugs = [...excludedDocs.values()].toSorted()
+
   const assets: VersionAsset[] = []
 
   await copyDirectory(docsDir, new URL(ensureTrailingSlash(newVersion.slug), docsDir), async (entry) => {
@@ -86,7 +108,7 @@ export async function ensureNewVersion(
         }
 
         // Do not skip other non-root directories.
-        return false
+        return
       }
 
       // Skip root version directories.
@@ -95,17 +117,22 @@ export async function ensureNewVersion(
       const localeDir = locales.find((locale) => locale === entry.name)
 
       // Copy root directories not matching any locale.
-      if (!localeDir) return false
+      if (!localeDir) return
 
       // Otherwise, swap the locale and version directories.
       return new URL(`../../${localeDir}/${newVersion.slug}/`, entry.dest)
     }
 
+    if (!docsExtensions.has(getExtension(entry.url.pathname))) return
+    if (excludedDocs.has(getDocPath(docsDir, entry.url))) return true
+
     const slug = getDocSlug(docsDir, entry.url)
 
-    const md = await transformMarkdown(entry.content, {
+    const md = await transformMarkdown(await fs.readFile(entry.url, 'utf8'), {
       assets: [],
       base: stripTrailingSlash(astroConfig.base),
+      docsDir,
+      excludedSlugs,
       locale: getDocLocale(slug, starlightConfig),
       publicDir: astroConfig.publicDir,
       slug,
@@ -122,7 +149,7 @@ export async function ensureNewVersion(
     await copyFile(asset.source, asset.dest)
   }
 
-  await makeVersionConfig(newVersion, starlightConfig, astroConfig.srcDir)
+  await makeVersionConfig(newVersion, starlightConfig, astroConfig.srcDir, excludedSlugs)
 
   logger.info(`Created new version '${newVersion.slug}'.`)
 }
@@ -139,11 +166,24 @@ export async function getVersionedSidebar(
     },
   ]
 
+  const excludedSlugsByVersion: Record<string, string[]> = {}
+
   for (const version of config.versions) {
-    const versionSidebar = await getSidebarVersionGroup(version, srcDir)
-    sidebar.push(versionSidebar)
+    const versionConfig = await getVersionConfig(version, srcDir)
+    const excludedSlugs = versionConfig.excluded
+
+    excludedSlugsByVersion[version.slug] = excludedSlugs
+
+    sidebar.push({
+      label: version.slug,
+      items: versionConfig.sidebar
+        ? addPrefixToSidebarConfig(version.slug, versionConfig.sidebar, excludedSlugs)
+        : [{ autogenerate: { directory: version.slug } }],
+    })
   }
 
+  config.excludedSlugsByVersion = excludedSlugsByVersion
+
   return sidebar
 }
 
@@ -170,15 +210,26 @@ export function getVersionURL(
   url: URL,
   version: Version | undefined,
 ): URL {
+  const canonicalSlug = getCanonicalSlug(config, starlightConfig, url)
+
+  if (version && isSlugExcludedFromVersion(config, version, canonicalSlug)) {
+    return getVersionURL(
+      { ...config, current: { ...config.current, redirect: 'same-page' } },
+      starlightConfig,
+      url,
+      undefined,
+    )
+  }
+
   const versionURL = new URL(url)
   const versionSlug = version?.slug ?? ''
   const versionRedirect = version?.redirect ?? config.current.redirect
 
   const base = stripTrailingSlash(import.meta.env.BASE_URL)
-  const hasBase = versionURL.pathname.startsWith(base)
+  const hasBase = versionURL.pathname === base || versionURL.pathname.startsWith(ensureTrailingSlash(base))
 
   if (hasBase) {
-    versionURL.pathname = versionURL.pathname.replace(base, '')
+    versionURL.pathname = versionURL.pathname.slice(base.length)
   }
 
   let baseSegment: string | undefined
@@ -243,6 +294,42 @@ export function getVersionURL(
   return versionURL
 }
 
+export function getCanonicalSlug(config: StarlightVersionsConfig, starlightConfig: StarlightConfig, url: URL) {
+  const slug = getURLSlug(url)
+  const version = getVersionFromSlug(config, starlightConfig, slug)
+  return version ? stripVersionSegment(slug, version.slug) : slug
+}
+
+export function isSlugExcludedFromVersion(config: StarlightVersionsConfig, version: Version | undefined, slug: string) {
+  return version ? (config.excludedSlugsByVersion[version.slug]?.includes(slug) ?? false) : false
+}
+
+export function isExcludedDocPath(config: StarlightVersionsConfig, filePath: string) {
+  const normalizedPath = filePath.replaceAll('\\', '/')
+  const docsRoot = 'content/docs/'
+  const docsRootIndex = normalizedPath.indexOf(docsRoot)
+  if (docsRootIndex === -1) return false
+
+  const docsPath = normalizedPath.slice(docsRootIndex + docsRoot.length)
+
+  return config.exclude.some((excludeGlob) => path.posix.matchesGlob(docsPath, excludeGlob))
+}
+
+export function getPagefindVersionIdentifiers(
+  config: StarlightVersionsConfig,
+  version: Version | undefined,
+  slug: string,
+): [string, ...string[]] {
+  if (version) return [version.slug]
+
+  return [
+    'current',
+    ...config.versions
+      .filter((archivedVersion) => isSlugExcludedFromVersion(config, archivedVersion, slug))
+      .map((archivedVersion) => archivedVersion.slug),
+  ]
+}
+
 // An undefined version is valid and represents the current version.
 export function getVersionFromSlug(
   config: StarlightVersionsConfig,
@@ -268,8 +355,95 @@ export function getVersionFromSlug(
   return config.versions.find((version) => version.slug === versionSegment)
 }
 
-export function getVersionIdentifier(version: Version | undefined): string {
-  return version?.slug ?? 'current'
+export function addExcludedLinksToVersionSidebar(
+  currentSidebar: StarlightSidebar,
+  archivedSidebar: StarlightSidebar,
+  version: Version,
+  excludedSlugs: string[],
+  baseURL: URL,
+) {
+  addExcludedLinksToVersionSidebarEntries(currentSidebar, archivedSidebar, version.slug, excludedSlugs, baseURL)
+
+  return archivedSidebar
+}
+
+function addExcludedLinksToVersionSidebarEntries(
+  currentSidebar: StarlightSidebar,
+  archivedSidebar: StarlightSidebar,
+  version: string,
+  excludedSlugs: string[],
+  baseURL: URL,
+) {
+  let cursor = 0
+
+  for (const entry of currentSidebar) {
+    const archivedIndex = archivedSidebar.findIndex(
+      (candidate, index) => index >= cursor && isMatchingSidebarEntry(entry, candidate, version, baseURL),
+    )
+
+    if (archivedIndex !== -1) {
+      const archivedEntry = archivedSidebar[archivedIndex]
+
+      if (entry.type === 'group' && archivedEntry?.type === 'group') {
+        addExcludedLinksToVersionSidebarEntries(entry.entries, archivedEntry.entries, version, excludedSlugs, baseURL)
+      }
+
+      cursor = archivedIndex + 1
+      continue
+    }
+
+    const clone = cloneExcludedSidebarEntry(entry, excludedSlugs, baseURL)
+    if (!clone) continue
+
+    archivedSidebar.splice(cursor, 0, clone)
+    cursor++
+  }
+}
+
+function cloneExcludedSidebarEntry(
+  entry: StarlightSidebar[number],
+  excludedSlugs: string[],
+  baseURL: URL,
+): StarlightSidebar[number] | undefined {
+  if (!('autogenerate' in entry)) return undefined
+
+  if (entry.type === 'link') {
+    const slug = getSidebarSlug(entry.href, baseURL)
+    if (!excludedSlugs.includes(slug)) return undefined
+    return { ...entry, isCurrent: false }
+  }
+
+  const entries = entry.entries.flatMap((child) => {
+    const clone = cloneExcludedSidebarEntry(child, excludedSlugs, baseURL)
+    return clone ? [clone] : []
+  })
+
+  return entries.length > 0 ? { ...entry, entries } : undefined
+}
+
+function isMatchingSidebarEntry(
+  current: StarlightSidebar[number],
+  archived: StarlightSidebar[number],
+  version: string,
+  baseURL: URL,
+) {
+  if (current.type !== archived.type) return false
+  if (current.type === 'link' && archived.type === 'link') {
+    return getSidebarSlug(current.href, baseURL) === getSidebarSlug(archived.href, baseURL, version)
+  }
+  if (current.type !== 'group' || archived.type !== 'group') return false
+
+  const currentAuto = 'autogenerate' in current
+  const archivedAuto = 'autogenerate' in archived
+  if (currentAuto !== archivedAuto || current.label !== archived.label) return false
+  if (!currentAuto || !archivedAuto) return true
+
+  return current.autogenerate.directory === stripVersionSegment(archived.autogenerate.directory, version)
+}
+
+function getSidebarSlug(href: string, baseURL: URL, version?: string) {
+  const slug = getURLSlug(new URL(href, baseURL))
+  return version ? stripVersionSegment(slug, version) : slug
 }
 
 // An undefined version is valid and represents the current version.
@@ -278,12 +452,9 @@ export function getVersionFromPaginationLink(
   link: string,
   locale: string | undefined,
 ): Version | undefined {
-  const [, ...segments] = link.split('/')
-
-  if (import.meta.env.BASE_URL !== '/') {
-    // Remove the base segment if configured.
-    segments.splice(0, 1)
-  }
+  const base = stripTrailingSlash(import.meta.env.BASE_URL)
+  const pathname = link === base || link.startsWith(ensureTrailingSlash(base)) ? link.slice(base.length) : link
+  const segments = stripLeadingAndTrailingSlashes(pathname).split('/')
 
   if (locale) {
     // Remove the locale segment if the current locale is not a root locale.
@@ -297,30 +468,57 @@ export function getVersionFromPaginationLink(
   return config.versions.find((version) => version.slug === versionSegment)
 }
 
-async function getSidebarVersionGroup(version: Version, srcDir: URL) {
-  const versionConfig = await getVersionConfig(version, srcDir)
-
-  if (!versionConfig.sidebar) {
-    return {
-      label: version.slug,
-      items: [{ autogenerate: { directory: version.slug } }],
-    }
-  }
-
-  return {
-    label: version.slug,
-    items: addPrefixToSidebarConfig(version.slug, versionConfig.sidebar),
-  }
-}
-
 async function getVersionConfig(version: Version, srcDir: URL) {
   try {
-    return await readJSONFile<DocsVersionsConfig>(getVersionConfigURL(version, srcDir))
+    return docsVersionsSchema().parse(
+      await readJSONFile<Partial<DocsVersionsConfig>>(getVersionConfigURL(version, srcDir)),
+    )
   } catch (error) {
     throw new Error(`Failed to read the version '${version.slug}' configuration file.`, { cause: error })
   }
 }
 
+async function getExcludedDocs(config: StarlightVersionsConfig, locales: string[], docsDir: URL) {
+  const excludedDocs = new Map<string, string>()
+
+  async function visitDirectory(directory: URL) {
+    for (const entry of await listDirectory(directory)) {
+      const isDirectory = await isDirectoryEntry(entry)
+      const entryURL = new URL(isDirectory ? ensureTrailingSlash(entry.name) : entry.name, directory)
+      const docPath = getDocPath(docsDir, entryURL)
+
+      if (isDirectory) {
+        const [firstSegment, secondSegment] = docPath.split('/')
+
+        if (
+          (firstSegment && firstSegment in config.versionsBySlug) ||
+          (firstSegment && locales.includes(firstSegment) && secondSegment && secondSegment in config.versionsBySlug)
+        ) {
+          continue
+        }
+
+        await visitDirectory(entryURL)
+
+        continue
+      }
+
+      if (
+        !entry.isFile() ||
+        !docsExtensions.has(getExtension(docPath)) ||
+        !config.exclude.some((excludeGlob) => path.posix.matchesGlob(docPath, excludeGlob))
+      ) {
+        continue
+      }
+
+      excludedDocs.set(docPath, resolveDocSlug(docsDir, entryURL, await fs.readFile(entryURL, 'utf8')))
+    }
+  }
+
+  await visitDirectory(docsDir)
+
+  return excludedDocs
+}
+
 async function checkForNewVersion(config: StarlightVersionsConfig, docsDir: URL): Promise<Version | undefined> {
   let newVersion: Version | undefined
 
@@ -345,12 +543,18 @@ async function checkForNewVersion(config: StarlightVersionsConfig, docsDir: URL)
   return newVersion
 }
 
-async function makeVersionConfig(version: Version, starlightConfig: StarlightUserConfig, srcDir: URL) {
+async function makeVersionConfig(
+  version: Version,
+  starlightConfig: StarlightUserConfig,
+  srcDir: URL,
+  excludedSlugs: string[],
+) {
   const versionsDir = getVersionContentCollectionURL(srcDir)
 
   await ensureDirectory(versionsDir)
   await writeJSONFile(getVersionConfigURL(version, srcDir), {
     sidebar: starlightConfig.sidebar,
+    excluded: excludedSlugs,
   } satisfies DocsVersionsConfig)
 }
 
@@ -362,6 +566,13 @@ function getVersionConfigURL(version: Version, srcDir: URL) {
   return new URL(`${version.slug}.json`, getVersionContentCollectionURL(srcDir))
 }
 
+function stripVersionSegment(route: string, version: string) {
+  const segments = route.split('/')
+  const index = segments.indexOf(version)
+  if (index !== -1) segments.splice(index, 1)
+  return segments.join('/')
+}
+
 export type Version = z.output<typeof VersionSchema>
 
 export interface VersionAsset {

package/middleware.ts

@@ -2,32 +2,119 @@ import { defineRouteMiddleware, type StarlightRouteData } from '@astrojs/starlig
 import starlightConfig from 'virtual:starlight/user-config'
 import starlightVersionsConfig from 'virtual:starlight-versions-config'
 
-import { getVersionFromPaginationLink, getVersionFromSlug, getVersionSidebar, type Version } from './libs/versions'
+import { getSidebarLinks } from './libs/starlight'
+import {
+  addExcludedLinksToVersionSidebar,
+  getCanonicalSlug,
+  getVersionFromPaginationLink,
+  getVersionFromSlug,
+  getVersionSidebar,
+  isSlugExcludedFromVersion,
+  type Version,
+} from './libs/versions'
 
 export const onRequest = defineRouteMiddleware((context) => {
   const { starlightRoute } = context.locals
-  const { entry, locale, pagination, sidebar } = starlightRoute
-
-  starlightRoute.sidebar = getVersionSidebar(
-    getVersionFromSlug(starlightVersionsConfig, starlightConfig, entry.id),
-    sidebar,
-  )
+  const { entry, locale, sidebar } = starlightRoute
 
   const pageVersion = getVersionFromSlug(starlightVersionsConfig, starlightConfig, entry.id)
+  const versionSidebar = getVersionSidebar(pageVersion, sidebar)
+
+  if (pageVersion) {
+    const excludedSlugs = starlightVersionsConfig.excludedSlugsByVersion[pageVersion.slug] ?? []
+    if (excludedSlugs.length > 0) {
+      addExcludedLinksToVersionSidebar(
+        getVersionSidebar(undefined, sidebar),
+        versionSidebar,
+        pageVersion,
+        excludedSlugs,
+        context.url,
+      )
+      starlightRoute.pagination = getPaginationFromSidebar(starlightRoute, versionSidebar)
+    }
+  }
+
+  starlightRoute.sidebar = versionSidebar
 
-  starlightRoute.pagination.prev = getPaginationLink(locale, pageVersion, pagination.prev)
-  starlightRoute.pagination.next = getPaginationLink(locale, pageVersion, pagination.next)
+  starlightRoute.pagination.prev = getPaginationLink(context.url, locale, pageVersion, starlightRoute.pagination.prev)
+  starlightRoute.pagination.next = getPaginationLink(context.url, locale, pageVersion, starlightRoute.pagination.next)
 })
 
-function getPaginationLink(locale: string | undefined, currentVersion: Version | undefined, link: PaginationLink) {
+function getPaginationLink(
+  baseURL: URL,
+  locale: string | undefined,
+  currentVersion: Version | undefined,
+  link: PaginationLink,
+) {
   if (!link) return undefined
 
   const linkVersion = getVersionFromPaginationLink(starlightVersionsConfig, link.href, locale)
+  const canonicalSlug = getCanonicalSlug(starlightVersionsConfig, starlightConfig, new URL(link.href, baseURL))
 
-  // If the current version is not the same as the link version, remove the link.
-  return (currentVersion === undefined && linkVersion === undefined) || currentVersion?.slug === linkVersion?.slug
+  // If the current version is not the same as the link version and it's not an excluded version link, remove it.
+  return (currentVersion === undefined && linkVersion === undefined) ||
+    currentVersion?.slug === linkVersion?.slug ||
+    (linkVersion === undefined && isSlugExcludedFromVersion(starlightVersionsConfig, currentVersion, canonicalSlug))
     ? link
     : undefined
 }
 
+// https://github.com/withastro/starlight/blob/main/packages/starlight/utils/navigation.ts#L481
+function getPaginationFromSidebar(
+  route: StarlightRouteData,
+  sidebar: StarlightRouteData['sidebar'],
+): StarlightRouteData['pagination'] {
+  const entries = getSidebarLinks(sidebar)
+  const currentIndex = entries.findIndex((entry) => entry.isCurrent)
+
+  const prev = applyPaginationConfig(
+    entries[currentIndex - 1],
+    starlightConfig.pagination,
+    route.entry.data.prev,
+    route.pagination.prev,
+  )
+  const next = applyPaginationConfig(
+    currentIndex > -1 ? entries[currentIndex + 1] : undefined,
+    starlightConfig.pagination,
+    route.entry.data.next,
+    route.pagination.next,
+  )
+
+  return { prev, next }
+}
+
+// https://github.com/withastro/starlight/blob/main/packages/starlight/utils/navigation.ts#L501
+function applyPaginationConfig(
+  link: PaginationLink,
+  paginationEnabled: boolean,
+  config: StarlightRouteData['entry']['data']['prev'],
+  existing: PaginationLink,
+): PaginationLink {
+  // Explicitly remove the link.
+  if (config === false) return undefined
+  // Use the generated link if any.
+  else if (config === true) return link
+  // If a link exists, update its label if needed.
+  else if (typeof config === 'string' && link) {
+    return { ...link, label: config }
+  } else if (typeof config === 'object') {
+    if (link) {
+      // If a link exists, update both its label and href if needed.
+      return {
+        ...link,
+        label: config.label ?? link.label,
+        href: config.link ?? link.href,
+        // Explicitly remove sidebar link attributes for prev/next links.
+        attrs: {},
+      }
+    } else if (config.link && config.label) {
+      // If there is no link and the frontmatter contains both a URL and a label, use it.
+      return existing
+    }
+  }
+
+  // Otherwise, if the global config is enabled, return the generated link if any.
+  return paginationEnabled ? link : undefined
+}
+
 type PaginationLink = StarlightRouteData['pagination']['next']

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-versions",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "license": "MIT",
   "description": "Starlight plugin to version documentation pages.",
   "author": "HiDeoo <github@hideoo.dev> (https://hideoo.dev)",

package/schema.ts

@@ -4,10 +4,12 @@ import type { StarlightSidebarUserConfig } from './libs/starlight'
 
 export function docsVersionsSchema() {
   return z.object({
-    sidebar: z.any().optional(),
+    sidebar: z.custom<NonNullable<StarlightSidebarUserConfig>>().optional(),
+    excluded: z.array(z.string()).default([]),
   })
 }
 
 export interface DocsVersionsConfig {
   sidebar?: StarlightSidebarUserConfig
+  excluded: string[]
 }