astro-pure 1.0.0

package/index.ts

@@ -0,0 +1,74 @@
+import { spawn } from 'node:child_process'
+import { dirname, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { AstroIntegration } from 'astro'
+import mdx from '@astrojs/mdx'
+import sitemap from '@astrojs/sitemap'
+
+import { vitePluginUserConfig } from './plugins/virtual-user-config'
+import type { UserConfig } from './types/user-config'
+
+export default function AstroPureIntegration(opts: UserConfig): AstroIntegration {
+  let integrations: AstroIntegration[] = []
+  return {
+    name: 'astro-pure',
+    hooks: {
+      'astro:config:setup': async ({ config, injectRoute, updateConfig }) => {
+        // Add built-in integrations only if they are not already added by the user through the
+        // config or by a plugin.
+        const allIntegrations = [...config.integrations, ...integrations]
+        if (!allIntegrations.find(({ name }) => name === '@astrojs/sitemap')) {
+          integrations.push(sitemap())
+        }
+        if (!allIntegrations.find(({ name }) => name === '@astrojs/mdx')) {
+          integrations.push(mdx({ optimize: true }))
+        }
+
+        // Add Starlight directives restoration integration at the end of the list so that remark
+        // plugins injected by Starlight plugins through Astro integrations can handle text and
+        // leaf directives before they are transformed back to their original form.
+        // integrations.push(starlightDirectivesRestorationIntegration())
+
+        // Add integrations immediately after Starlight in the config array.
+        // e.g. if a user has `integrations: [starlight(), tailwind()]`, then the order will be
+        // `[starlight(), expressiveCode(), sitemap(), mdx(), tailwind()]`.
+        // This ensures users can add integrations before/after Starlight and we respect that order.
+        const selfIndex = config.integrations.findIndex((i) => i.name === 'astro-pure')
+        config.integrations.splice(selfIndex + 1, 0, ...integrations)
+
+        updateConfig({
+          vite: {
+            // @ts-ignore
+            plugins: [vitePluginUserConfig(opts, config)]
+          },
+          markdown: {
+            remarkPlugins: [
+              //   ...starlightAsides({ starlightConfig, astroConfig: config, useTranslations })
+            ]
+            // rehypePlugins: [rehypeRtlCodeSupport()],
+            // shikiConfig:
+            // Configure Shiki theme if the user is using the default github-dark theme.
+            //   config.markdown.shikiConfig.theme !== 'github-dark' ? {} : { theme: 'css-variables' }
+          },
+          scopedStyleStrategy: 'where',
+          // If not already configured, default to prefetching all links on hover.
+          prefetch: config.prefetch ?? { prefetchAll: true }
+        })
+      },
+
+      'astro:build:done': ({ dir }) => {
+        if (!opts.integ.pagefind) return
+        const targetDir = fileURLToPath(dir)
+        const cwd = dirname(fileURLToPath(import.meta.url))
+        const relativeDir = relative(cwd, targetDir)
+        return new Promise<void>((resolve) => {
+          spawn('npx', ['-y', 'pagefind', '--site', relativeDir], {
+            stdio: 'inherit',
+            shell: true,
+            cwd
+          }).on('close', () => resolve())
+        })
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "astro-pure",
+  "version": "1.0.0",
+  "description": "A simple, clean but powerful blog theme build by astro.",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "Astro",
+    "Theme",
+    "Blog"
+  ],
+  "author": "CWorld",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cworld1/astro-theme-pure",
+    "directory": "packages/pure"
+  },
+  "bugs": "https://github.com/cworld1/astro-theme-pure",
+  "homepage": "https://astro-theme-pure.vercel.app/",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./user": "./components/user/index.ts",
+    "./advanced": "./components/advanced/index.ts",
+    "./utils": "./utils/index.ts",
+    "./locals": "./locals.ts",
+    "./props": "./props.ts",
+    "./schema": "./schema.ts",
+    "./types": "./types.ts"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^4.0.1",
+    "@astrojs/sitemap": "^3.2.1",
+    "astro": "^5.0.3"
+  }
+}

package/plugins/link-preview.ts

@@ -0,0 +1,110 @@
+import { parse as htmlParser } from 'node-html-parser'
+
+class LRU<K, V> extends Map<K, V> {
+  constructor(private readonly maxSize: number) {
+    super()
+  }
+
+  override get(key: K): V | undefined {
+    const value = super.get(key)
+    if (value) this.#touch(key, value)
+    return value
+  }
+
+  override set(key: K, value: V): this {
+    this.#touch(key, value)
+    if (this.size > this.maxSize) {
+      const firstKey = this.keys().next().value
+      if (firstKey !== undefined) this.delete(firstKey)
+    }
+    return this
+  }
+
+  #touch(key: K, value: V): void {
+    this.delete(key)
+    super.set(key, value)
+  }
+}
+
+const formatError = (...lines: string[]) => lines.join('\n         ')
+
+/**
+ * Fetch a URL and parse it as JSON, but catch errors to stop builds erroring.
+ * @param url URL to fetch
+ * @returns {Promise<Record<string, unknown> | undefined>}
+ */
+export const safeGet = makeSafeGetter<Record<string, unknown>>((res) => res.json())
+
+/**
+ * Fetch a URL and parse it as HTML, but catch errors to stop builds erroring.
+ * @param url URL to fetch
+ * @returns {Promise<Document | undefined>}
+ */
+const safeGetDOM = makeSafeGetter(async (res) => htmlParser.parse(await res.text()))
+
+/** Factory to create safe, caching fetch functions. */
+function makeSafeGetter<T>(
+  handleResponse: (res: Response) => T | Promise<T>,
+  { cacheSize = 1000 }: { cacheSize?: number } = {}
+) {
+  const cache = new LRU<string, T>(cacheSize)
+  return async function safeGet(url: string): Promise<T | undefined> {
+    try {
+      const cached = cache.get(url)
+      if (cached) return cached
+      const response = await fetch(url)
+      if (!response.ok)
+        throw new Error(
+          formatError(`Failed to fetch ${url}`, `Error ${response.status}: ${response.statusText}`)
+        )
+      const result = await handleResponse(response)
+      cache.set(url, result)
+      return result
+    } catch (e) {
+      console.error(formatError(`[error] astro-embed`, (e as Error)?.message ?? e, `URL: ${url}`))
+      return undefined
+    }
+  }
+}
+
+/** Helper to get the `content` attribute of an element. */
+const getContent = (el: HTMLElement | null) => el?.getAttribute('content')
+/** Helper to filter out insecure or non-absolute URLs. */
+const urlOrNull = (url: string | null | undefined) => (url?.slice(0, 8) === 'https://' ? url : null)
+
+/**
+ * Loads and parses an HTML page to return Open Graph metadata.
+ * @param pageUrl URL to parse
+ */
+async function parseOpenGraph(pageUrl: string) {
+  const html = await safeGetDOM(pageUrl)
+  if (!html) return
+
+  const getMetaProperty = (prop: string) =>
+    getContent(html.querySelector(`meta[property=${JSON.stringify(prop)}]`) as HTMLElement | null)
+  const getMetaName = (name: string) =>
+    getContent(html.querySelector(`meta[name=${JSON.stringify(name)}]`) as HTMLElement | null)
+
+  const title = getMetaProperty('og:title') || html.querySelector('title')?.textContent
+  const description = getMetaProperty('og:description') || getMetaName('description')
+  const image = urlOrNull(
+    getMetaProperty('og:image:secure_url') ||
+      getMetaProperty('og:image:url') ||
+      getMetaProperty('og:image')
+  )
+  const imageAlt = getMetaProperty('og:image:alt')
+  const video = urlOrNull(
+    getMetaProperty('og:video:secure_url') ||
+      getMetaProperty('og:video:url') ||
+      getMetaProperty('og:video')
+  )
+  const videoType = getMetaProperty('og:video:type')
+  const url =
+    urlOrNull(
+      getMetaProperty('og:url') || html.querySelector("link[rel='canonical']")?.getAttribute('href')
+    ) || pageUrl
+
+  return { title, description, image, imageAlt, url, video, videoType }
+}
+
+export { safeGetDOM, parseOpenGraph }

