starlight-theme-celestia 0.2.0

package/src/components/get-i18n-text.ts

@@ -0,0 +1,39 @@
+import type { StarlightRouteData } from "@astrojs/starlight/route-data";
+import config from "virtual:starlight/user-config";
+
+export function getI18nText(value: string | Record<string, string>, route: StarlightRouteData): string {
+  if (typeof value === "string") {
+    return value;
+  }
+
+  const { lang, locale } = route;
+
+  // Try `lang` first, which is a BCP-47 language tag
+  if (value[lang]) {
+    return value[lang];
+  }
+
+  // Use the same "root" convention as the Starlight docs to get the default value.
+  // https://github.com/withastro/starlight/blob/9d3ba179c5d524c1c61d771ceb1a7b4e754bee16/docs/src/content/docs/guides/i18n.mdx?plain=1#L72-L75
+  if (config.defaultLocale.lang === lang || config.defaultLocale.locale === locale) {
+    if (value["root"]) {
+      return value["root"];
+    }
+  }
+
+  const message =
+    `[starlight-theme-celestia] Unable to find the translation for language "${lang}".\n` +
+    `Are you using the correct BCP-47 language tag ` +
+    `(e.g. "en", "ar", or "zh-CN") in the following configuration?\n` +
+    JSON.stringify(value, null, 2) +
+    "\n";
+
+  // Fallback to the `locale`, which is a base path at which a language is
+  // served. This is not of the same format as the `lang` BCP-47 language tag.
+  if (locale && value[locale]) {
+    console.warn(message);
+    return value[locale];
+  }
+
+  throw new Error(message);
+}

package/src/components/index.ts

@@ -0,0 +1,7 @@
+export { default as Code } from "./Code.astro";
+export { default as CodeFile } from "./CodeFile.astro";
+export { default as CodePackageManagers } from "./CodePackageManagers.astro";
+export { default as CodeTabItem } from "./CodeTabItem.astro";
+export { default as CodeTabs } from "./CodeTabs.astro";
+export { default as LinkButton } from "./LinkButton.astro";
+export { default as LinkCard } from "./LinkCard.astro";

package/src/components/mobile-menu-toggle.ts

@@ -0,0 +1,49 @@
+import type { HostElement } from "@aria-ui/core";
+import { createSignal, defineCustomElement, useEffect } from "@aria-ui/core";
+import { useEventListener } from "@aria-ui/utils";
+
+function setupMobileMenuToggle(host: HostElement) {
+  const { get: getExpanded, set: setExpanded } = createSignal(false);
+
+  const toggleExpanded = () => setExpanded(!getExpanded());
+
+  useEffect(host, () => {
+    const expanded: boolean = getExpanded();
+    host.setAttribute("aria-controls", expanded ? "true" : "false");
+    document.body.toggleAttribute("data-mobile-menu-expanded", expanded || false);
+  });
+
+  useEventListener(host, "click", toggleExpanded);
+  useEventListener(host, "keydown", (event) => {
+    if (!event.isComposing && (event.key === "Enter" || event.key === " ")) {
+      event.preventDefault();
+      toggleExpanded();
+    }
+  });
+
+  useEffect(host, () => {
+    const sidebarNav = document.getElementById("celestia-sidebar-nav");
+    if (!sidebarNav) return;
+    const handleKeyup = (event: KeyboardEvent) => {
+      if (event.code === "Escape") {
+        setExpanded(false);
+        host.focus();
+      }
+    };
+    sidebarNav.addEventListener("keyup", handleKeyup);
+    return () => sidebarNav.removeEventListener("keyup", handleKeyup);
+  });
+
+  useEffect(host, () => {
+    host.setAttribute("role", "button");
+    host.setAttribute("tabindex", "0");
+  });
+}
+
+const MobileMenuToggle = defineCustomElement(setupMobileMenuToggle, {});
+
+function register() {
+  customElements.define("celestia-mobile-menu-toggle", MobileMenuToggle);
+}
+
+export { register };

package/src/components/rehype-code-tabs.ts

