@chassis-ui/docs 0.5.1 → 0.6.0

package/src/libs/remark.ts

@@ -0,0 +1,184 @@
+import type { Root } from 'mdast'
+import type { MdxJsxAttribute, MdxJsxExpressionAttribute } from 'mdast-util-mdx-jsx'
+import type { Plugin } from 'unified'
+import { visit } from 'unist-util-visit'
+import { joinDocsPath } from './docs-path'
+
+// [[config:foo]]
+// [[config:foo.bar]]
+const configRegExp = /\[\[config:(?<name>[\w.]+)\]\]/g
+// [[docsref:/foo]]
+// [[docsref:/foo/bar#baz]]
+const docsrefRegExp = /\[\[docsref:(?<path>[\w./#-]+)\]\]/g
+
+type Replacer = (_text: string) => string
+type MdxAttributes = (MdxJsxAttribute | MdxJsxExpressionAttribute)[]
+
+export interface RemarkCxConfigOptions {
+  /** The parsed `config.yml`. */
+  config: object
+}
+
+export interface RemarkCxDocsrefOptions {
+  /** The `docsPath` of the site's `config.yml`. */
+  docsPath: string
+  /** Called with each docs path that a page links to. */
+  onDocsPath?: (_path: string) => void
+}
+
+/** Replaces each `[[config:key]]` in `text` with the value of that key. */
+export function replaceConfigInText(text: string, config: object): string {
+  return text.replace(configRegExp, (_match, keyPath: string) => {
+    const value = keyPath.split('.').reduce<unknown>((values, part) => {
+      return values && typeof values === 'object'
+        ? (values as Record<string, unknown>)[part]
+        : undefined
+    }, config)
+
+    if (typeof value !== 'string' || !value) {
+      throw new Error(`Failed to find a valid configuration value for '${keyPath}'.`)
+    }
+
+    return value
+  })
+}
+
+/** Replaces each `[[docsref:/path]]` in `text` with the URL path of that docs page. */
+export function replaceDocsrefInText(text: string, options: RemarkCxDocsrefOptions): string {
+  return text.replace(docsrefRegExp, (_match, inputPath: string) => {
+    options.onDocsPath?.(inputPath)
+
+    return joinDocsPath(options.docsPath, inputPath)
+  })
+}
+
+function replaceInAttributes(attributes: MdxAttributes, replacer: Replacer) {
+  return attributes.map((attribute) => {
+    if (attribute.type === 'mdxJsxAttribute' && typeof attribute.value === 'string') {
+      attribute.value = replacer(attribute.value)
+    }
+
+    return attribute
+  })
+}
+
+function replaceInFrontmatter(record: Record<string, unknown>, replacer: Replacer) {
+  for (const [key, value] of Object.entries(record)) {
+    if (typeof value === 'string') {
+      record[key] = replacer(value)
+    } else if (Array.isArray(value)) {
+      record[key] = value.map((arrayValue) => {
+        return typeof arrayValue === 'string'
+          ? replacer(arrayValue)
+          : typeof arrayValue === 'object'
+            ? replaceInFrontmatter(arrayValue, replacer)
+            : arrayValue
+      })
+    }
+  }
+
+  return record
+}
+
+function containsFrontmatter(data: unknown): data is { frontmatter: Record<string, unknown> } {
+  return data != undefined && typeof data === 'object' && 'frontmatter' in data
+}
+
+/**
+ * A remark plugin that replaces config values in Markdown and MDX files. `[[config:foo]]`
+ * becomes the value of the `foo` key of `config.yml`, and `[[config:foo.bar]]` reads a nested
+ * key. It also works in frontmatter.
+ */
+export const remarkCxConfig: Plugin<[RemarkCxConfigOptions], Root> = function ({ config }) {
+  const replacer: Replacer = (text) => replaceConfigInText(text, config)
+
+  return function remarkCxConfigPlugin(ast, file) {
+    if (containsFrontmatter(file.data.astro)) {
+      replaceInFrontmatter(file.data.astro.frontmatter, replacer)
+    }
+
+    // https://github.com/syntax-tree/mdast#nodes
+    // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
+    visit(
+      ast,
+      ['code', 'definition', 'image', 'inlineCode', 'link', 'mdxJsxFlowElement', 'text'],
+      (node) => {
+        switch (node.type) {
+          case 'code':
+          case 'inlineCode':
+          case 'text': {
+            node.value = replacer(node.value)
+            break
+          }
+          case 'image': {
+            if (node.alt) {
+              node.alt = replacer(node.alt)
+            }
+
+            node.url = replacer(node.url)
+            break
+          }
+          case 'definition':
+          case 'link': {
+            node.url = replacer(node.url)
+            break
+          }
+          case 'mdxJsxFlowElement': {
+            node.attributes = replaceInAttributes(node.attributes, replacer)
+            break
+          }
+        }
+      }
+    )
+  }
+}
+
+/**
+ * A remark plugin that turns `[[docsref:/foo]]` into a link to the docs page `/foo`, under
+ * the `docsPath` of `config.yml`. It also works in frontmatter.
+ */
+export const remarkCxDocsref: Plugin<[RemarkCxDocsrefOptions], Root> = function (options) {
+  const replacer: Replacer = (text) => replaceDocsrefInText(text, options)
+
+  return function remarkCxDocsrefPlugin(ast, file) {
+    if (containsFrontmatter(file.data.astro)) {
+      replaceInFrontmatter(file.data.astro.frontmatter, replacer)
+    }
+
+    // https://github.com/syntax-tree/mdast#nodes
+    // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
+    visit(
+      ast,
+      [
+        'code',
+        'definition',
+        'image',
+        'inlineCode',
+        'link',
+        'mdxJsxFlowElement',
+        'mdxJsxTextElement',
+        'text'
+      ],
+      (node) => {
+        switch (node.type) {
+          case 'code':
+          case 'inlineCode':
+          case 'text': {
+            node.value = replacer(node.value)
+            break
+          }
+          case 'definition':
+          case 'link': {
+            node.url = replacer(node.url)
+            break
+          }
+          case 'mdxJsxFlowElement':
+          case 'mdxJsxTextElement': {
+            node.attributes = replaceInAttributes(node.attributes, replacer)
+            break
+          }
+        }
+      }
+    )
+  }
+}

package/src/libs/schema.ts

@@ -0,0 +1,211 @@
+import { z } from 'astro/zod'
+
+// Sites extend the schemas below. They must use this `z`, so that the site and the package
+// share one copy of Zod.
+export { z }
+
+export const zVersionMajorMinor = z.string().regex(/^\d+\.\d+$/)
+
+// https://ihateregex.io/expr/semver/
+const unboundSemverRegex =
+  /(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?/
+
+export const zVersionSemver = z.string().regex(new RegExp(`^${unboundSemverRegex.source}$`))
+export const zPrefixedVersionSemver = z
+  .string()
+  .regex(new RegExp(`^v${unboundSemverRegex.source}$`))
+
+export const zLanguageCode = z.string().regex(/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
+
+const zHeadingRange = z.object({
+  min: z.number().int().min(1).max(6),
+  max: z.number().int().min(1).max(6)
+})
+
+/**
+ * The keys of `config.yml` that the package reads.
+ *
+ * The schema is strict: a key that is not in it fails the build. A site with keys of its own
+ * extends the schema and passes the result to the integration.
+ *
+ * @example
+ * ```ts
+ * import { configSchema, z } from '@chassis-ui/docs/schema'
+ *
+ * export const siteConfigSchema = configSchema.extend({
+ *   blog: z.object({ pageSize: z.number() })
+ * })
+ * ```
+ */
+export const configSchema = z.strictObject({
+  /** Google Analytics is loaded in production builds when `googleId` is set. */
+  analytics: z.strictObject({ googleId: z.string().optional() }).default({}),
+  /** Heading levels that get an anchor link. */
+  anchors: zHeadingRange.default({ min: 2, max: 5 }),
+  authors: z.string(),
+  /** Canonical URL of the site, e.g. `"https://chassis-ui.com/css"`. */
+  baseURL: z.url(),
+  /** Version of the release that the site documents. Links to source files use its tag. */
+  currentVersion: zVersionSemver,
+  description: z.string(),
+  /** URL path of the docs pages, e.g. `"/css/docs"`. */
+  docsPath: z.string().startsWith('/'),
+  /** Figma Community handle, without the `@`. The header links to it when set. */
+  figmaHandle: z.string().optional(),
+  /** GitHub organisation or user name, not a URL. The header links to it when set. */
+  githubOrg: z
+    .string()
+    .regex(/^[\w.-]+$/, 'Expected a GitHub organisation name, not a URL')
+    .optional(),
+  /** Repository URL, e.g. `"https://github.com/chassis-ui/css"`. */
+  repo: z.url(),
+  /** The branch that "View on GitHub" links to. */
+  siteBranch: z.string().default('main'),
+  /** The site's root from the root of the repository, e.g. `"packages/site"`. */
+  sitePath: z.string().optional(),
+  /**
+   * Directory that the `file` props of `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and
+   * `<Code>` are relative to, itself relative to the site's root, e.g. `"../css"`.
+   */
+  sourceDir: z.string().default('.'),
+  /** The same directory from the root of the repository, e.g. `"packages/css"`. */
+  sourcePath: z.string().optional(),
+  subtitle: z.string(),
+  title: z.string(),
+  /** Heading levels that the table of contents lists. */
+  toc: zHeadingRange.default({ min: 2, max: 6 }),
+  /** X handle, without the `@`. Used in the social meta tags when set. */
+  xUsername: z.string().optional()
+})
+
+/** The parsed `config.yml`, limited to the keys that the package reads. */
+export type ChassisConfig = z.infer<typeof configSchema>
+
+/** A schema that a site passes to the integration: `configSchema` or an extension of it. */
+export type ChassisConfigSchema = z.ZodType<ChassisConfig>
+
+/**
+ * Keys that were renamed in 0.6.0. Loading a `config.yml` that still has one of them fails
+ * with a message that names the new key.
+ */
+export const renamedConfigKeys: Record<string, string> = {
+  'analytics.google_id': 'analytics.googleId',
+  current_version: 'currentVersion',
+  figma_handle: 'figmaHandle',
+  github_org: 'githubOrg',
+  x_username: 'xUsername'
+}
+
+/** Keys that were removed in 0.6.0, with the reason. */
+export const removedConfigKeys: Record<string, string> = {
+  docsDir: 'The site root is the Astro root. Delete the key.'
+}
+
+// A key that was renamed in 0.6.0. The schemas below are not strict, so the old key would
+// be dropped silently. This makes it fail, with a message that names the new key.
+function renamedTo(newKey: string) {
+  return z.never({ error: `This key was renamed to \`${newKey}\`.` }).optional()
+}
+
+const sidebarMetaSchema = z.object({ added: z.string() }).array().optional()
+
+/** The entries of `data/sidebar.yml`. */
+export const sidebarSchema = z
+  .object({
+    title: z.string(),
+    section: z.string().optional(),
+    icon: z.string().optional(),
+    iconColor: z.string().optional(),
+    icon_color: renamedTo('iconColor'),
+    pages: z
+      .object({
+        title: z.string().optional(),
+        href: z.string().optional(),
+        group: z.string().optional(),
+        meta: sidebarMetaSchema,
+        pages: z
+          .object({
+            title: z.string(),
+            meta: sidebarMetaSchema
+          })
+          .array()
+          .optional()
+      })
+      .array()
+      .optional()
+  })
+  .array()
+
+export type Sidebar = z.infer<typeof sidebarSchema>
+export type SidebarGroup = Sidebar[number]
+export type SidebarItem = NonNullable<SidebarGroup['pages']>[number]
+export type SidebarSubItem = NonNullable<SidebarItem['pages']>[number]
+
+/**
+ * Frontmatter of a page in the `docs` collection.
+ *
+ * @example
+ * ```ts
+ * // src/content.config.ts
+ * import { defineCollection } from 'astro:content'
+ * import { glob } from 'astro/loaders'
+ * import { calloutsSchema, docsSchema } from '@chassis-ui/docs/schema'
+ *
+ * export const collections = {
+ *   docs: defineCollection({
+ *     loader: glob({ pattern: '**\/*.{md,mdx}', base: './content/docs' }),
+ *     schema: docsSchema
+ *   }),
+ *   callouts: defineCollection({
+ *     loader: glob({ pattern: '**\/*.md', base: './content/callouts' }),
+ *     schema: calloutsSchema
+ *   })
+ * }
+ * ```
+ */
+export const docsSchema = z
+  .object({
+    added: z
+      .object({
+        showBadge: z.boolean().optional(),
+        show_badge: renamedTo('showBadge'),
+        version: z.string()
+      })
+      .optional(),
+    aliases: z.string().or(z.string().array()).optional(),
+    description: z.string(),
+    direction: z.literal('rtl').optional(),
+    extraJs: z
+      .object({
+        async: z.boolean().optional(),
+        src: z.string()
+      })
+      .array()
+      .optional(),
+    extra_js: renamedTo('extraJs'),
+    sections: z
+      .object({
+        description: z.string(),
+        title: z.string(),
+        slug: z.string().optional()
+      })
+      .array()
+      .optional(),
+    thumbnail: z.string().optional(),
+    title: z.string(),
+    toc: z.boolean().optional()
+  })
+  .partial()
+
+export type DocsFrontmatter = z.infer<typeof docsSchema>
+
+/** Frontmatter of an entry in the `callouts` collection. */
+export const calloutsSchema = z.object({})
+
+/** An entry of the `docs` collection, as far as the package reads it. */
+export interface DocsPage {
+  id: string
+  data: DocsFrontmatter
+  /** Path of the source file from the site's root. */
+  filePath?: string
+}

package/src/libs/shortcodes.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import type { AstroIntegration } from 'astro'
+import { resolvePackageFilePath } from './paths'
 
 interface MdxjsEsmNode {
   type: 'mdxjsEsm'
@@ -8,9 +8,13 @@ interface MdxjsEsmNode {
   data: { estree: object }
 }
 
+function getComponentName(filePath: string): string {
+  return path.parse(filePath).name.replaceAll(/[^\w\d]/g, '')
+}
+
 function buildImportsNode(imports: string[]): MdxjsEsmNode {
   const body = imports.map((filePath) => {
-    const name = path.parse(filePath).name.replaceAll(/[^\w\d]/g, '')
+    const name = getComponentName(filePath)
     return {
       type: 'ImportDeclaration',
       specifiers: [{ type: 'ImportDefaultSpecifier', local: { type: 'Identifier', name } }],
@@ -26,89 +30,100 @@ function buildImportsNode(imports: string[]): MdxjsEsmNode {
 }
 
 export interface ChassisAutoImportOptions {
-  /** Absolute path to the docs site root (e.g. `getDocsFsPath()`). Used for the
-   *  site-local shortcodes directory and the type definitions output path. */
-  docsPath: string
-  /** Absolute path to the directory containing `node_modules`. Defaults to
-   *  `docsPath` when omitted — override when `node_modules` lives at the repo root. */
-  modulesPath?: string
+  /**
+   * The site's root.
+   * @default process.cwd()
+   */
+  root?: string
+  /**
+   * The site's own shortcodes, relative to `root`. A component here replaces the component
+   * of the package that has the same name.
+   * @default 'src/components/shortcodes'
+   */
+  dir?: string
+  /** Names of the only shortcodes of the package to import, e.g. `['Code', 'Callout']`. */
+  include?: string[]
+  /** Names of shortcodes of the package to leave out, e.g. `['Icon']`. */
+  exclude?: string[]
+  /**
+   * Absolute path of the package's shortcodes. Found from the package's own location when
+   * omitted.
+   */
+  packageDir?: string
 }
 
-function scanComponents({ docsPath, modulesPath = docsPath }: ChassisAutoImportOptions) {
-  const dirs = [
-    path.join(modulesPath, 'node_modules/@chassis-ui/docs/src/components/shortcodes'),
-    path.join(docsPath, 'src/components/shortcodes')
-  ]
+export interface ChassisAutoImport {
+  /** Import specifiers of the components, in import order. */
+  imports: string[]
+  /** Source of a declaration file that makes the components global in MDX files. */
+  typeDefinitions: string
+  /** Factory for the remark plugin that injects the imports into every `.mdx` file. */
+  plugin: () => ReturnType<typeof createAutoImportPlugin>
+}
 
-  const components: string[] = []
-  const definitions: string[] = []
-
-  for (const dir of dirs) {
-    if (!fs.existsSync(dir)) continue
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-      if (!entry.isFile()) continue
-      components.push(`${dir}/${entry.name}`)
-      if (entry.name.endsWith('.astro')) {
-        const importPath = dir.includes('@chassis-ui/docs')
-          ? `@chassis-ui/docs/shortcodes`
-          : `@shortcodes`
-        definitions.push(
-          `export const ${entry.name.replace('.astro', '')}: typeof import('${importPath}/${entry.name}').default`
-        )
-      }
-    }
-  }
+function listFiles(directory: string): string[] {
+  if (!fs.existsSync(directory)) return []
 
-  return { components, definitions }
+  return fs
+    .readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && !entry.name.startsWith('.'))
+    .map((entry) => entry.name)
+    .sort()
 }
 
 /**
- * Astro integration that writes the auto-import type definitions file, and a
- * remark plugin factory for injecting shortcode imports into every MDX file.
- *
- * Replaces `astro-auto-import`, which triggers a deprecation warning in Astro 7.
- *
- * @example
- * ```ts
- * // astro.ts
- * const { integration, plugin } = chassisAutoImport({ docsPath: getDocsFsPath(), modulesPath: process.cwd() })
- *
- * // astro.config.ts
- * markdown: getDocsMarkdownConfig({ remarkPlugins: [plugin()] })
- * integrations: [integration()]
- * ```
+ * Finds the shortcodes of the package and of the site, and returns what is needed to import
+ * them into every MDX file. The `chassisDocs()` integration calls it. A site calls it only
+ * to build its own markdown configuration.
  */
-export function chassisAutoImport(options: ChassisAutoImportOptions): {
-  /** Astro integration that writes `src/types/auto-import.d.ts`. */
-  integration: () => AstroIntegration
-  /** Factory for the remark plugin that injects imports into every `.mdx` file. */
-  plugin: () => ReturnType<typeof createAutoImportPlugin>
-} {
-  const { components, definitions } = scanComponents(options)
-  const typeDefinitionsPath = path.join(options.docsPath, 'src/types/auto-import.d.ts')
+export function chassisAutoImport(options: ChassisAutoImportOptions = {}): ChassisAutoImport {
+  const {
+    root = process.cwd(),
+    dir = 'src/components/shortcodes',
+    include,
+    exclude = [],
+    packageDir = resolvePackageFilePath('shortcodes')
+  } = options
+
+  const siteDir = path.resolve(root, dir)
+  const siteFiles = listFiles(siteDir)
+  const siteNames = new Set(siteFiles.map(getComponentName))
+
+  const packageFiles = listFiles(packageDir).filter((file) => {
+    const name = getComponentName(file)
+
+    if (siteNames.has(name) || exclude.includes(name)) return false
+
+    return include ? include.includes(name) : true
+  })
+
+  // The package's components are imported by specifier, not by path. The path of an
+  // installed package is outside the site, where the dev server refuses to serve files.
+  const components = [
+    ...packageFiles.map((file) => ({ file, source: `@chassis-ui/docs/shortcodes/${file}` })),
+    ...siteFiles.map((file) => ({ file, source: path.join(siteDir, file) }))
+  ]
+
+  const definitions = components
+    .filter(({ file }) => file.endsWith('.astro'))
+    .map(
+      ({ file, source }) =>
+        `export const ${getComponentName(file)}: typeof import('${source}').default`
+    )
+
+  const imports = components.map(({ source }) => source)
 
   return {
-    integration: () => ({
-      name: 'chassis-auto-import',
-      hooks: {
-        'astro:config:setup': () => {
-          fs.writeFileSync(
-            typeDefinitionsPath,
-            `/**
- * DO NOT EDIT THIS FILE MANUALLY.
- *
- * This file is automatically generated by the Chassis Astro Integration.
- * It contains the type definitions for the components that are auto imported in all pages.
+    imports,
+    typeDefinitions: `/**
+ * Generated by the integration of @chassis-ui/docs.
+ * The components that are imported into every MDX file.
  */
 export declare global {
   ${definitions.join('\n  ')}
 }
-`
-          )
-        }
-      }
-    }),
-    plugin: () => createAutoImportPlugin(components)
+`,
+    plugin: () => createAutoImportPlugin(imports)
   }
 }
 

package/src/libs/snippet.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns the text between `// <kind>-docs-start <name>` and the first
+ * `// <kind>-docs-end <name>` after it, or `undefined` when the file has no such part.
+ *
+ * The end marker has to name the part exactly: the part `make-col` ends at
+ * `// scss-docs-end make-col`, not at `// scss-docs-end make-col-auto`.
+ */
+export function extractDocsSnippet(
+  content: string,
+  kind: 'js' | 'scss',
+  name: string
+): string | undefined {
+  const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const matches = content.match(
+    new RegExp(
+      `// ${kind}-docs-start ${escapedName}\\n([\\s\\S]*?)// ${kind}-docs-end ${escapedName}(?![\\w-])`
+    )
+  )
+
+  return matches?.[1] || undefined
+}

package/src/libs/source.ts

@@ -1,34 +1,11 @@
 import path from 'node:path'
-import { getConfig } from '@libs/config'
+import type { ChassisConfig } from './schema'
 
-/**
- * The part of the site's `config.yml` that says where files live, on disk and on GitHub.
- *
- * All four location keys are optional. A site that sets none of them is assumed to be built
- * from the root of its repository, with its source files in that root.
- */
-interface SourceConfig {
-  /** Repository URL (e.g. `"https://github.com/chassis-ui/css"`). */
-  repo: string
-  /** Version of the release that links to source files name. */
-  current_version: string
-  /**
-   * Directory the `file` props of `<ScssDocs>`, `<ScssDocsSimple>`, `<JsDocs>` and `<Code>` are
-   * relative to, itself relative to the working directory of the build (e.g. `"../css"` for a
-   * site in `packages/site`).
-   */
-  sourceDir?: string
-  /** The same directory from the root of the repository (e.g. `"packages/css"`). */
-  sourcePath?: string
-  /** The site's root from the root of the repository (e.g. `"packages/site"`). */
-  sitePath?: string
-  /** The branch that "View on GitHub" links to. Defaults to `"main"`. */
-  siteBranch?: string
-}
-
-function getSourceConfig(): SourceConfig {
-  return getConfig() as SourceConfig
-}
+/** The keys of `config.yml` that say where files live, on disk and on GitHub. */
+export type SourceConfig = Pick<
+  ChassisConfig,
+  'repo' | 'currentVersion' | 'siteBranch' | 'sitePath' | 'sourcePath'
+>
 
 /** Joins URL segments, skipping empty ones, and resolves any `..` in them. */
 function toUrl(segments: (string | undefined)[]): string {
@@ -37,16 +14,18 @@ function toUrl(segments: (string | undefined)[]): string {
   return new URL(url).href
 }
 
-/** Absolute path of a file or directory that a `file` prop names. */
-export function getSourceFsPath(file = ''): string {
-  return path.resolve(process.cwd(), getSourceConfig().sourceDir ?? '.', file)
+/**
+ * Absolute path of a file or directory that a `file` prop names.
+ *
+ * @param sourceDir Absolute path of the directory that `file` props are relative to.
+ */
+export function resolveSourceFsPath(sourceDir: string, file = ''): string {
+  return path.resolve(sourceDir, file)
 }
 
 /** URL of a source file on GitHub, in the tag of the current version. */
-export function getSourceUrl(file: string): string {
-  const { repo, current_version: version, sourcePath } = getSourceConfig()
-
-  return toUrl([repo, 'blob', `v${version}`, sourcePath, file])
+export function resolveSourceUrl(config: SourceConfig, file: string): string {
+  return toUrl([config.repo, 'blob', `v${config.currentVersion}`, config.sourcePath, file])
 }
 
 /**
@@ -55,8 +34,6 @@ export function getSourceUrl(file: string): string {
  * @param filePath Path of the file from the site's root, as Astro stores it in a content
  * entry's `filePath` (e.g. `"content/docs/getting-started/introduction.mdx"`).
  */
-export function getSiteFileUrl(filePath: string): string {
-  const { repo, sitePath, siteBranch = 'main' } = getSourceConfig()
-
-  return toUrl([repo, 'blob', siteBranch, sitePath, filePath])
+export function resolveSiteFileUrl(config: SourceConfig, filePath: string): string {
+  return toUrl([config.repo, 'blob', config.siteBranch, config.sitePath, filePath])
 }