package/plugins/rehype-steps.ts

@@ -0,0 +1,98 @@
+// https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/rehype-steps.ts
+
+import { AstroError } from 'astro/errors'
+import type { Element, Root } from 'hast'
+import { rehype } from 'rehype'
+import type { VFile } from 'vfile'
+
+const prettyPrintProcessor = rehype().data('settings', { fragment: true })
+
+const prettyPrintHtml = (html: string) =>
+  prettyPrintProcessor.processSync({ value: html }).toString()
+
+const stepsProcessor = rehype()
+  .data('settings', { fragment: true })
+
+  .use(function steps() {
+    return (tree: Root, vfile: VFile) => {
+      const rootElements = tree.children.filter((item): item is Element => item.type === 'element')
+
+      const [rootElement] = rootElements
+
+      if (!rootElement) {
+        throw new StepsError(
+          'The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found no child elements.'
+        )
+      } else if (rootElements.length > 1) {
+        throw new StepsError(
+          'The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found multiple child elements: ' +
+            rootElements.map((element: Element) => `\`<${element.tagName}>\``).join(', ') +
+            '.',
+
+          vfile.value.toString()
+        )
+      } else if (rootElement.tagName !== 'ol') {
+        throw new StepsError(
+          'The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found the following element: ' +
+            `\`<${rootElement.tagName}>\`.`,
+
+          vfile.value.toString()
+        )
+      }
+
+      // Ensure `role="list"` is set on the ordered list.
+
+      // We use `list-style: none` in the styles for this component and need to ensure the list
+
+      // retains its semantics in Safari, which will remove them otherwise.
+
+      rootElement.properties.role = 'list'
+
+      // Add the required CSS class name, preserving existing classes if present.
+
+      if (!Array.isArray(rootElement.properties.className)) {
+        rootElement.properties.className = ['sl-steps']
+      } else {
+        rootElement.properties.className.push('sl-steps')
+      }
+
+      // Add the `start` attribute as a CSS custom property so we can use it as the starting index
+
+      // of the steps custom counter.
+
+      if (typeof rootElement.properties.start === 'number') {
+        const styles = [`--sl-steps-start: ${rootElement.properties.start - 1}`]
+
+        if (rootElement.properties.style) styles.push(String(rootElement.properties.style))
+
+        rootElement.properties.style = styles.join(';')
+      }
+    }
+  })
+
+/**
+
+ * Process steps children: validates the HTML and adds `role="list"` to the ordered list.
+
+ * @param html Inner HTML passed to the `<Steps>` component.
+
+ */
+
+export const processSteps = (html: string | undefined) => {
+  const file = stepsProcessor.processSync({ value: html })
+
+  return { html: file.toString() }
+}
+
+class StepsError extends AstroError {
+  constructor(message: string, html?: string) {
+    let hint =
+      'To learn more about the `<Steps>` component, see https://starlight.astro.build/components/steps/'
+
+    if (html) {
+      hint += '\n\nFull HTML passed to `<Steps>`:\n' + prettyPrintHtml(html)
+    }
+
+    super(message, hint)
+  }
+}