@@ -0,0 +1,52 @@
+import type { Element, ElementContent } from "hast";
+import { rehype } from "rehype";
+
+import { CODE_PROPERTY_CONTAINER, CODE_PROPERTY_TITLE } from "../constants";
+
+// https://github.com/withastro/starlight/blob/bdb05e704a6cf06a029367f99b6bf2f575e5a5f3/packages/starlight/user-components/rehype-tabs.ts#L20
+export const TabItemTagname = "starlight-tab-item";
+
+/**
+ * Rehype processor to extract tab panel data and turn each
+ * `<starlight-tab-item>` into a `<div>` with the necessary
+ * attributes.
+ */
+const tabsProcessor = rehype()
+  .data("settings", { fragment: true })
+  .use(() => {
+    return (tree: Element) => {
+      return {
+        ...tree,
+        children: tree.children.map(replacePre),
+      };
+    };
+  });
+
+function replacePre(node: ElementContent): ElementContent {
+  if (node.type === "element" && node.tagName === "div" && node.properties[CODE_PROPERTY_CONTAINER] != null) {
+    const title = node.properties[CODE_PROPERTY_TITLE];
+
+    if (title) {
+      node.properties[CODE_PROPERTY_TITLE] = undefined;
+      return {
+        type: "element",
+        tagName: TabItemTagname,
+        properties: {
+          dataLabel: title,
+        },
+        children: [node],
+      };
+    }
+  }
+
+  return node;
+}
+
+/**
+ * Processes the children of the `<CodeTabs>` component to transform
+ * any code blocks with "title" meta information into a <TabItem> component.
+ */
+export function processCodeTabs(html: string): string {
+  const file = tabsProcessor.processSync({ value: html });
+  return file.toString();
+}

package/src/constants.ts

@@ -0,0 +1,7 @@
+export const PAGE_TITLE_ID = "_top";
+
+// data-celestia-code-container
+export const CODE_PROPERTY_CONTAINER = "dataCelestiaCodeContainer";
+
+// data-celestia-code-title
+export const CODE_PROPERTY_TITLE = "dataCelestiaCodeTitle";

package/src/content.config.ts

@@ -0,0 +1,16 @@
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+import { defineCollection } from "astro:content";
+import type { CollectionConfig } from "astro/content/config";
+import type { Loader } from "astro/loaders";
+
+type ExtendedSchema = ReturnType<ReturnType<typeof docsSchema>>;
+
+type Docs = CollectionConfig<ExtendedSchema, Loader>;
+
+const docs: Docs = defineCollection<ExtendedSchema, Loader>({
+  loader: docsLoader(),
+  schema: docsSchema(),
+});
+
+export const collections = { docs };

package/src/content.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This file contains some types by simplifying and modifying the generated
+ * files `.astro/content.d.ts`.
+ *
+ * Normally, Astro will generate a `.astro/content.d.ts` file for an Astro app
+ * project. However, since starlight-theme-celestia is a library instead of an app,
+ * we don't have those auto-generated files.
+ */
+
+declare module "astro:content" {
+  export interface RenderResult {
+    Content: import("astro/runtime/server/index.js").AstroComponentFactory;
+  }
+}
+
+type ContentConfig = typeof import("./content.config.js");
+
+type ReturnTypeOrOriginal<T> = T extends (...args: any[]) => infer R ? R : T;
+
+export type StarlightRouteEntryData = import("astro/zod").infer<
+  ReturnTypeOrOriginal<Required<ContentConfig["collections"]["docs"]>["schema"]>
+>;

package/src/icons/lucide-arrow-left.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="m12 19l-7-7l7-7m7 7H5"/></svg>

package/src/icons/lucide-arrow-right.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 12h14m-7-7l7 7l-7 7"/></svg>

package/src/icons/lucide-check.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20 6L9 17l-5-5"/></svg>

package/src/icons/lucide-chevron-left.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="m15 18l-6-6l6-6"/></svg>

package/src/icons/lucide-chevron-right.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="m9 18l6-6l-6-6"/></svg>

package/src/icons/lucide-clipboard.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><rect width="8" height="4" x="8" y="2" rx="1" ry="1"/><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/></g></svg>

package/src/icons/lucide-menu.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 5h16M4 12h16M4 19h16"/></svg>

package/src/icons/lucide-search.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><g fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"><path d="m21 21l-4.34-4.34"/><circle cx="11" cy="11" r="8"/></g></svg>

