astro-pure 1.0.0

package/types/common.d.ts

@@ -0,0 +1,48 @@
+declare module 'virtual:types' {
+  export type MenuLinks = { link: string; label: string }[]
+
+  export interface PaginationLink {
+    url: string
+    text?: string
+    srLabel?: string
+  }
+
+  export interface SiteMeta {
+    title: string
+    description?: string
+    ogImage?: string | undefined
+    articleDate?: string | undefined
+  }
+
+  export interface SocialLink {
+    name:
+      | 'coolapk'
+      | 'telegram'
+      | 'github'
+      | 'bilibili'
+      | 'twitter'
+      | 'zhihu'
+      | 'steam'
+      | 'netease_music'
+      | 'mail'
+    url: string
+  }
+
+  export type ShareItem = 'weibo' | 'x' | 'bluesky'
+
+  export type CardListData = {
+    title: string
+    list: CardList
+  }
+
+  export type CardList = {
+    title: string
+    link?: string
+    children?: CardList
+  }[]
+
+  export type TimelineEvent = {
+    date: string
+    content: string
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,6 @@
+/// <reference path="./common.d.ts" />
+
+declare module 'virtual:config' {
+  const Config: import('./user-config').UserConfig
+  export default Config
+}

package/types/integrations-config.ts

@@ -0,0 +1,43 @@
+import { z } from 'astro/zod'
+
+export const IntegrationConfigSchema = () =>
+  z.object({
+    /**
+     * Define whether Starlight’s default site search provider Pagefind is enabled.
+     * Set to `false` to disable indexing your site with Pagefind.
+     * This will also hide the default search UI if in use.
+     */
+    pagefind: z.boolean().optional(),
+    quote: z.object({
+      /** The server to fetch the quote from. */
+      server: z.string(),
+      // target: (data: unknown) => string
+      target: z.function().args(z.unknown()).returns(z.string())
+    }),
+    typography: z.object({
+      /** The class to apply to the typography. */
+      class: z
+        .string()
+        .default('prose prose-pure dark:prose-invert dark:prose-pure prose-headings:font-medium')
+    }),
+    mediumZoom: z.object({
+      /** Enable the medium zoom library. */
+      enable: z.boolean().default(true),
+      /** The selector to apply the zoom effect to. */
+      selector: z.string().default('.prose .zoomable'),
+      /** Options to pass to the medium zoom library. */
+      options: z.record(z.string(), z.any()).default({ className: 'zoomable' })
+    }),
+    waline: z.object({
+      /** Enable the Waline comment system. */
+      enable: z.boolean().default(false),
+      /** The server to use for the Waline comment system. */
+      server: z.string().optional(),
+      /** The emoji to use for the Waline comment system. */
+      emoji: z.array(z.string()).optional(),
+      /** Additional configurations for the Waline comment system. */
+      additionalConfigs: z.record(z.string(), z.any()).default({})
+    })
+  })
+
+export type IntegrationConfig = z.infer<ReturnType<typeof IntegrationConfigSchema>>

package/types/theme-config.ts

@@ -0,0 +1,125 @@
+import { z } from 'astro/zod'
+
+import { FaviconSchema } from '../schemas/favicon'
+import { HeadConfigSchema } from '../schemas/head'
+import { LogoConfigSchema } from '../schemas/logo'
+import { SocialLinksSchema } from '../schemas/social'
+
+export const ThemeConfigSchema = z.object({
+  /** Title for your website. Will be used in metadata and as browser tab title. */
+  title: z
+    .string()
+    .describe('Title for your website. Will be used in metadata and as browser tab title.'),
+
+  /** Description metadata for your website. Can be used in page metadata. */
+  description: z
+    .string()
+    .optional()
+    .describe('Description metadata for your website. Can be used in page metadata.'),
+
+  /** Set a logo image to show in the homepage. */
+  logo: LogoConfigSchema(),
+
+  /**
+   * Optional details about the social media accounts for this site.
+   *
+   * @example
+   * social: {
+   *   codeberg: 'https://codeberg.org/knut/examples',
+   *   discord: 'https://astro.build/chat',
+   *   github: 'https://github.com/withastro/starlight',
+   *   gitlab: 'https://gitlab.com/delucis',
+   *   linkedin: 'https://www.linkedin.com/company/astroinc',
+   *   mastodon: 'https://m.webtoo.ls/@astro',
+   *   threads: 'https://www.threads.net/@nmoodev',
+   *   twitch: 'https://www.twitch.tv/bholmesdev',
+   *   twitter: 'https://twitter.com/astrodotbuild',
+   *   youtube: 'https://youtube.com/@astrodotbuild',
+   * }
+   */
+  social: SocialLinksSchema(),
+
+  /** The tagline for your website. */
+  tagline: z.string().optional().describe('The tagline for your website.'),
+
+  /** Configure the defaults for the table of contents on each page. */
+  //   tableOfContents: TableOfContentsSchema(),
+
+  /**
+   * Specify the default language for this site.
+   *
+   * The default locale will be used to provide fallback content where translations are missing.
+   */
+  locale: z.string().optional(),
+
+  /**
+   * Add extra tags to your site’s `<head>`.
+   *
+   * Can also be set for a single page in a page’s frontmatter.
+   *
+   * @example
+   * // Add Fathom analytics to your site
+   * starlight({
+   *  head: [
+   *    {
+   *      tag: 'script',
+   *      attrs: {
+   *        src: 'https://cdn.usefathom.com/script.js',
+   *        'data-site': 'MY-FATHOM-ID',
+   *        defer: true,
+   *      },
+   *    },
+   *  ],
+   * })
+   */
+  head: HeadConfigSchema(),
+
+  /**
+   * Provide CSS files to customize the look and feel of your Starlight site.
+   *
+   * Supports local CSS files relative to the root of your project,
+   * e.g. `'/src/custom.css'`, and CSS you installed as an npm
+   * module, e.g. `'@fontsource/roboto'`.
+   *
+   * @example
+   * starlight({
+   *  customCss: ['/src/custom-styles.css', '@fontsource/roboto'],
+   * })
+   */
+  customCss: z.string().array().optional().default([]),
+
+  /** The default favicon for your site which should be a path to an image in the `public/` directory. */
+  favicon: FaviconSchema(),
+
+  /** Will be used as title delimiter in the generated `<title>` tag. */
+  titleDelimiter: z
+    .string()
+    .default('|')
+    .describe('Will be used as title delimiter in the generated `<title>` tag.'),
+
+  /**
+   * Define whether Starlight pages should be prerendered or not.
+   * Defaults to always prerender Starlight pages, even when the project is
+   * set to "server" output mode.
+   */
+  prerender: z.boolean().default(true),
+
+  /** Enable displaying a “Built with Starlight” link in your site’s footer. */
+  credits: z
+    .boolean()
+    .default(false)
+    .describe('Enable displaying a “Built with Starlight” link in your site’s footer.'),
+
+  /** The npm CDN to use for loading npm packages.
+   * @example
+   * npmCDN: 'https://cdn.jsdelivr.net/npm'
+   * npmCDN: 'https://cdn.smartcis.cn/npm'
+   * npmCDN: 'https://unkpg.com'
+   * npmCDN: 'https://cdn.cbd.int'
+   * npmCDN: 'https://esm.sh'
+   */
+  npmCDN: z
+    .string()
+    .default('https://esm.sh')
+    .describe('The npm CDN to use for loading npm packages.')
+})

package/types/user-config.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+
+import { IntegrationConfigSchema } from './integrations-config'
+import { ThemeConfigSchema } from './theme-config'
+
+export const UserConfigSchema = ThemeConfigSchema.strict()
+  .merge(
+    z.object({
+      integ: IntegrationConfigSchema()
+    })
+  )
+  .transform((config) => ({
+    ...config,
+    // Pagefind only defaults to true if prerender is also true.
+    integ: {
+      ...config.integ,
+      pagefind: config.integ.pagefind ?? config.prerender
+    }
+  }))
+  .refine((config) => !(config.integ.pagefind && !config.prerender), {
+    message: 'Pagefind search is not supported with prerendering disabled.'
+  })
+
+export type UserConfig = z.infer<typeof UserConfigSchema>

package/utils/clsx.ts

@@ -0,0 +1,24 @@
+export type ClassValue = ClassArray | ClassDictionary | string | number | null | boolean | undefined
+export type ClassDictionary = Record<string, unknown>
+export type ClassArray = ClassValue[]
+
+export function clsx(...inputs: ClassValue[]): string {
+  let str = ''
+  for (let i = 0; i < inputs.length; i++) {
+    const input = inputs[i]
+    if (typeof input === 'string' || typeof input === 'number') {
+      str += (str && ' ') + input
+    } else if (Array.isArray(input)) {
+      str += (str && ' ') + clsx(...input)
+    } else if (typeof input === 'object') {
+      for (const key in input) {
+        if (input[key]) {
+          str += (str && ' ') + key
+        }
+      }
+    }
+  }
+  return str
+}
+
+export default clsx

package/utils/collections.ts

@@ -0,0 +1,48 @@
+import { type CollectionEntry, type CollectionKey } from 'astro:content'
+
+type Collections = CollectionEntry<CollectionKey>[]
+
+export function groupCollectionsByYear<T extends CollectionKey>(
+  collections: Collections
+): [number, CollectionEntry<T>[]][] {
+  const collectionsByYear = collections.reduce((acc, collection) => {
+    const year = new Date(collection.data.updatedDate ?? collection.data.publishDate).getFullYear()
+    if (!acc.has(year)) {
+      acc.set(year, [])
+    }
+    acc.get(year)!.push(collection)
+    return acc
+  }, new Map<number, Collections>())
+
+  return Array.from(
+    collectionsByYear.entries() as IterableIterator<[number, CollectionEntry<T>[]]>
+  ).sort((a, b) => b[0] - a[0])
+}
+
+export function sortMDByDate(collections: Collections) {
+  return collections.sort((a, b) => {
+    const aDate = new Date(a.data.updatedDate ?? a.data.publishDate).valueOf()
+    const bDate = new Date(b.data.updatedDate ?? b.data.publishDate).valueOf()
+    return bDate - aDate
+  })
+}
+
+/** Note: This function doesn't filter draft posts, pass it the result of getAllPosts above to do so. */
+export function getAllTags(collections: Collections) {
+  return collections.flatMap((collection) => [...collection.data.tags])
+}
+
+/** Note: This function doesn't filter draft posts, pass it the result of getAllPosts above to do so. */
+export function getUniqueTags(collections: Collections) {
+  return [...new Set(getAllTags(collections))]
+}
+
+/** Note: This function doesn't filter draft posts, pass it the result of getAllPosts above to do so. */
+export function getUniqueTagsWithCount(collections: Collections): [string, number][] {
+  return [
+    ...getAllTags(collections).reduce(
+      (acc, t) => acc.set(t, (acc.get(t) || 0) + 1),
+      new Map<string, number>()
+    )
+  ].sort((a, b) => b[1] - a[1])
+}

package/utils/date.ts

@@ -0,0 +1,17 @@
+import { siteConfig } from '@/site-config'
+
+const dateFormat = new Intl.DateTimeFormat(siteConfig.date.locale, siteConfig.date.options)
+
+export function getFormattedDate(
+  date: string | number | Date,
+  options?: Intl.DateTimeFormatOptions
+) {
+  if (typeof options !== 'undefined') {
+    return new Date(date).toLocaleDateString(siteConfig.date.locale, {
+      ...(siteConfig.date.options as Intl.DateTimeFormatOptions),
+      ...options
+    })
+  }
+
+  return dateFormat.format(new Date(date))
+}

package/utils/docsContents.ts

@@ -0,0 +1,36 @@
+import type { CardListData } from '@/types'
+
+// Docs content declaration
+export const docs: CardListData = {
+  title: 'Docs content',
+  list: [
+    {
+      title: 'Setup',
+      children: [
+        { title: 'Getting Started', link: '/docs/setup/getting-started' },
+        { title: 'Configuration', link: '/docs/setup/configuration' },
+        { title: 'Authoring Content', link: '/docs/setup/content' },
+        { title: 'Deployment', link: '/docs/setup/deployment' }
+      ]
+    },
+    {
+      title: 'Integrations',
+      children: [
+        { title: 'Comment System', link: '/docs/integrations/comment' },
+        { title: 'Friend Links', link: '/docs/integrations/links' },
+        { title: 'Shiki Code', link: '/docs/integrations/code' },
+        { title: 'User Components', link: '/docs/integrations/components' },
+        { title: 'Advanced Components', link: '/docs/integrations/advanced' },
+        { title: 'Other Integrations', link: '/docs/integrations/others' }
+      ]
+    },
+    {
+      title: 'Advanced',
+      children: [
+        { title: 'Update Theme', link: '/docs/advanced/update' },
+        { title: 'Optimize Your Site', link: '/docs/advanced/optimize' },
+        { title: 'Acknowledgements', link: '/docs/advanced/thanks' }
+      ]
+    }
+  ]
+}

package/utils/index.ts

@@ -0,0 +1,23 @@
+// Tailwind
+export { cn } from './tailwind'
+
+// Collections
+export {
+  groupCollectionsByYear,
+  sortMDByDate,
+  getUniqueTags,
+  getUniqueTagsWithCount
+} from './collections'
+
+// Date
+export { getFormattedDate } from './date'
+
+// Toc
+export { generateToc } from './toc'
+export type { TocItem } from './toc'
+
+// Theme
+export { getTheme, listenThemeChange, setTheme } from './theme'
+
+// Toast
+export { showToast } from './toast'

package/utils/module.d.ts

@@ -0,0 +1,25 @@
+declare module '../../utils' {
+  // Tailwind
+  export { cn } from './tailwind'
+
+  // Collections
+  export {
+    groupCollectionsByYear,
+    sortMDByDate,
+    getUniqueTags,
+    getUniqueTagsWithCount
+  } from './collections'
+
+  // Date
+  export { getFormattedDate } from './date'
+
+  // Toc
+  export { generateToc } from './toc'
+  export type { TocItem } from './toc'
+
+  // Theme
+  export { getTheme, listenThemeChange, setTheme } from './theme'
+
+  // Toast
+  export { showToast } from './toast'
+}

package/utils/server.ts

@@ -0,0 +1,11 @@
+import { getCollection, type CollectionEntry, type CollectionKey } from 'astro:content'
+
+export const prod = import.meta.env.PROD
+
+/** Note: this function filters out draft posts based on the environment */
+export async function getBlogCollection(contentType: CollectionKey = 'blog') {
+  return await getCollection(contentType, ({ data }: CollectionEntry<typeof contentType>) => {
+    // Not in production & draft is not false
+    return !prod || data.draft !== false
+  })
+}

package/utils/tailwind.ts

@@ -0,0 +1,7 @@
+import { twMerge } from 'tailwind-merge'
+
+import { clsx, type ClassValue } from './clsx'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/utils/theme.ts

@@ -0,0 +1,40 @@
+export function getTheme() {
+  return localStorage.getItem('theme')
+}
+
+export function listenThemeChange(theme?: string) {
+  if (!theme || theme === 'system') return // if theme is specified, no need to listen window theme change
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+    setTheme(e.matches ? 'dark' : 'light')
+  })
+}
+
+export function setTheme(theme?: string, save = false) {
+  const themes = ['system', 'dark', 'light']
+  if (theme) {
+    if (!themes.includes(theme)) return
+    if (save) localStorage.setItem('theme', theme)
+  } else {
+    theme = getTheme() ?? undefined
+    if (save) {
+      // Set theme equals undefined, switch cycle in ['system', 'dark', 'light']
+      const currentIndex = themes.indexOf(theme ?? 'system')
+      theme = themes[(currentIndex + 1) % themes.length]
+      localStorage.setItem('theme', theme) // save theme
+    }
+  }
+  let targetTheme = theme
+  if (theme === 'system') {
+    targetTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+    // Listen theme change
+    listenThemeChange(theme)
+  }
+
+  // Set theme
+  document.documentElement.classList.toggle('dark', targetTheme === 'dark')
+  document
+    .querySelector('meta[name="theme-color"]')
+    ?.setAttribute('content', targetTheme === 'dark' ? '#0B0B10' : '#FCFCFD')
+
+  return theme
+}

