starlight-theme-celestia 0.2.0

package/lib/theme.css

@@ -0,0 +1,94 @@
+:root,
+::backdrop {
+  --sl-content-width: 55rem;
+  --sl-sidebar-width: 17rem;
+  --sl-font: "Inter", system-ui, sans-serif;
+
+  /* Prevent adjustments of font size after orientation changes in iOS. */
+  -webkit-text-size-adjust: 100%;
+}
+
+/* Dark mode Starlight theme variables (default). */
+:root {
+  --sl-color-white: white;
+  --sl-color-gray-1: var(--color-gray-200);
+  --sl-color-gray-2: var(--color-gray-300);
+  --sl-color-gray-3: var(--color-gray-400);
+  --sl-color-gray-4: var(--color-gray-600);
+  --sl-color-gray-5: var(--color-gray-700);
+  --sl-color-gray-6: var(--color-gray-800);
+  --sl-color-black: var(--color-gray-950);
+
+  --sl-color-bg-inline-code: var(--color-gray-800);
+  --sl-color-border-inline-code: var(--color-gray-700);
+  --sl-color-bg-nav: color-mix(in oklch, var(--color-gray-950) 50%, transparent);
+
+  --sl-color-orange-low: var(--color-amber-950);
+  --sl-color-orange: var(--color-amber-900);
+  --sl-color-orange-high: var(--color-amber-200);
+
+  --sl-color-green-low: var(--color-green-950);
+  --sl-color-green: var(--color-green-900);
+  --sl-color-green-high: var(--color-green-200);
+
+  --sl-color-blue-low: var(--color-blue-950);
+  --sl-color-blue: var(--color-blue-900);
+  --sl-color-blue-high: var(--color-blue-200);
+
+  --sl-color-purple-low: var(--color-purple-950);
+  --sl-color-purple: var(--color-purple-900);
+  --sl-color-purple-high: var(--color-purple-200);
+
+  --sl-color-red-low: var(--color-red-950);
+  --sl-color-red: var(--color-red-900);
+  --sl-color-red-high: var(--color-red-200);
+
+  --nano-color-highlight: var(--sl-color-gray-5);
+}
+
+/* Light mode Starlight theme variables */
+:root[data-theme="light"] {
+  --sl-color-white: var(--color-gray-900);
+  --sl-color-gray-1: var(--color-gray-800);
+  --sl-color-gray-2: var(--color-gray-700);
+  --sl-color-gray-3: var(--color-gray-500);
+  --sl-color-gray-4: var(--color-gray-400);
+  --sl-color-gray-5: var(--color-gray-300);
+  --sl-color-gray-6: var(--color-gray-200);
+  --sl-color-gray-7: var(--color-gray-100);
+  --sl-color-black: white;
+
+  --sl-color-bg-inline-code: var(--color-gray-100);
+  --sl-color-border-inline-code: var(--color-gray-300);
+  --sl-color-bg-nav: color-mix(in oklch, var(--color-white) 80%, transparent);
+
+  --sl-color-orange-low: var(--color-amber-100);
+  --sl-color-orange: var(--color-amber-400);
+  --sl-color-orange-high: var(--color-amber-800);
+
+  --sl-color-green-low: var(--color-green-100);
+  --sl-color-green: var(--color-green-400);
+  --sl-color-green-high: var(--color-green-800);
+
+  --sl-color-blue-low: var(--color-blue-100);
+  --sl-color-blue: var(--color-blue-400);
+  --sl-color-blue-high: var(--color-blue-800);
+
+  --sl-color-purple-low: var(--color-purple-100);
+  --sl-color-purple: var(--color-purple-400);
+  --sl-color-purple-high: var(--color-purple-800);
+
+  --sl-color-red-low: var(--color-red-100);
+  --sl-color-red: var(--color-red-400);
+  --sl-color-red-high: var(--color-red-800);
+
+  --nano-color-highlight: var(--sl-color-gray-6);
+}
+
+.sl-markdown-content [data-celestia-code-container] pre.astro-code,
+.sl-markdown-content [data-celestia-code-container] pre.astro-code code {
+  border-width: 0;
+  border-style: solid;
+  border-color: transparent;
+  border-radius: 0;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "starlight-theme-celestia",
+  "type": "module",
+  "version": "0.2.0",
+  "description": "A clean, modern theme for Astro Starlight",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*.css": "./lib/*.css",
+    "./components": "./src/components/index.ts",
+    "./components/*.astro": "./src/components/*.astro"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun run build:tailwindcss",
+    "build:tailwindcss": "tailwindcss -i ./lib/tailwind.build.css -o ./lib/tailwind.gen.css"
+  },
+  "dependencies": {
+    "@aria-ui/core": "^0.2.0",
+    "@aria-ui/utils": "^0.1.5",
+    "@fontsource/inter": "^5.0.0",
+    "@lorenzo_lewis/starlight-utils": "^0.3.0",
+    "@pagefind/default-ui": "^1.5.2",
+    "@shikijs/transformers": "^4.0.2",
+    "@shikijs/twoslash": "^4.0.2",
+    "@shikijs/types": "^4.0.2",
+    "@types/hast": "^3.0.4",
+    "hast-util-is-element": "^3.0.0",
+    "rehype": "^13.0.2",
+    "remark-custom-header-id": "^1.0.0",
+    "shiki-twoslash-renderer": "^0.3.3",
+    "starlight-versions": "^0.8.0"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": "*"
+  },
+  "peerDependenciesMeta": {
+    "@astrojs/starlight": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "^0.38.3",
+    "@tailwindcss/cli": "^4.2.2",
+    "@tailwindcss/vite": "^4.2.2",
+    "@types/node": "^20.17.30",
+    "astro": "^6.1.6",
+    "tailwindcss": "^4.2.2",
+    "typescript": "^5.9.3"
+  }
+}

package/src/astro.d.ts

@@ -0,0 +1,6 @@
+declare module "*.astro" {
+  import type { AstroComponentFactory } from "astro/runtime/server/index.js";
+
+  const content: AstroComponentFactory;
+  export default content;
+}

package/src/components/Code.astro

@@ -0,0 +1,12 @@
+---
+import type { ComponentProps } from 'astro/types'
+import { Code as CodeComponent } from 'astro:components'
+import { createShikiConfig } from '../shiki-config'
+
+type Props = ComponentProps<typeof CodeComponent>
+
+// For unknown reasons, enabling twoslash breaks the build, thus twoslash is disabled here.
+const shikiConfig = createShikiConfig({ twoslash: false })
+---
+
+<CodeComponent {...shikiConfig} {...Astro.props} />

package/src/components/CodeCopy.astro

@@ -0,0 +1,39 @@
+<script>
+  import ClipboardIcon from '../icons/lucide-clipboard.svg?raw'
+  import CheckIcon from '../icons/lucide-check.svg?raw'
+
+  class CodeCopyButton extends HTMLElement {
+    constructor() {
+      super()
+    }
+
+    connectedCallback() {
+      const update = () => {
+        const iconHtml = state === 'ready' ? ClipboardIcon : CheckIcon
+        this.innerHTML =
+          '<span class="w-full h-full block [&_svg]:w-full [&_svg]:h-full">' +
+          iconHtml +
+          '</span>'
+      }
+
+      let state: 'ready' | 'success' = 'ready'
+      update()
+
+      this.addEventListener('click', () => {
+        if (state === 'ready') {
+          state = 'success'
+          update()
+
+          const code = this.dataset.code || ''
+          void navigator.clipboard.writeText(code)
+          setTimeout(() => {
+            state = 'ready'
+            update()
+          }, 1500)
+        }
+      })
+    }
+  }
+
+  customElements.define('celestia-code-copy-button', CodeCopyButton)
+</script>

package/src/components/CodeFile.astro

@@ -0,0 +1,64 @@
+---
+import type { ComponentProps } from 'astro/types'
+import { existsSync } from 'node:fs'
+import fs from 'node:fs/promises'
+import { basename } from 'node:path'
+import Code from './Code.astro'
+import config from 'virtual:starlight-theme-celestia/user-config'
+import { fileURLToPath } from 'node:url'
+
+type CodeProps = ComponentProps<typeof Code>
+
+interface Props extends Omit<CodeProps, 'code' | 'lang'> {
+  /**
+   * The file path relative to the project root.
+   */
+  path: string
+
+  /**
+   * The title of the file. If not provided, the file name will be used.
+   */
+  title?: string
+
+  /**
+   * The language of the file. If not provided, the file extension will be used.
+   */
+  lang?: CodeProps['lang']
+}
+
+const { path, title, lang, meta, ...rest } = Astro.props
+
+if (!path) {
+  throw new Error('path is required for <CodeFile> component')
+}
+
+const root = new URL(config.rootHref)
+const url = new URL(path, root)
+const absolutePath = fileURLToPath(url)
+if (!existsSync(absolutePath)) {
+  throw new Error(`Unable to find file ${absolutePath}`)
+}
+
+let code: string
+try {
+  code = await fs.readFile(absolutePath, 'utf-8')
+} catch (error) {
+  throw new Error(`Unable to read file ${absolutePath}: ${error}`, {
+    cause: error,
+  })
+}
+
+let fileName = basename(path)
+let defaultLang = (fileName.split('.').pop() || 'plaintext') as 'plaintext'
+let defaultTitle = fileName
+let titleMeta = `title="${title || defaultTitle}"`
+
+const codeProps: CodeProps = {
+  ...rest,
+  lang: lang ?? defaultLang,
+  meta: meta ? `${meta} ${titleMeta}` : titleMeta,
+  code,
+}
+---
+
+<Code {...codeProps} />