package/src/icons/lucide-x.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Lucide by Lucide Contributors - https://github.com/lucide-icons/lucide/blob/main/LICENSE --><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M18 6L6 18M6 6l12 12"/></svg>

package/src/icons/tabler-moon-filled.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Tabler Icons by Paweł Kuna - https://github.com/tabler/tabler-icons/blob/master/LICENSE --><path fill="currentColor" d="M12 1.992a10 10 0 1 0 9.236 13.838c.341-.82-.476-1.644-1.298-1.31a6.5 6.5 0 0 1-6.864-10.787l.077-.08c.551-.63.113-1.653-.758-1.653h-.266l-.068-.006z"/></svg>

package/src/icons/tabler-sun-high-filled.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24"><!-- Icon from Tabler Icons by Paweł Kuna - https://github.com/tabler/tabler-icons/blob/master/LICENSE --><path fill="currentColor" d="M12 19a1 1 0 0 1 1 1v2a1 1 0 0 1-2 0v-2a1 1 0 0 1 1-1m-4.95-2.05a1 1 0 0 1 0 1.414l-1.414 1.414a1 1 0 1 1-1.414-1.414l1.414-1.414a1 1 0 0 1 1.414 0m11.314 0l1.414 1.414a1 1 0 0 1-1.414 1.414l-1.414-1.414a1 1 0 0 1 1.414-1.414m-5.049-9.836a5 5 0 1 1-2.532 9.674a5 5 0 0 1 2.532-9.674M4 11a1 1 0 0 1 0 2H2a1 1 0 0 1 0-2zm18 0a1 1 0 0 1 0 2h-2a1 1 0 0 1 0-2zM5.636 4.222L7.05 5.636A1 1 0 0 1 5.636 7.05L4.222 5.636a1 1 0 0 1 1.414-1.414m14.142 0a1 1 0 0 1 0 1.414L18.364 7.05a1 1 0 0 1-1.414-1.414l1.414-1.414a1 1 0 0 1 1.414 0M12 1a1 1 0 0 1 1 1v2a1 1 0 0 1-2 0V2a1 1 0 0 1 1-1"/></svg>

package/src/index.ts

