starlight-versions 0.1.0

package/components/VersionSelect.astro

@@ -0,0 +1,112 @@
+---
+import { Icon } from '@astrojs/starlight/components'
+import type { Props } from '@astrojs/starlight/props'
+import starlightConfig from 'virtual:starlight/user-config'
+import starlightVersionsConfig from 'virtual:starlight-versions-config'
+
+import { getVersionFromSlug, getVersionURL } from '../libs/versions'
+
+const { slug } = Astro.props
+
+const pageVersion = getVersionFromSlug(starlightVersionsConfig, starlightConfig, slug)
+---
+
+<starlight-version-select>
+  <label>
+    <span class="sr-only">Select version</span>
+    <Icon name="seti:clock" class="icon label-icon" />
+    <select value={pageVersion?.label ?? 'current'}>
+      <option
+        selected={pageVersion === undefined}
+        value={getVersionURL(starlightVersionsConfig, starlightConfig, Astro.url, undefined).pathname}
+        >{starlightVersionsConfig.current.label}</option
+      >
+      {
+        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 {
+    --sl-versions-label-icon-size: 0.875rem;
+    --sl-versions-caret-icon-size: 1.25rem;
+
+    align-items: center;
+    color: var(--sl-color-gray-1);
+    display: flex;
+    gap: 0.25rem;
+    position: relative;
+  }
+
+  label:hover {
+    color: var(--sl-color-gray-2);
+  }
+
+  .icon {
+    pointer-events: none;
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+  }
+
+  .label-icon {
+    font-size: var(--sl-versions-label-icon-size);
+    inset-inline-start: 0;
+  }
+
+  .caret-icon {
+    font-size: var(--sl-versions-caret-icon-size);
+    inset-inline-end: 0;
+  }
+
+  select {
+    appearance: none;
+    background-color: transparent;
+    border: 0;
+    color: inherit;
+    cursor: pointer;
+    padding-block: 0.625rem;
+    padding-inline: calc(var(--sl-versions-label-icon-size) + 0.375rem)
+      calc(var(--sl-versions-caret-icon-size) + 0.25rem);
+    text-overflow: ellipsis;
+    width: 6.5em;
+  }
+
+  option {
+    background-color: var(--sl-color-bg-nav);
+    color: var(--sl-color-gray-1);
+  }
+
+  @media (min-width: 50rem) {
+    select {
+      font-size: var(--sl-text-sm);
+    }
+  }
+</style>
+
+<script>
+  customElements.define(
+    'starlight-version-select',
+    class StarlightVersionSelect extends HTMLElement {
+      constructor() {
+        super()
+
+        this.querySelector('select')?.addEventListener('change', (event) => {
+          if (event.currentTarget instanceof HTMLSelectElement) {
+            window.location.pathname = event.currentTarget.value
+          }
+        })
+      }
+    },
+  )
+</script>

package/components/VersionSidebar.astro

@@ -0,0 +1,15 @@
+---
+import Default from '@astrojs/starlight/components/Sidebar.astro'
+import type { Props } from '@astrojs/starlight/props'
+import starlightConfig from 'virtual:starlight/user-config'
+import starlightVersionsConfig from 'virtual:starlight-versions-config'
+
+import { getVersionFromSlug, getVersionSidebar } from '../libs/versions'
+
+const sidebar = getVersionSidebar(
+  getVersionFromSlug(starlightVersionsConfig, starlightConfig, Astro.props.entry.slug),
+  Astro.props.sidebar,
+)
+---
+
+<Default {...Astro.props} {sidebar}><slot /></Default>

package/env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly BASE_URL: string
+  readonly DEV: boolean
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/index.ts

@@ -0,0 +1,70 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types'
+
+import { StarlightVersionsConfigSchema, type StarlightVersionsUserConfig } from './libs/config'
+import { overrideComponents, throwPluginError } from './libs/plugin'
+import { ensureNewVersion, getVersionedSidebar } from './libs/versions'
+import { vitePluginStarlightVersions } from './libs/vite'
+
+export type { StarlightVersionsConfig, StarlightVersionsUserConfig } from './libs/config'
+
+export default function starlightVersionsPlugin(userConfig: StarlightVersionsUserConfig): StarlightPlugin {
+  const parsedConfig = StarlightVersionsConfigSchema.safeParse(userConfig)
+
+  if (!parsedConfig.success) {
+    throwPluginError(
+      `The provided plugin configuration is invalid.\n${parsedConfig.error.issues.map((issue) => issue.message).join('\n')}`,
+    )
+  }
+
+  const config = parsedConfig.data
+
+  return {
+    name: 'starlight-versions-plugin',
+    hooks: {
+      async setup({ addIntegration, astroConfig, command, config: starlightConfig, logger, updateConfig }) {
+        if (command !== 'dev' && command !== 'build') return
+
+        try {
+          await ensureNewVersion(config, starlightConfig, astroConfig.srcDir, logger)
+        } catch (error) {
+          throwPluginError(
+            error instanceof Error ? error.message : 'An error occurred while creating a new documentation version.',
+          )
+        }
+
+        try {
+          const versionedSidebar = await getVersionedSidebar(config, starlightConfig.sidebar, astroConfig.srcDir)
+
+          updateConfig({
+            components: overrideComponents(
+              starlightConfig,
+              [
+                { name: 'ThemeSelect', fallback: 'VersionSelect' },
+                { name: 'Sidebar', fallback: 'VersionSidebar' },
+                { name: 'Pagination', fallback: 'VersionPagination' },
+                { name: 'Search', fallback: 'VersionSearch' },
+                { name: 'PageTitle', fallback: 'VersionNotice' },
+                { name: 'Banner', fallback: 'VersionBanner' },
+              ],
+              logger,
+            ),
+            sidebar: versionedSidebar,
+          })
+        } catch (error) {
+          throwPluginError(
+            error instanceof Error ? error.message : 'An error occurred while generating versioned sidebars.',
+          )
+        }
+
+        addIntegration({
+          name: 'starlight-versions-integration',
+          hooks: {
+            'astro:config:setup': ({ updateConfig }) => {
+              updateConfig({ vite: { plugins: [vitePluginStarlightVersions(config)] } })
+            },
+          },
+        })
+      },
+    },
+  }
+}

package/libs/config.ts

@@ -0,0 +1,34 @@
+import { z } from 'astro/zod'
+
+import { VersionBaseSchema, VersionSchema } from './versions'
+
+export const StarlightVersionsConfigSchema = z
+  .object({
+    /**
+     * Options related to the current version of the documentation.
+     */
+    current: z
+      .object({
+        /**
+         * The label used in the UI to represent the current version.
+         *
+         * @default 'Latest'
+         */
+        label: z.string().default('Latest'),
+      })
+      .merge(VersionBaseSchema)
+      .default({}),
+    /**
+     * A list of all archived versions of the documentation.
+     */
+    versions: z.array(VersionSchema).refine((value) => value.length > 0, {
+      message: 'At least one version of the documentation must be defined.',
+    }),
+  })
+  .transform((value) => ({
+    ...value,
+    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

@@ -0,0 +1,67 @@
+import type { PathLike } from 'node:fs'
+import fs from 'node:fs/promises'
+
+import { ensureTrailingSlash } from './path'
+
+export function listDirectory(directory: URL) {
+  return fs.readdir(directory, { withFileTypes: true })
+}
+
+export async function copyDirectory(sourceDir: URL, destDir: URL, callback: CopyDirectoryCallback, isRoot = true) {
+  const dirEntries = await listDirectory(sourceDir)
+
+  if (isRoot && dirEntries.length === 0) {
+    throw new Error(
+      `Failed to copy the empty directory ('${sourceDir.pathname}') to the destination ('${destDir.pathname}').`,
+    )
+  }
+
+  await ensureDirectory(destDir)
+
+  for (const entry of dirEntries) {
+    if (entry.isDirectory()) {
+      const source = new URL(ensureTrailingSlash(entry.name), sourceDir)
+      let dest = new URL(ensureTrailingSlash(entry.name), destDir)
+
+      const skipOrDest = await callback({ type: 'directory', name: entry.name, isRoot, dest, source })
+      if (skipOrDest === true) continue
+      if (skipOrDest instanceof URL) dest = skipOrDest
+
+      await ensureDirectory(dest)
+      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 })
+
+      if (typeof updatedContent !== 'string') continue
+
+      await fs.writeFile(new URL(entry.name, destDir), updatedContent)
+    }
+  }
+}
+
+export function copyFile(source: URL, dest: URL) {
+  return fs.cp(source, dest, { force: true })
+}
+
+export function writeJSONFile(file: PathLike, data: unknown) {
+  return fs.writeFile(file, JSON.stringify(data, null, 2))
+}
+
+export async function readJSONFile<T extends object>(file: PathLike): Promise<T> {
+  const content = await fs.readFile(file, 'utf8')
+
+  return JSON.parse(content) as T
+}
+
+export function ensureDirectory(directory: PathLike) {
+  return fs.mkdir(directory, { recursive: true })
+}
+
+export type CopyDirectoryCallback = (
+  entry:
+    | { type: 'file'; content: string; url: URL }
+    | { type: 'directory'; name: string; isRoot: boolean; source: URL; dest: URL },
+) => Promise<string | boolean | URL>

package/libs/markdown.ts

@@ -0,0 +1,246 @@
+import assert from 'node:assert'
+
+import type { 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'
+import remarkFrontmatter from 'remark-frontmatter'
+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 { getFrontmatterNodeValue, parseFrontmatter } from './starlight'
+import type { Version, VersionAsset } from './versions'
+
+const importPathRegex = /(from ?["'])([^"']*)(["'];?\s?)$/gm
+const astroAssetRegex = /\.(png|jpg|jpeg|tiff|webp|gif|svg|avif)$/i
+
+const mediaElements = new Set(['img', 'source', 'Image', 'audio', 'video'])
+
+const processor = remark().use(remarkMdx).use(remarkFrontmatter).use(remarkStarlightVersions)
+
+export async function transformMarkdown(markdown: string, context: TransformContext) {
+  const file = await processor.process({
+    data: { ...context },
+    value: markdown,
+  })
+
+  return {
+    assets: file.data.assets,
+    content: String(file),
+  }
+}
+
+export function remarkStarlightVersions() {
+  return function transformer(tree: Root, file: VFile) {
+    visit(tree, (node) => {
+      switch (node.type) {
+        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': {
+          if (node.name && mediaElements.has(node.name)) {
+            return handleMediaElements(node, file)
+          }
+
+          return CONTINUE
+        }
+        case 'image': {
+          return handleImages(node, file)
+        }
+        default: {
+          return CONTINUE
+        }
+      }
+    })
+
+    handleFrontmatter(tree, file)
+  }
+}
+
+function handleFrontmatter(tree: Root, file: VFile) {
+  // The frontmatter is always at the root of the tree.
+  for (const node of tree.children) {
+    if (node.type !== 'yaml') {
+      continue
+    }
+
+    const frontmatter = parseFrontmatter(node.value)
+
+    if (frontmatter.slug) {
+      frontmatter.slug = stripLeadingSlash(
+        stripTrailingSlash(`${file.data.version?.slug}/${stripTrailingSlash(frontmatter.slug)}`),
+      )
+    } else if (file.data.slug && file.data.version) {
+      if (file.data.slug === '/') {
+        frontmatter.slug = file.data.version.slug
+      } else {
+        const segments = file.data.slug.split('/')
+
+        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)
+        }
+
+        frontmatter.slug = segments.join('/')
+      }
+    }
+
+    if (typeof frontmatter.prev === 'object' && frontmatter.prev.link?.startsWith('/')) {
+      frontmatter.prev.link = addVersionToLink(frontmatter.prev.link, file)
+    }
+
+    if (typeof frontmatter.next === 'object' && frontmatter.next.link?.startsWith('/')) {
+      frontmatter.next.link = addVersionToLink(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)
+        }
+      }
+    }
+
+    if (frontmatter.hero?.image) {
+      if (frontmatter.hero.image.file?.startsWith('../')) {
+        frontmatter.hero.image.file = addVersionToAstroAsset(frontmatter.hero.image.file, file)
+      }
+      if (frontmatter.hero.image.dark?.startsWith('../')) {
+        frontmatter.hero.image.dark = addVersionToAstroAsset(frontmatter.hero.image.dark, file)
+      }
+      if (frontmatter.hero.image.light?.startsWith('../')) {
+        frontmatter.hero.image.light = addVersionToAstroAsset(frontmatter.hero.image.light, file)
+      }
+    }
+
+    node.value = getFrontmatterNodeValue(frontmatter)
+
+    break
+  }
+}
+
+function handleLinks(node: Link, file: VFile) {
+  if (!isPublicAsset(node.url)) return SKIP
+
+  node.url = addVersionToLink(node.url, file)
+
+  return SKIP
+}
+
+function handleLinkElements(node: 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
+
+  href.value = addVersionToLink(href.value, file)
+
+  return CONTINUE
+}
+
+function handleImages(node: Image, file: VFile) {
+  if (isAbsoluteLink(node.url)) return SKIP
+
+  node.url = (isPublicAsset(node.url) ? addVersionToPublicAsset : addVersionToAstroAsset)(node.url, file)
+
+  return SKIP
+}
+
+function handleMediaElements(node: MdxJsxFlowElement, file: VFile) {
+  const srcOrSrcset = node.attributes.find(
+    (attribute) => attribute.type === 'mdxJsxAttribute' && (attribute.name === 'src' || attribute.name === 'srcset'),
+  )
+
+  if (!srcOrSrcset || typeof srcOrSrcset.value !== 'string' || !isPublicAsset(srcOrSrcset.value)) return CONTINUE
+
+  srcOrSrcset.value = addVersionToPublicAsset(srcOrSrcset.value, file)
+
+  return SKIP
+}
+
+function handleImports(node: MdxjsEsm, file: VFile) {
+  node.value = node.value.replaceAll(importPathRegex, (match, start, importPath: string, end) => {
+    if (!importPath.startsWith('../')) return match
+
+    if (isAstroAsset(importPath)) {
+      return `${start}${addVersionToAstroAsset(importPath, file)}${end}`
+    }
+
+    return `${start}../${importPath}${end}`
+  })
+
+  return SKIP
+}
+
+function addVersionToLink(link: string, file: VFile) {
+  assert(file.data.version, 'A version must be provided to add a version to an Astro asset.')
+
+  const segments = link.split('/')
+  segments.splice(1, 0, file.data.version.slug)
+
+  return segments.join('/')
+}
+
+function addVersionToAstroAsset(asset: string, file: VFile) {
+  assert(file.data.version, 'A version must be provided to add a version to an Astro asset.')
+
+  const source = new URL(asset, file.data.url)
+
+  const segments = asset.split('/')
+  segments.splice(-1, 0, file.data.version.slug)
+
+  addVersionAsset(file, { source, dest: new URL(segments.join('/'), file.data.url) })
+
+  segments.splice(0, 0, '..')
+
+  return segments.join('/')
+}
+
+function addVersionToPublicAsset(asset: string, file: VFile) {
+  assert(file.data.version, 'A version must be provided to add a version to an public asset.')
+
+  const source = new URL(asset, file.data.url)
+
+  const segments = asset.split('/')
+  segments.splice(-1, 0, file.data.version.slug)
+
+  addVersionAsset(file, { source, dest: new URL(segments.join('/'), file.data.url) })
+
+  return segments.join('/')
+}
+
+function addVersionAsset(file: VFile, asset: VersionAsset) {
+  file.data.assets?.push(asset)
+}
+
+function isAstroAsset(asset: string) {
+  return astroAssetRegex.test(asset)
+}
+
+function isPublicAsset(asset: string) {
+  return asset.startsWith('/')
+}
+
+export interface TransformContext {
+  assets: VersionAsset[]
+  locale: string | undefined
+  slug: string
+  url: URL
+  version: Version
+}
+
+declare module 'vfile' {
+  interface DataMap extends TransformContext {}
+}