package/plugins/rehype-tabs.ts

@@ -0,0 +1,112 @@
+import type { Element } from 'hast'
+import { select } from 'hast-util-select'
+import { rehype } from 'rehype'
+import { CONTINUE, SKIP, visit } from 'unist-util-visit'
+
+interface Panel {
+  panelId: string
+  tabId: string
+  label: string
+}
+
+declare module 'vfile' {
+  interface DataMap {
+    panels: Panel[]
+  }
+}
+
+export const TabItemTagname = 'starlight-tab-item'
+
+// https://github.com/adobe/react-spectrum/blob/99ca82e87ba2d7fdd54f5b49326fd242320b4b51/packages/%40react-aria/focus/src/FocusScope.tsx#L256-L275
+const focusableElementSelectors = [
+  'input:not([disabled]):not([type=hidden])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'button:not([disabled])',
+  'a[href]',
+  'area[href]',
+  'summary',
+  'iframe',
+  'object',
+  'embed',
+  'audio[controls]',
+  'video[controls]',
+  '[contenteditable]',
+  '[tabindex]:not([disabled])'
+]
+  .map((selector) => `${selector}:not([hidden]):not([tabindex="-1"])`)
+  .join(',')
+
+let count = 0
+const getIDs = () => {
+  const id = count++
+  return { panelId: 'tab-panel-' + id, tabId: 'tab-' + id }
+}
+
+/**
+ * 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(function tabs() {
+    return (tree: Element, file) => {
+      file.data.panels = []
+      let isFirst = true
+      visit(tree, 'element', (node) => {
+        if (node.tagName !== TabItemTagname || !node.properties) {
+          return CONTINUE
+        }
+
+        const { dataLabel } = node.properties
+        const ids = getIDs()
+        const panel: Panel = {
+          ...ids,
+          label: String(dataLabel)
+        }
+        file.data.panels?.push(panel)
+
+        // Remove `<TabItem>` props
+        delete node.properties.dataLabel
+        // Turn into `<div>` with required attributes
+        node.tagName = 'div'
+        node.properties.id = ids.panelId
+        node.properties['aria-labelledby'] = ids.tabId
+        node.properties.role = 'tabpanel'
+
+        const focusableChild = select(focusableElementSelectors, node)
+        // If the panel does not contain any focusable elements, include it in
+        // the tab sequence of the page.
+        if (!focusableChild) {
+          node.properties.tabindex = 0
+        }
+
+        // Hide all panels except the first
+        // TODO: make initially visible tab configurable
+        if (isFirst) {
+          isFirst = false
+        } else {
+          node.properties.hidden = true
+        }
+
+        // Skip over the tab panel’s children.
+        return SKIP
+      })
+    }
+  })
+
+/**
+ * Process tab panel items to extract data for the tab links and format
+ * each tab panel correctly.
+ * @param html Inner HTML passed to the `<Tabs>` component.
+ */
+export const processPanels = (html: string) => {
+  const file = tabsProcessor.processSync({ value: html })
+  return {
+    /** Data for each tab panel. */
+    panels: file.data.panels,
+    /** Processed HTML for the tab panels. */
+    html: file.toString()
+  }
+}

