@chassis-ui/docs 0.5.1 → 0.6.0-next.0

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])
 }

package/src/libs/toc.ts

@@ -37,7 +37,9 @@ export function generateToc(allHeadings: MarkdownHeading[], config: TocConfig):
 
     const previousEntry = toc[toc.length - 1]
 
-    if (heading.depth === previousEntry.depth) {
+    // A heading at the depth of the previous top-level entry, or shallower, starts a new
+    // top-level entry. A page whose first heading is an `<h3>` has later `<h2>`s here.
+    if (heading.depth <= previousEntry.depth) {
       toc.push({ ...heading, children: [] })
       continue
     }

package/src/scss/_vars.scss

@@ -1,4 +1,7 @@
-// Local docs variables
+// The Sass variables and custom properties of the docs.
+//
+// This partial is public: a site may `@use "@chassis-ui/docs/scss/vars"` in its own
+// stylesheets. Removing or renaming a variable is a breaking change.
 @use "@chassis-ui/css/scss/functions" as *;
 @use "@chassis-ui/css/scss/mixins" as *;
 

package/src/site.ts

@@ -0,0 +1,150 @@
+// What pages and components read from the site. It is backed by the modules that the
+// integration provides, so it works only in code that Astro renders: not in
+// `astro.config.ts`, and not in the browser.
+
+import path from 'node:path'
+import type { z } from 'astro/zod'
+import config from 'virtual:chassis-docs/config'
+import sidebar from 'virtual:chassis-docs/sidebar'
+import * as paths from 'virtual:chassis-docs/paths'
+import { getCollection, getEntry, type render } from 'astro:content'
+import { loadData } from './libs/config'
+import { joinDocsPath } from './libs/docs-path'
+import { getNodeModulesFsPaths, resolvePackageFilePath } from './libs/paths'
+import { replaceConfigInText, replaceDocsrefInText } from './libs/remark'
+import type { ChassisConfig, DocsPage, Sidebar } from './libs/schema'
+import { resolveSiteFileUrl, resolveSourceFsPath, resolveSourceUrl } from './libs/source'
+
+/**
+ * The parsed `config.yml`.
+ *
+ * A site with keys of its own names its config type: `getConfig<SiteConfig>()`, where
+ * `SiteConfig` is inferred from the schema that the site passes to the integration.
+ */
+export function getConfig<TConfig extends ChassisConfig = ChassisConfig>(): TConfig {
+  return config as TConfig
+}
+
+/** The parsed `data/sidebar.yml`. Empty when the site has no sidebar file. */
+export function getSidebar(): Sidebar {
+  return sidebar
+}
+
+/** URL path of a docs page, e.g. `getDocsPath('/components/button/')`. */
+export function getDocsPath(inputPath: string): string {
+  return joinDocsPath(config.docsPath, inputPath)
+}
+
+/** Absolute path of the site's root: the directory that holds `astro.config.ts`. */
+export function getSiteRoot(): string {
+  return paths.root
+}
+
+/** Absolute path of a file in the site's root. */
+export function getSiteFsPath(file = ''): string {
+  return path.resolve(paths.root, file)
+}
+
+/** Absolute path of a file in the site's `public` directory. */
+export function getPublicFsPath(file = ''): string {
+  return path.join(paths.publicDir, file)
+}
+
+/** Absolute path of a file or directory that a `file` prop names. */
+export function getSourceFsPath(file = ''): string {
+  return resolveSourceFsPath(paths.sourceDir, file)
+}
+
+/** URL of a source file on GitHub, in the tag of the current version. */
+export function getSourceUrl(file: string): string {
+  return resolveSourceUrl(config, file)
+}
+
+/** URL of a file of the site on GitHub, on the site's branch. */
+export function getSiteFileUrl(filePath: string): string {
+  return resolveSiteFileUrl(config, filePath)
+}
+
+/**
+ * Absolute path of a file of the package, named by its public path, e.g.
+ * `getPackageFilePath('js/color-modes.js')`.
+ */
+export function getPackageFilePath(file: string): string {
+  return resolvePackageFilePath(file, paths.packageRoot)
+}
+
+/** The `node_modules` directories that the site resolves packages from, nearest first. */
+export function getNodeModulesPaths(): string[] {
+  return getNodeModulesFsPaths(paths.root)
+}
+
+/**
+ * Returns a `getData(name)` function for the site's own data files. Each key of
+ * `definitions` is the name of a YAML file in `dir`, and its value is the schema of the file.
+ *
+ * @example
+ * ```ts
+ * import { createDataLoader } from '@chassis-ui/docs/site'
+ * import { z } from '@chassis-ui/docs/schema'
+ *
+ * export const getData = createDataLoader({
+ *   breakpoints: z.object({ name: z.string() }).array()
+ * })
+ * ```
+ */
+export function createDataLoader<TDefinitions extends Record<string, z.ZodType>>(
+  definitions: TDefinitions,
+  options: { dir?: string } = {}
+) {
+  const cache = new Map<keyof TDefinitions, unknown>()
+
+  return function getData<TName extends keyof TDefinitions & string>(
+    name: TName
+  ): z.infer<TDefinitions[TName]> {
+    if (!cache.has(name)) {
+      cache.set(
+        name,
+        loadData({
+          file: path.join(options.dir ?? 'data', `${name}.yml`),
+          root: paths.root,
+          schema: definitions[name]
+        })
+      )
+    }
+
+    return cache.get(name) as z.infer<TDefinitions[TName]>
+  }
+}
+
+type RenderableEntry = Parameters<typeof render>[0]
+
+// The package cannot know the collections of the site, so their names are not type-checked.
+const getSiteCollection = getCollection as unknown as (_name: string) => Promise<DocsPage[]>
+const getSiteEntry = getEntry as unknown as (
+  _collection: string,
+  _id: string
+) => Promise<RenderableEntry | undefined>
+
+let docsPages: Promise<DocsPage[]> | undefined
+
+/** The entries of the site's `docs` collection. */
+export function getDocsPages(): Promise<DocsPage[]> {
+  docsPages ??= getSiteCollection('docs')
+
+  return docsPages
+}
+
+/** An entry of the site's `callouts` collection, or `undefined` when there is none. */
+export function getCallout(name: string): Promise<RenderableEntry | undefined> {
+  return getSiteEntry('callouts', name)
+}
+
+/** Replaces each `[[config:key]]` in `text` with the value of that key of `config.yml`. */
+export function resolveConfigRefs(text: string): string {
+  return replaceConfigInText(text, config)
+}
+
+/** Replaces each `[[docsref:/path]]` in `text` with the URL path of that docs page. */
+export function resolveDocsrefs(text: string): string {
+  return replaceDocsrefInText(text, { docsPath: config.docsPath })
+}