package/utils/toast.ts

@@ -0,0 +1,3 @@
+export function showToast(detail: { message: string }) {
+  document.dispatchEvent(new CustomEvent('toast', { detail }))
+}

package/utils/toc.ts

@@ -0,0 +1,41 @@
+import type { MarkdownHeading } from 'astro'
+
+export interface TocItem extends MarkdownHeading {
+  subheadings: TocItem[]
+}
+
+function diveChildren(item: TocItem, depth: number): TocItem[] {
+  if (depth === 1 || !item.subheadings.length) {
+    return item.subheadings
+  } else {
+    // e.g., 2
+    return diveChildren(item.subheadings[item.subheadings.length - 1] as TocItem, depth - 1)
+  }
+}
+
+export function generateToc(headings: readonly MarkdownHeading[]) {
+  // this ignores/filters out h1 element(s)
+  const bodyHeadings = [...headings.filter(({ depth }) => depth > 1)]
+  const toc: TocItem[] = []
+
+  bodyHeadings.forEach((h) => {
+    const heading: TocItem = { ...h, subheadings: [] }
+
+    // add h2 elements into the top level
+    if (heading.depth === 2) {
+      toc.push(heading)
+    } else {
+      const lastItemInToc = toc[toc.length - 1]!
+      if (heading.depth < lastItemInToc.depth) {
+        throw new Error(`Orphan heading found: ${heading.text}.`)
+      }
+
+      // higher depth
+      // push into children, or children's children
+      const gap = heading.depth - lastItemInToc.depth
+      const target = diveChildren(lastItemInToc, gap)
+      target.push(heading)
+    }
+  })
+  return toc
+}

package/virtual.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="./types/index.d.ts" />
+/// <reference path="./utils/module.d.ts" />