package/plugins/virtual-user-config.ts

@@ -0,0 +1,83 @@
+import fs from 'fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { AstroConfig, ViteUserConfig } from 'astro'
+
+import type { UserConfig } from '../types/user-config'
+
+function resolveVirtualModuleId<T extends string>(id: T): `\0${T}` {
+  return `\0${id}`
+}
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const virtualUtilsPath = resolve(__dirname, '../virtual.d.ts')
+
+/** Vite plugin that exposes Starlight user config and project context via virtual modules. */
+export function vitePluginUserConfig(
+  opts: UserConfig,
+  {
+    build,
+    root,
+    srcDir,
+    trailingSlash
+  }: Pick<AstroConfig, 'root' | 'srcDir' | 'trailingSlash'> & {
+    build: Pick<AstroConfig['build'], 'format'>
+  }
+): NonNullable<ViteUserConfig['plugins']>[number] {
+  /**
+   * Resolves module IDs to a usable format:
+   * - Relative paths (e.g. `'./module.js'`) are resolved against `base` and formatted as an absolute path.
+   * - Package identifiers (e.g. `'module'`) are returned unchanged.
+   *
+   * By default, `base` is the project root directory.
+   */
+  const resolveId = (id: string, base = root) =>
+    JSON.stringify(id.startsWith('.') ? resolve(fileURLToPath(base), id) : id)
+
+  /** Map of virtual module names to their code contents as strings. */
+  const modules = {
+    'virtual:config': `export default ${JSON.stringify(opts)}`,
+    'virtual:starlight/project-context': `export default ${JSON.stringify({
+      build: { format: build.format },
+      root,
+      srcDir,
+      trailingSlash
+    })}`,
+    'virtual:starlight/user-css': opts.customCss.map((id) => `import ${resolveId(id)};`).join(''),
+    'virtual:starlight/user-images': opts.logo
+      ? 'src' in opts.logo
+        ? `import src from ${resolveId(
+            opts.logo.src
+          )}; export const logos = { dark: src, light: src };`
+        : `import dark from ${resolveId(opts.logo.dark)}; import light from ${resolveId(
+            opts.logo.light
+          )}; export const logos = { dark, light };`
+      : 'export const logos = {};',
+    'virtual:starlight/collection-config': `let userCollections;
+			try {
+				userCollections = (await import(${resolveId('./content/config.ts', srcDir)})).collections;
+			} catch {}
+			export const collections = userCollections;`,
+    '../../utils': fs.readFileSync(virtualUtilsPath, 'utf-8')
+  } 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-user-config',
+    resolveId(id): string | void {
+      if (id in modules) return resolveVirtualModuleId(id)
+    },
+    load(id): string | void {
+      const resolution = resolutionMap[id]
+      if (resolution) return modules[resolution]
+    }
+  }
+}

package/schemas/favicon.ts