package/src/components/CodePackageManagers.astro

@@ -0,0 +1,55 @@
+---
+import { CodeTabItem, CodeTabs } from 'starlight-theme-celestia/components'
+
+type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun'
+
+interface Props {
+  /**
+   * The package managers to use.
+   *
+   * @default ['pnpm', 'npm', 'yarn', 'bun']
+   */
+  packageManagers?: PackageManager[]
+
+  /**
+   * The packages to install. If you want to install multiple packages, you can pass a space-separated string.
+   */
+  packages: string
+
+  /**
+   * Whether to install the packages as dev dependencies.
+   *
+   * @default false
+   */
+  dev?: boolean
+}
+
+const props: Props = Astro.props
+
+const packageManagers = props.packageManagers ?? ['pnpm', 'npm', 'yarn', 'bun']
+
+function getCode(packageManager: PackageManager) {
+  const parts: string[] = [
+    {
+      pnpm: 'pnpm add',
+      npm: 'npm install',
+      yarn: 'yarn add',
+      bun: 'bun add',
+    }[packageManager],
+
+    props.dev ? '-D' : '',
+
+    props.packages,
+  ]
+
+  return parts.filter(Boolean).join(' ')
+}
+---
+
+<CodeTabs syncKey="code-group-installation">
+  {
+    packageManagers.map((pkg) => (
+      <CodeTabItem label={pkg} lang="shell" code={getCode(pkg)} />
+    ))
+  }
+</CodeTabs>