@@ -0,0 +1,112 @@
+import type { StarlightConfig, StarlightPlugin, StarlightUserConfig } from "@astrojs/starlight/types";
+import type { AstroConfig } from "astro";
+import remarkCustomHeaderId from "remark-custom-header-id";
+
+import { createShikiConfig } from "./shiki-config";
+import type { ThemeCelestiaOptions } from "./user-options";
+import { vitePluginUserConfig } from "./virtual-user-config";
+
+const components = {
+  Header: "starlight-theme-celestia/components/Header.astro",
+  Search: "starlight-theme-celestia/components/Search.astro",
+  ThemeProvider: "starlight-theme-celestia/components/ThemeProvider.astro",
+  ThemeSelect: "starlight-theme-celestia/components/ThemeSelect.astro",
+  SocialIcons: "starlight-theme-celestia/components/SocialIcons.astro",
+  SiteTitle: "starlight-theme-celestia/components/SiteTitleVersioned.astro",
+  PageFrame: "starlight-theme-celestia/components/PageFrame.astro",
+  Pagination: "starlight-theme-celestia/components/Pagination.astro",
+  MobileMenuToggle: "starlight-theme-celestia/components/MobileMenuToggle.astro",
+  TwoColumnContent: "starlight-theme-celestia/components/TwoColumnContent.astro",
+  MarkdownContent: "starlight-theme-celestia/components/MarkdownContent.astro",
+  Hero: "starlight-theme-celestia/components/Hero.astro",
+  MobileTableOfContents: "starlight-theme-celestia/components/MobileTableOfContents.astro",
+  MobileMenuFooter: "starlight-theme-celestia/components/MobileMenuFooter.astro",
+  LanguageSelect: "starlight-theme-celestia/components/LanguageSelect.astro",
+  Head: "starlight-theme-celestia/components/Head.astro",
+} as const satisfies Partial<StarlightConfig["components"]>;
+
+export type { ThemeCelestiaOptions };
+
+export default function starlightCelestiaTheme(options: ThemeCelestiaOptions = {}): StarlightPlugin {
+  return {
+    name: "starlight-theme-celestia",
+    hooks: {
+      setup: async ({ config, updateConfig, addIntegration, astroConfig }) => {
+        let useTailwind: boolean;
+
+        if (options.stylingSystem === "css") {
+          useTailwind = false;
+        } else if (options.stylingSystem === "tailwind") {
+          useTailwind = true;
+        } else {
+          const hasTailwindcss = await checkHasPlugin(astroConfig.vite?.plugins, "tailwind");
+          useTailwind = hasTailwindcss;
+        }
+
+        const newConfig = {
+          customCss: [
+            "starlight-theme-celestia/layer.css",
+
+            useTailwind ? "" : "starlight-theme-celestia/tailwind.gen.css",
+
+            "starlight-theme-celestia/theme.css",
+
+            ...(config.customCss || []),
+
+            "starlight-theme-celestia/styles.css",
+          ].filter(Boolean),
+          components: {
+            ...components,
+            ...config.components,
+          },
+          expressiveCode: config.expressiveCode ?? false,
+        } satisfies Partial<StarlightUserConfig>;
+
+        updateConfig(newConfig);
+
+        addIntegration({
+          name: "starlight-theme-celestia-integration",
+          hooks: {
+            "astro:config:setup": ({ updateConfig }) => {
+              updateConfig({
+                markdown: {
+                  shikiConfig: createShikiConfig({ twoslash: true }),
+                  remarkPlugins: [remarkCustomHeaderId],
+                },
+                vite: {
+                  plugins: [
+                    vitePluginUserConfig({
+                      nav: options.nav,
+                      rootHref: astroConfig.root.toString(),
+                    }),
+                  ],
+                },
+              });
+            },
+          },
+        });
+      },
+    },
+  };
+}
+
+type ViteUserConfig = AstroConfig["vite"];
+type VitePlugin = NonNullable<ViteUserConfig["plugins"]>[number];
+
+async function checkHasPlugin(plugin: VitePlugin | Promise<VitePlugin>, search: string): Promise<boolean> {
+  const awaited = await plugin;
+
+  if (!awaited) {
+    return false;
+  }
+  if (Array.isArray(awaited)) {
+    for (const p of awaited) {
+      if (await checkHasPlugin(p, search)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  const name = awaited.name || "";
+  return name.includes(search);
+}

package/src/shiki-config.ts

@@ -0,0 +1,49 @@
+import {
+  transformerMetaHighlight,
+  transformerMetaWordHighlight,
+  transformerNotationDiff,
+  transformerRemoveNotationEscape,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight,
+} from "@shikijs/transformers";
+import { transformerTwoslash } from "@shikijs/twoslash";
+import type { ShikiTransformer } from "@shikijs/types";
+import type { ShikiConfig } from "astro";
+import { createRenderer } from "shiki-twoslash-renderer";
+
+import { transformerContainer } from "./shiki-transformer-container";
+
+export function createShikiConfig(options: { twoslash: boolean }): ShikiConfig {
+  const transformers: ShikiTransformer[] = [
+    transformerMetaHighlight(),
+    transformerMetaWordHighlight(),
+    transformerNotationDiff(),
+    transformerNotationHighlight(),
+    transformerNotationWordHighlight(),
+    transformerRemoveNotationEscape(),
+
+    transformerContainer(),
+    ...(options.twoslash
+      ? [
+          transformerTwoslash({
+            renderer: createRenderer(),
+            explicitTrigger: true,
+            twoslashOptions: {
+              compilerOptions: {
+                noUncheckedSideEffectImports: false,
+              },
+            },
+          }),
+        ]
+      : []),
+  ];
+
+  return {
+    themes: {
+      light: "one-light",
+      dark: "github-dark-dimmed",
+    },
+    defaultColor: false,
+    transformers: transformers,
+  };
+}

package/src/shiki-meta-title.ts

@@ -0,0 +1,6 @@
+export function parseTitleString(meta: string): string | null {
+  if (!meta) return null;
+  const match = meta.match(/title="([^"]+)"/);
+  if (!match) return null;
+  return match[1];
+}

package/src/shiki-transformer-container.ts

@@ -0,0 +1,85 @@
+import type { ShikiTransformer } from "@shikijs/types";
+import type { ElementContent, RootContent } from "hast";
+import { isElement } from "hast-util-is-element";
+
+import { CODE_PROPERTY_CONTAINER, CODE_PROPERTY_TITLE } from "./constants";
+import { parseTitleString } from "./shiki-meta-title";
+
+const name = "starlight-theme-celestia-shiki-transformer-container";
+
+/**
+ * A transformer to wrap code blocks in a container.
+ */
+export function transformerContainer(): ShikiTransformer {
+  return {
+    name: name,
+    root(node) {
+      if (node.children.length === 0) {
+        throw new Error(`[${name}] Expected at least one child`);
+      }
+
+      const pre = node.children.find((child) => isElement(child, "pre"));
+
+      if (!pre) {
+        throw new Error(`[${name}] Expected a <pre> element in the root node but got ${JSON.stringify(node)}`);
+      }
+
+      const title = parseTitleString(this.options.meta?.__raw || "");
+
+      const children: ElementContent[] = normalizeContent(node.children);
+
+      if (title) {
+        children.unshift({
+          type: "element",
+          tagName: "div",
+          properties: {
+            class:
+              "hidden border-b border-solid border-b-(--sl-color-gray-5) bg-(--sl-color-bg) px-4 py-2 font-mono text-sm text-(--sl-color-gray-3) [div[data-celestia-code-container][data-celestia-code-title]_&]:block",
+          },
+          children: [
+            {
+              type: "text",
+              value: title,
+            },
+          ],
+        });
+      }
+
+      node.children = [
+        {
+          type: "element",
+          tagName: "div",
+          properties: {
+            [CODE_PROPERTY_CONTAINER]: "",
+            [CODE_PROPERTY_TITLE]: title || undefined,
+            class:
+              "not-content relative overflow-hidden [&_pre]:relative [&_celestia-code-copy-button]:opacity-0 [&:hover_celestia-code-copy-button]:opacity-100 border border-solid border-(--sl-color-gray-5) rounded-md",
+          },
+          children: [
+            ...children,
+            {
+              type: "element",
+              tagName: "celestia-code-copy-button",
+              properties: {
+                type: "button",
+                "data-code": this.source,
+                title: "Copy code",
+                "aria-label": "Copy code",
+                class:
+                  "absolute top-2 right-2 m-0 size-6 rounded border border-solid border-(--sl-color-gray-5) bg-gray-100/30 p-1 text-black backdrop-blur-sm transition hover:bg-gray-200/50 active:scale-90 dark:bg-gray-600/30 dark:text-white hover:dark:bg-gray-500/50",
+              },
+              children: [],
+            },
+          ],
+        },
+      ];
+
+      return node;
+    },
+  };
+}
+
+// A simple function to make typescript happy
+function normalizeContent(children: RootContent[]): ElementContent[] {
+  return children.filter((child) => child.type !== "doctype");
+}

package/src/types.d.ts

@@ -0,0 +1,2 @@
+import "astro/client";
+import "@astrojs/starlight";

package/src/user-options.ts

@@ -0,0 +1,37 @@
+export interface NavItem {
+  /**
+   * The visible label for this item in the navigation. It could be a string or
+   * a record of strings with the language code as the key.
+   */
+  label: string | Record<string, string>;
+  /**
+   * The link to this item's content. It could be a string or a record of
+   * strings with the language code as the key.
+   */
+  href: string | Record<string, string>;
+}
+
+export interface ThemeCelestiaOptions {
+  nav?: NavItem[];
+
+  /**
+   * `starlight-theme-celestia` supports two styling systems: pure CSS and Tailwind
+   * CSS.
+   *
+   * By default, `starlight-theme-celestia` will detect if Tailwind CSS is passed to
+   * the Astro config, and use Tailwind CSS if it is. You can also force the
+   * theme to use a specific styling system by setting the `stylingSystem`
+   * option to `css` or `tailwind`.
+   *
+   * @default "detect"
+   */
+  stylingSystem?: "css" | "tailwind" | "detect";
+}
+
+/**
+ * @internal
+ */
+export interface ConfigSerialized {
+  nav?: NavItem[];
+  rootHref: string;
+}

package/src/virtual-internal.d.ts

@@ -0,0 +1,44 @@
+// Copied from https://github.com/withastro/starlight/blob/9d3ba179c5d524c1c61d771ceb1a7b4e754bee16/packages/starlight/virtual-internal.d.ts#L25
+declare module "virtual:starlight/pagefind-config" {
+  import type { StarlightConfig } from "@astrojs/starlight/types";
+
+  export const pagefindUserConfig: Partial<Extract<StarlightConfig["pagefind"], object>>;
+}
+
+declare module "virtual:starlight-theme-celestia/user-config" {
+  const config: import("./user-options").ConfigSerialized;
+  export default config;
+}
+declare module "virtual:starlight-versions-config" {
+  export interface ConfigSerialized {
+    current: { label: string; redirect?: "same-page" | "root" };
+    versions: Array<{ slug: string; label?: string; redirect?: "same-page" | "root" }>;
+    versionsBySlug: Record<string, unknown>;
+  }
+  const config: ConfigSerialized;
+  export default config;
+}
+declare module "virtual:starlight/components/Search" {
+  const Search: typeof import("./components/Search.astro").default;
+  export default Search;
+}
+declare module "virtual:starlight/components/SiteTitle" {
+  const SiteTitle: typeof import("./components/SiteTitle.astro").default;
+  export default SiteTitle;
+}
+declare module "virtual:starlight/components/SocialIcons" {
+  const SocialIcons: typeof import("./components/SocialIcons.astro").default;
+  export default SocialIcons;
+}
+declare module "virtual:starlight/components/ThemeSelect" {
+  const ThemeSelect: typeof import("./components/ThemeSelect.astro").default;
+  export default ThemeSelect;
+}
+declare module "virtual:starlight/components/LanguageSelect" {
+  const LanguageSelect: typeof import("./components/LanguageSelect.astro").default;
+  export default LanguageSelect;
+}
+declare module "virtual:starlight/components/MobileMenuFooter" {
+  const MobileMenuFooter: typeof import("./components/MobileMenuFooter.astro").default;
+  export default MobileMenuFooter;
+}

package/src/virtual-user-config.ts

@@ -0,0 +1,44 @@
+import type { ViteUserConfig } from "astro";
+
+import type { ConfigSerialized } from "./user-options";
+
+function resolveVirtualModuleId<T extends string>(id: T): `\0${T}` {
+  return `\0${id}`;
+}
+
+const VERSIONS_VIRTUAL_ID = "virtual:starlight-versions-config";
+const VERSIONS_FALLBACK = `export default ${JSON.stringify({
+  current: { label: "latest", redirect: "root" },
+  versions: [],
+  versionsBySlug: {},
+})}`;
+
+/** Vite plugin that exposes user config via virtual modules. */
+export function vitePluginUserConfig(config: ConfigSerialized): NonNullable<ViteUserConfig["plugins"]>[number] {
+  /** Map of virtual module names to their code contents as strings. */
+  const modules = {
+    "virtual:starlight-theme-celestia/user-config": `export default ${JSON.stringify(config)}`,
+  } satisfies Record<string, string>;
+
+  /** Mapping names prefixed with `\0` to their original form. */
+  const resolutionMap = Object.fromEntries(
+    (Object.keys(modules) as (keyof typeof modules)[]).map((key) => [resolveVirtualModuleId(key), key]),
+  );
+
+  return {
+    name: "vite-plugin-starlight-theme-celestia-user-config",
+    // enforce 'post' so starlight-versions' real config takes precedence over our fallback
+    enforce: "post" as const,
+    resolveId(id): string | void {
+      if (id in modules) return resolveVirtualModuleId(id);
+      // Fallback for virtual:starlight-versions-config when the plugin isn't configured
+      if (id === VERSIONS_VIRTUAL_ID) return resolveVirtualModuleId(id);
+    },
+    load(id): string | void {
+      const resolution = resolutionMap[id];
+      if (resolution) return modules[resolution];
+      // Provide empty fallback if starlight-versions plugin didn't load
+      if (id === resolveVirtualModuleId(VERSIONS_VIRTUAL_ID)) return VERSIONS_FALLBACK;
+    },
+  };
+}