@@ -0,0 +1,42 @@
+import { extname } from 'node:path'
+import { z } from 'astro/zod'
+
+const faviconTypeMap = {
+  '.ico': 'image/x-icon',
+  '.gif': 'image/gif',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml'
+}
+
+export const FaviconSchema = () =>
+  z
+    .string()
+    .default('/favicon.svg')
+    .transform((favicon, ctx) => {
+      // favicon can be absolute or relative url
+      const { pathname } = new URL(favicon, 'https://example.com')
+      const ext = extname(pathname).toLowerCase()
+
+      if (!isFaviconExt(ext)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: 'favicon must be a .ico, .gif, .jpg, .png, or .svg file'
+        })
+
+        return z.NEVER
+      }
+
+      return {
+        href: favicon,
+        type: faviconTypeMap[ext]
+      }
+    })
+    .describe(
+      'The default favicon for your site which should be a path to an image in the `public/` directory.'
+    )
+
+function isFaviconExt(ext: string): ext is keyof typeof faviconTypeMap {
+  return ext in faviconTypeMap
+}

package/schemas/head.ts

@@ -0,0 +1,18 @@
+import { z } from 'astro/zod'
+
+export const HeadConfigSchema = () =>
+  z
+    .array(
+      z.object({
+        /** Name of the HTML tag to add to `<head>`, e.g. `'meta'`, `'link'`, or `'script'`. */
+        tag: z.enum(['title', 'base', 'link', 'style', 'meta', 'script', 'noscript', 'template']),
+        /** Attributes to set on the tag, e.g. `{ rel: 'stylesheet', href: '/custom.css' }`. */
+        attrs: z.record(z.union([z.string(), z.boolean(), z.undefined()])).default({}),
+        /** Content to place inside the tag (optional). */
+        content: z.string().default('')
+      })
+    )
+    .default([])
+
+export type HeadUserConfig = z.input<ReturnType<typeof HeadConfigSchema>>
+export type HeadConfig = z.output<ReturnType<typeof HeadConfigSchema>>

package/schemas/logo.ts

@@ -0,0 +1,28 @@
+import { z } from 'astro/zod'
+
+export const LogoConfigSchema = () =>
+  z
+    .union([
+      z.object({
+        /** Source of the image file to use. */
+        src: z.string(),
+        /** Alternative text description of the logo. */
+        alt: z.string().default(''),
+        /** Set to `true` to hide the site title text and only show the logo. */
+        replacesTitle: z.boolean().default(false)
+      }),
+      z.object({
+        /** Source of the image file to use in dark mode. */
+        dark: z.string(),
+        /** Source of the image file to use in light mode. */
+        light: z.string(),
+        /** Alternative text description of the logo. */
+        alt: z.string().default(''),
+        /** Set to `true` to hide the site title text and only show the logo. */
+        replacesTitle: z.boolean().default(false)
+      })
+    ])
+    .optional()
+
+export type LogoUserConfig = z.input<ReturnType<typeof LogoConfigSchema>>
+export type LogoConfig = z.output<ReturnType<typeof LogoConfigSchema>>

package/schemas/social.ts

@@ -0,0 +1,51 @@
+import { z } from 'astro/zod'
+
+export const socialLinks = [
+  'github',
+  'gitlab',
+  'discord',
+  'youtube',
+  'instagram',
+  'x',
+  'telegram',
+  'rss',
+  'facebook',
+  'email',
+  'reddit',
+  'blueSky',
+  'tiktok'
+] as const
+
+export const SocialLinksSchema = () =>
+  z
+    .record(
+      z.enum(socialLinks),
+      // Link to the respective social profile for this site
+      z.string().url()
+    )
+    .transform((links) => {
+      const labelledLinks: Partial<Record<keyof typeof links, { label: string; url: string }>> = {}
+      for (const _k in links) {
+        const key = _k as keyof typeof links
+        const url = links[key]
+        if (!url) continue
+        const label = {
+          github: 'GitHub',
+          gitlab: 'GitLab',
+          discord: 'Discord',
+          youtube: 'YouTube',
+          instagram: 'Instagram',
+          x: 'X',
+          telegram: 'Telegram',
+          rss: 'RSS',
+          facebook: 'Facebook',
+          email: 'Email',
+          reddit: 'Reddit',
+          blueSky: 'BlueSky',
+          tiktok: 'TikTok'
+        }[key]
+        labelledLinks[key] = { label, url }
+      }
+      return labelledLinks
+    })
+    .optional()