package/src/components/CodeTabItem.astro

@@ -0,0 +1,13 @@
+---
+import { TabItem } from '@astrojs/starlight/components'
+import Code from './Code.astro'
+import type { ComponentProps } from 'astro/types'
+
+type Props = { label: string } & ComponentProps<typeof Code>
+
+const { label, ...codeProps } = Astro.props
+---
+
+<TabItem label={label}>
+  <Code {...codeProps} />
+</TabItem>

package/src/components/CodeTabs.astro

@@ -0,0 +1,67 @@
+---
+import { Tabs } from '@astrojs/starlight/components'
+import { processCodeTabs } from './rehype-code-tabs'
+
+interface Props {
+  border?: boolean
+  syncKey?: string
+}
+
+const { border = true, syncKey } = Astro.props
+
+const originalHtml = await Astro.slots.render('default')
+const processedHtml = processCodeTabs(originalHtml)
+---
+
+<div class:list={['code-tabs', border ? 'code-tabs-border' : undefined]}>
+  <Tabs syncKey={syncKey}>
+    <Fragment set:html={processedHtml} />
+  </Tabs>
+</div>
+
+<style is:global>
+  @layer utilities {
+    .sl-markdown-content .code-tabs {
+      &.code-tabs-border {
+        border-color: var(--sl-color-gray-5);
+        border-width: 1px;
+        border-style: solid;
+        border-radius: 0.5rem;
+      }
+
+      [role='tablist'] {
+        border-bottom-width: 1px;
+      }
+
+      .tablist-wrapper {
+        [role='tab'] {
+          font-family: var(--sl-font-system-mono);
+          padding-top: 0.6rem;
+          padding-bottom: 0.6rem;
+          padding-left: 0.75rem;
+          padding-right: 0.75rem;
+          font-size: 0.875rem;
+          white-space: nowrap;
+        }
+      }
+
+      starlight-tabs {
+        margin-top: 0rem;
+      }
+
+      div[role='tabpanel'] {
+        margin: 0;
+      }
+
+      .astro-code {
+        border-radius: 0;
+      }
+
+      [data-celestia-code-container] {
+        border-radius: 0;
+        border-width: 0;
+        border-color: transparent;
+      }
+    }
+  }
+</style>