package/libs/path.ts

@@ -0,0 +1,49 @@
+import path from 'node:path'
+
+import { slug } from 'github-slugger'
+
+const absoluteLinkRegex = /^https?:\/\//
+
+export function ensureTrailingSlash(filePath: string): string {
+  if (filePath.endsWith('/')) {
+    return filePath
+  }
+
+  return `${filePath}/`
+}
+
+export function stripLeadingSlash(filePath: string) {
+  if (!filePath.startsWith('/')) {
+    return filePath
+  }
+
+  return filePath.slice(1)
+}
+
+export function stripTrailingSlash(filePath: string) {
+  if (!filePath.endsWith('/')) {
+    return filePath
+  }
+
+  return filePath.slice(0, -1)
+}
+
+export function slugifyPath(filePath: string): string {
+  const segments = stripExtension(filePath).split('/')
+
+  return segments.map((segment) => slug(segment)).join('/')
+}
+
+export function getExtension(filePath: string) {
+  return path.extname(filePath)
+}
+
+export function stripExtension(filePath: string) {
+  const parsedPath = path.parse(filePath)
+
+  return path.posix.join(parsedPath.dir, parsedPath.name)
+}
+
+export function isAbsoluteLink(link: string) {
+  return absoluteLinkRegex.test(link)
+}

package/libs/plugin.ts

@@ -0,0 +1,36 @@
+import type { AstroIntegrationLogger } from 'astro'
+import { AstroError } from 'astro/errors'
+
+import type { StarlightUserConfig } from './starlight'
+
+export function throwPluginError(message: string): never {
+  throw new AstroError(
+    message,
+    `See the error report above for more informations.\n\nIf you believe this is a bug, please file an issue at https://github.com/HiDeoo/starlight-versions/issues/new/choose`,
+  )
+}
+
+export function overrideComponents(
+  starlightConfig: StarlightUserConfig,
+  overrides: ComponentOverride[],
+  logger: AstroIntegrationLogger,
+): StarlightUserConfig['components'] {
+  const components = { ...starlightConfig.components }
+  for (const { name, fallback } of overrides) {
+    if (starlightConfig.components?.[name]) {
+      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\`.`,
+      )
+      continue
+    }
+    components[name] = `starlight-versions/overrides/${name}.astro`
+  }
+
+  return components
+}
+
+interface ComponentOverride {
+  name: keyof NonNullable<StarlightUserConfig['components']>
+  fallback: string
+}