package/src/components/Head.astro

@@ -0,0 +1,7 @@
+---
+import Default from "@astrojs/starlight/components/Head.astro";
+import { ClientRouter } from "astro:transitions";
+---
+
+<Default />
+<ClientRouter />

package/src/components/Header.astro

@@ -0,0 +1,91 @@
+---
+const { hasSidebar } = Astro.locals.starlightRoute
+
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect'
+import Search from 'virtual:starlight/components/Search'
+import SiteTitle from 'virtual:starlight/components/SiteTitle'
+import SocialIcons from 'virtual:starlight/components/SocialIcons'
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect'
+
+import options from 'virtual:starlight-theme-celestia/user-config'
+import MobileMenuToggle from './MobileMenuToggle.astro'
+import { getI18nText } from './get-i18n-text'
+
+const nav = options.nav ?? []
+
+const route = Astro.locals.starlightRoute
+---
+
+<div class="header-bar">
+  <div class="header-start">
+    <div
+      class:list={[
+        '-m-3 overflow-clip p-3',
+        'flex min-w-0',
+      ]}
+    >
+      <SiteTitle />
+    </div>
+    <nav
+      class="flex flex-row gap-4 overflow-x-auto py-3 pr-4 pl-4 text-sm font-medium max-md:**:hidden xl:gap-6 xl:pl-6"
+    >
+      {
+        nav.map((item) => (
+          <a
+            class="-m-1.5 rounded-md p-1.5 text-(--sl-color-gray-3) no-underline hover:text-(--sl-color-white) focus-visible:outline-offset-0"
+            href={getI18nText(item.href, route)}
+          >
+            {getI18nText(item.label, route)}
+          </a>
+        ))
+      }
+    </nav>
+  </div>
+  <div class="header-center print:hidden">
+    <Search />
+  </div>
+  <div class="header-end">
+    <div class="hidden items-center gap-4 md:flex print:hidden">
+      <SocialIcons />
+      <LanguageSelect />
+      <ThemeSelect />
+    </div>
+    {
+      hasSidebar && (
+        <div class="flex items-center gap-2 md:hidden print:hidden">
+          <MobileMenuToggle />
+        </div>
+      )
+    }
+  </div>
+</div>
+
+<style>
+  .header-bar {
+    display: flex;
+    align-items: center;
+    height: 100%;
+    box-sizing: border-box;
+  }
+
+  .header-start {
+    display: flex;
+    align-items: center;
+    min-width: 0;
+    flex-shrink: 0;
+  }
+
+  .header-center {
+    flex: 1;
+    display: flex;
+    justify-content: center;
+    max-width: 24rem;
+    margin: 0 auto;
+  }
+
+  .header-end {
+    display: flex;
+    align-items: center;
+    flex-shrink: 0;
+  }
+</style>

package/src/components/Hero.astro

@@ -0,0 +1,169 @@
+---
+import { Image } from 'astro:assets'
+import { PAGE_TITLE_ID } from '../constants'
+import LinkButton from './LinkButton.astro'
+import type { StarlightRouteEntryData } from '../content'
+
+const data = Astro.locals.starlightRoute.entry.data as StarlightRouteEntryData
+
+const { title = data.title, tagline, image, actions = [] } = data.hero || {}
+
+const imageAttrs = {
+  loading: 'eager' as const,
+  decoding: 'async' as const,
+  width: 400,
+  height: 400,
+  alt: image?.alt || '',
+}
+
+let darkImage: ImageMetadata | undefined
+let lightImage: ImageMetadata | undefined
+let rawHtml: string | undefined
+if (image) {
+  if ('file' in image) {
+    darkImage = image.file
+  } else if ('dark' in image) {
+    darkImage = image.dark
+    lightImage = image.light
+  } else {
+    rawHtml = image.html
+  }
+}
+---
+
+<div class="hero">
+  {
+    darkImage && (
+      <Image
+        src={darkImage}
+        {...imageAttrs}
+        class:list={{ 'light:sl-hidden': Boolean(lightImage) }}
+      />
+    )
+  }
+  {
+    lightImage && (
+      <Image src={lightImage} {...imageAttrs} class="dark:sl-hidden" />
+    )
+  }
+  {rawHtml && <div class="hero-html sl-flex" set:html={rawHtml} />}
+  <div class="sl-flex stack">
+    <div class="sl-flex copy">
+      <h1 id={PAGE_TITLE_ID} data-page-title set:html={title} />
+      {tagline && <div class="tagline" set:html={tagline} />}
+    </div>
+    {
+      actions.length > 0 && (
+        <div class="sl-flex actions">
+          {actions.map(
+            ({
+              attrs: { class: className, ...attrs } = {},
+              icon,
+              link: href,
+              text,
+              variant,
+            }) => (
+              <LinkButton
+                {href}
+                {variant}
+                icon={icon?.name}
+                class:list={[className]}
+                {...attrs}
+              >
+                {text}
+                {icon?.html && <Fragment set:html={icon.html} />}
+              </LinkButton>
+            ),
+          )}
+        </div>
+      )
+    }
+  </div>
+</div>
+
+<style>
+  @layer celestia {
+    .hero {
+      display: grid;
+      align-items: center;
+      gap: 1rem;
+      padding-bottom: 1rem;
+    }
+
+    .hero > img,
+    .hero > .hero-html {
+      object-fit: contain;
+      width: min(70%, 20rem);
+      height: auto;
+      margin-inline: auto;
+    }
+
+    .stack {
+      flex-direction: column;
+      gap: clamp(1.5rem, calc(1.5rem + 1vw), 2rem);
+      text-align: center;
+    }
+
+    .copy {
+      flex-direction: column;
+      gap: 1rem;
+      align-items: center;
+    }
+
+    .copy > * {
+      max-width: 50ch;
+    }
+
+    h1 {
+      font-size: clamp(
+        var(--sl-text-3xl),
+        calc(0.25rem + 5vw),
+        var(--sl-text-6xl)
+      );
+      line-height: var(--sl-line-height-headings);
+      font-weight: 600;
+      color: var(--sl-color-white);
+    }
+
+    .tagline {
+      font-size: clamp(
+        var(--sl-text-base),
+        calc(0.0625rem + 2vw),
+        var(--sl-text-xl)
+      );
+      color: var(--sl-color-gray-2);
+    }
+
+    .actions {
+      gap: 1rem 2rem;
+      flex-wrap: wrap;
+      justify-content: center;
+    }
+
+    @media (min-width: 50rem) {
+      .hero {
+        grid-template-columns: 7fr 4fr;
+        gap: 3%;
+        padding-block: clamp(2.5rem, calc(1rem + 10vmin), 10rem);
+      }
+
+      .hero > img,
+      .hero > .hero-html {
+        order: 2;
+        width: min(100%, 25rem);
+      }
+
+      .stack {
+        text-align: start;
+      }
+
+      .copy {
+        align-items: flex-start;
+      }
+
+      .actions {
+        justify-content: flex-start;
+      }
+    }
+  }
+</style>

package/src/components/LanguageSelect.astro

@@ -0,0 +1,5 @@
+---
+import Default from '@astrojs/starlight/components/LanguageSelect.astro'
+---
+
+<Default />