@guzhongren/sha 0.1.0

package/src/components/SearchEnhancer.astro

@@ -0,0 +1,183 @@
+---
+---
+
+<dialog class="search-dialog" data-search-dialog aria-label="Search">
+  <section class="search-modal" data-search-root data-search-mode="modal" data-search-limit="8">
+    <div class="search-modal-header">
+      <p class="utility-note text-xs">full-text search</p>
+      <button class="search-close" type="button" data-search-close aria-label="Close search">Esc</button>
+    </div>
+    <label class="search-field">
+      <span class="sr-only">Search posts</span>
+      <input data-search-input type="search" placeholder="Search posts..." autocomplete="off" />
+    </label>
+    <p class="search-status" data-search-status>Type at least 2 characters to search.</p>
+    <ol class="search-results" data-search-results></ol>
+  </section>
+</dialog>
+
+<script>
+  const pagefindPath = "/pagefind/pagefind.js";
+  let pagefindModule;
+  let pagefindLoad;
+
+  function loadPagefind() {
+    pagefindLoad ??= import(/* @vite-ignore */ pagefindPath).then((module) => {
+      pagefindModule = module;
+      return module;
+    });
+    return pagefindLoad;
+  }
+
+  function escapeHtml(value) {
+    return String(value)
+      .replaceAll("&", "&amp;")
+      .replaceAll("<", "&lt;")
+      .replaceAll(">", "&gt;")
+      .replaceAll('"', "&quot;");
+  }
+
+  function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+
+  function highlight(value, query) {
+    const safe = escapeHtml(value);
+    const terms = [...new Set(query.split(/\s+/).map((term) => term.trim()).filter(Boolean))];
+    if (terms.length === 0) return safe;
+
+    const pattern = new RegExp(`(${terms.map(escapeRegExp).join("|")})`, "gi");
+    return safe.replace(pattern, "<mark>$1</mark>");
+  }
+
+  function setFallback(root, visible) {
+    const fallback = root.querySelector("[data-search-fallback]");
+    if (fallback) fallback.hidden = !visible;
+  }
+
+  function renderResults(root, results, query) {
+    const list = root.querySelector("[data-search-results]");
+    const status = root.querySelector("[data-search-status]");
+    if (!list || !status) return;
+
+    if (results.length === 0) {
+      list.innerHTML = "";
+      status.textContent = "No matching posts found.";
+      setFallback(root, false);
+      return;
+    }
+
+    status.textContent = `${results.length} result${results.length === 1 ? "" : "s"}`;
+    list.innerHTML = results
+      .map((result) => {
+        const title = result.meta?.title || result.url;
+        const category = result.meta?.category;
+        const date = result.meta?.date;
+        const meta = [category, date].filter(Boolean).join(" / ") || result.url;
+        const excerpt = result.excerpt || result.sub_results?.[0]?.excerpt || "";
+
+        return `
+          <li>
+            <a class="search-result" href="${escapeHtml(result.url)}" data-search-result>
+              <span class="search-result-meta">${escapeHtml(meta)}</span>
+              <span class="search-result-title">${highlight(title, query)}</span>
+              ${excerpt ? `<span class="search-result-excerpt">${excerpt}</span>` : ""}
+            </a>
+          </li>
+        `;
+      })
+      .join("");
+    setFallback(root, false);
+  }
+
+  function initSearchRoot(root) {
+    const input = root.querySelector("[data-search-input]");
+    const status = root.querySelector("[data-search-status]");
+    const list = root.querySelector("[data-search-results]");
+    const limit = Number(root.dataset.searchLimit || 20);
+    let timer;
+    let token = 0;
+
+    if (!input || !status || !list || root.dataset.searchReady === "true") return;
+    root.dataset.searchReady = "true";
+
+    async function runSearch() {
+      const query = input.value.trim();
+      token += 1;
+      const current = token;
+
+      if (query.length < 2) {
+        list.innerHTML = "";
+        status.textContent = "Type at least 2 characters to search.";
+        setFallback(root, root.dataset.searchMode === "page");
+        return;
+      }
+
+      status.textContent = "Searching...";
+      setFallback(root, false);
+
+      try {
+        const pagefind = pagefindModule || (await loadPagefind());
+        const search = await pagefind.search(query);
+        const data = await Promise.all(search.results.slice(0, limit).map((result) => result.data()));
+        if (current !== token) return;
+        renderResults(root, data, query);
+      } catch (error) {
+        if (current !== token) return;
+        list.innerHTML = "";
+        status.textContent = "Search index is available after a production build.";
+        setFallback(root, root.dataset.searchMode === "page");
+        console.error(error);
+      }
+    }
+
+    input.addEventListener("input", () => {
+      window.clearTimeout(timer);
+      timer = window.setTimeout(runSearch, 150);
+    });
+    input.addEventListener("focus", () => {
+      loadPagefind().catch(() => undefined);
+    });
+
+    root.addEventListener("click", (event) => {
+      const result = event.target.closest("[data-search-result]");
+      if (result) document.querySelector("[data-search-dialog]")?.close();
+    });
+  }
+
+  function initSearch() {
+    const dialog = document.querySelector("[data-search-dialog]");
+    const modalRoot = dialog?.querySelector("[data-search-root]");
+    const modalInput = dialog?.querySelector("[data-search-input]");
+
+    document.querySelectorAll("[data-search-root]").forEach(initSearchRoot);
+
+    function openSearch() {
+      if (!dialog || !modalRoot || !modalInput) return;
+      initSearchRoot(modalRoot);
+      if (!dialog.open) dialog.showModal();
+      window.setTimeout(() => modalInput.focus(), 0);
+    }
+
+    document.querySelectorAll("[data-search-trigger]").forEach((trigger) => {
+      trigger.addEventListener("click", openSearch);
+    });
+
+    document.querySelectorAll("[data-search-close]").forEach((trigger) => {
+      trigger.addEventListener("click", () => dialog?.close());
+    });
+
+    dialog?.addEventListener("click", (event) => {
+      if (event.target === dialog) dialog.close();
+    });
+
+    document.addEventListener("keydown", (event) => {
+      const isSearchShortcut = (event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k";
+      if (!isSearchShortcut) return;
+      event.preventDefault();
+      openSearch();
+    });
+  }
+
+  initSearch();
+</script>

package/src/components/TableOfContents.astro

@@ -0,0 +1,35 @@
+---
+import { renderEmojiShortcodes } from "../emoji";
+
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+interface Props {
+  headings: Heading[];
+}
+
+const headings = Astro.props.headings
+  .filter((heading) => heading.depth === 2 || heading.depth === 3)
+  .map((heading) => ({
+    ...heading,
+    text: renderEmojiShortcodes(heading.text),
+  }));
+---
+
+{
+  headings.length > 0 && (
+    <aside class="sticky top-20 hidden max-h-[calc(100dvh-5rem)] overflow-auto px-6 py-10 xl:block">
+      <h2 class="font-mono text-xs font-medium uppercase tracking-widest text-[var(--text-muted)]">On this page</h2>
+      <nav class="mt-4 grid gap-2 text-sm text-[var(--text-muted)]" data-emoji-shortcodes>
+        {headings.map((heading) => (
+          <a class:list={["border-l border-[var(--border-soft)] hover:text-[var(--text-strong)]", heading.depth === 3 ? "pl-6" : "pl-3"]} href={`#${heading.slug}`}>
+            {heading.text}
+          </a>
+        ))}
+      </nav>
+    </aside>
+  )
+}

package/src/components/TagList.astro

@@ -0,0 +1,19 @@
+---
+interface Props {
+  tags: string[];
+}
+
+const { tags } = Astro.props;
+---
+
+{
+  tags.length > 0 && (
+    <div class="flex flex-wrap gap-2">
+      {tags.map((tag) => (
+        <a class="rounded-full border border-[var(--border-soft)] px-2.5 py-1 font-mono text-xs text-[var(--text-muted)] hover:text-[var(--accent)]" href={`/tags/${tag}`}>
+          {tag}
+        </a>
+      ))}
+    </div>
+  )
+}

package/src/components/ThemeToggle.astro

@@ -0,0 +1,25 @@
+---
+---
+
+<button
+  type="button"
+  class="grid size-8 place-items-center rounded-full border border-[var(--border-soft)] text-sm text-[var(--text-muted)] hover:text-[var(--text-strong)]"
+  aria-label="Toggle color theme"
+  data-theme-toggle
+>
+  ◐
+</button>
+
+<script>
+  const button = document.querySelector("[data-theme-toggle]");
+  const modes = ["system", "light", "dark"];
+
+  button?.addEventListener("click", () => {
+    const current = document.documentElement.dataset.theme || "system";
+    const next = modes[(modes.indexOf(current) + 1) % modes.length];
+    localStorage.setItem("theme", next);
+    document.documentElement.dataset.theme = next;
+    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    document.documentElement.classList.toggle("dark", next === "dark" || (next === "system" && prefersDark));
+  });
+</script>

package/src/config.ts

@@ -0,0 +1,62 @@
+import type { BlogThemeOptions, NormalizedBlogThemeOptions } from "./types";
+
+export function normalizeOptions(options: BlogThemeOptions): NormalizedBlogThemeOptions {
+  return {
+    site: {
+      name: options.site.name,
+      title: options.site.title ?? options.site.name,
+      description: options.site.description ?? "",
+      lang: options.site.lang ?? "en",
+    },
+    author: {
+      name: options.author.name,
+      headline: options.author.headline ?? "",
+      bio: options.author.bio ?? "",
+      avatar: options.author.avatar,
+    },
+    postsPerPage: options.postsPerPage ?? 8,
+    nav:
+      options.nav ?? [
+        { label: "Posts", href: "/posts" },
+        { label: "Tags", href: "/tags" },
+        { label: "Categories", href: "/categories" },
+        { label: "About", href: "/about" },
+      ],
+    socialLinks: (options.socialLinks ?? []).map((link) => ({
+      ...link,
+      icon: link.icon ?? "link",
+    })),
+    theme: {
+      defaultMode: options.theme?.defaultMode ?? "system",
+      accent: options.theme?.accent ?? "sky",
+    },
+    diagrams: {
+      mermaid: options.diagrams?.mermaid ?? false,
+      plantuml: {
+        enabled: Boolean(options.diagrams?.plantuml),
+        serverUrl:
+          typeof options.diagrams?.plantuml === "object"
+            ? (options.diagrams.plantuml.serverUrl ?? "https://www.plantuml.com/plantuml/svg")
+            : "https://www.plantuml.com/plantuml/svg",
+      },
+    },
+    routes:
+      options.routes === false
+        ? {
+            home: false,
+            posts: false,
+            tags: false,
+            categories: false,
+            about: false,
+            search: false,
+          }
+        : {
+            home: options.routes?.home ?? true,
+            posts: options.routes?.posts ?? true,
+            tags: options.routes?.tags ?? true,
+            categories: options.routes?.categories ?? true,
+            about: options.routes?.about ?? true,
+            search: options.routes?.search ?? true,
+          },
+  };
+}

package/src/content.ts

@@ -0,0 +1,20 @@
+import { defineCollection } from "astro:content";
+import { glob } from "astro/loaders";
+import { z } from "astro/zod";
+
+const posts = defineCollection({
+  loader: glob({ base: "./src/content/posts", pattern: "**/*.{md,mdx}" }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string().default(""),
+    publishDate: z.union([z.date(), z.coerce.date()]).optional(),
+    updatedDate: z.union([z.date(), z.coerce.date()]).optional(),
+    category: z.string().default("Uncategorized"),
+    tags: z.array(z.string()).default([]),
+    cover: z.string().optional(),
+    draft: z.boolean().default(false),
+    featured: z.boolean().default(false),
+  }),
+});
+
+export const collections = { posts };

package/src/emoji.ts

@@ -0,0 +1,9 @@
+import { nameToEmoji } from "gemoji";
+
+export const emojiShortcodes = nameToEmoji;
+
+export function renderEmojiShortcodes(value: string) {
+  return value.replace(/:([+-]1|[a-z0-9_+-]+):/gi, (match, shortcode: string) => {
+    return emojiShortcodes[shortcode.toLowerCase()] ?? match;
+  });
+}

package/src/env.d.ts

@@ -0,0 +1,32 @@
+declare module "virtual:blog-theme/config" {
+  import type { NormalizedBlogThemeOptions } from "./types";
+
+  const config: NormalizedBlogThemeOptions;
+  export { config };
+  export default config;
+}
+
+declare module "virtual:blog-theme/about-content" {
+  import type { AstroComponentFactory } from "astro";
+  export const Content: AstroComponentFactory | null;
+}
+
+declare module "astro:content" {
+  export function getCollection(
+    collection: string,
+    filter?: (entry: any) => boolean
+  ): Promise<any[]>;
+
+  export function defineCollection(config: {
+    loader?: any;
+    schema?: any;
+  }): any;
+
+  export type CollectionEntry<T extends string> = {
+    id: string;
+    slug: string;
+    data: Record<string, any>;
+    body: string;
+    collection: T;
+  };
+}

package/src/index.ts

@@ -0,0 +1,136 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AstroIntegration } from "astro";
+import { unified } from "@astrojs/markdown-remark";
+import * as pagefind from "pagefind";
+import remarkGemoji from "remark-gemoji";
+import { normalizeOptions } from "./config";
+import { transformContentShortcodes } from "./shortcodes";
+import type { BlogThemeOptions } from "./types";
+
+function virtualConfigPlugin(config: unknown) {
+  const moduleId = "virtual:blog-theme/config";
+  const resolvedModuleId = `\0${moduleId}`;
+
+  return {
+    name: "astro-blog-theme-config",
+    resolveId(id: string) {
+      if (id === moduleId) return resolvedModuleId;
+    },
+    load(id: string) {
+      if (id === resolvedModuleId) {
+        return `export const config = ${JSON.stringify(config)}; export default config;`;
+      }
+    },
+  };
+}
+
+function virtualAboutPlugin() {
+  const moduleId = "virtual:blog-theme/about-content";
+  const resolvedModuleId = `\0${moduleId}`;
+  let root = "";
+
+  return {
+    name: "astro-blog-theme-about",
+    configResolved(config: any) {
+      root = config.root;
+    },
+    resolveId(id: string) {
+      if (id === moduleId) return resolvedModuleId;
+    },
+    load(id: string) {
+      if (id !== resolvedModuleId) return;
+      const md = resolve(root, "src/content/about.md");
+      const mdx = resolve(root, "src/content/about.mdx");
+      const aboutPath = existsSync(md) ? md : existsSync(mdx) ? mdx : null;
+      if (aboutPath) {
+        return `export { Content } from ${JSON.stringify(aboutPath)}`;
+      }
+      return `export const Content = null`;
+    },
+  };
+}
+
+function contentShortcodePlugin() {
+  return {
+    name: "astro-blog-theme-content-shortcodes",
+    enforce: "pre" as const,
+    transform(code: string, id: string) {
+      if (!/\.(md|mdx)(?:[?#].*)?$/.test(id) || !code.includes("{{<")) return;
+      return {
+        code: transformContentShortcodes(code),
+        map: null,
+      };
+    },
+  };
+}
+
+function route(path: string) {
+  return fileURLToPath(new URL(path, import.meta.url));
+}
+
+export default function blogTheme(options: BlogThemeOptions): AstroIntegration {
+  const config = normalizeOptions(options);
+
+  return {
+    name: "@guzhongren/sha",
+    hooks: {
+      "astro:config:setup": ({ injectRoute, updateConfig }) => {
+        updateConfig({
+          markdown: {
+            processor: unified({ remarkPlugins: [remarkGemoji] }),
+          },
+          vite: {
+            plugins: [contentShortcodePlugin(), virtualConfigPlugin(config), virtualAboutPlugin()],
+          },
+        });
+
+        if (config.routes.home) injectRoute({ pattern: "/", entrypoint: route("./pages/index.astro") });
+        if (config.routes.posts) injectRoute({ pattern: "/posts", entrypoint: route("./pages/posts/index.astro") });
+        if (config.routes.posts) {
+          injectRoute({ pattern: "/posts/[...slug]", entrypoint: route("./pages/posts/[...slug].astro") });
+          injectRoute({ pattern: "/posts/page/[page]", entrypoint: route("./pages/posts/page/[page].astro") });
+        }
+        if (config.routes.tags) injectRoute({ pattern: "/tags", entrypoint: route("./pages/tags/index.astro") });
+        if (config.routes.tags) injectRoute({ pattern: "/tags/[tag]", entrypoint: route("./pages/tags/[tag].astro") });
+        if (config.routes.categories) {
+          injectRoute({ pattern: "/categories", entrypoint: route("./pages/categories/index.astro") });
+          injectRoute({ pattern: "/categories/[category]", entrypoint: route("./pages/categories/[category].astro") });
+        }
+        if (config.routes.about) injectRoute({ pattern: "/about", entrypoint: route("./pages/about.astro") });
+        if (config.routes.search) injectRoute({ pattern: "/search", entrypoint: route("./pages/search.astro") });
+      },
+      "astro:build:done": async ({ dir }) => {
+        if (!config.routes.search) return;
+
+        const sitePath = fileURLToPath(dir);
+        const outputPath = fileURLToPath(new URL("./pagefind", dir));
+        const { index, errors: createErrors } = await pagefind.createIndex({
+          rootSelector: "[data-pagefind-body]",
+          includeCharacters: "_-:/#.",
+        });
+
+        if (!index || createErrors.length > 0) {
+          throw new Error(`Pagefind index creation failed: ${createErrors.join("; ") || "unknown error"}`);
+        }
+
+        try {
+          const addResult = await index.addDirectory({ path: sitePath });
+          if (addResult.errors.length > 0) {
+            throw new Error(addResult.errors.join("; "));
+          }
+
+          const writeResult = await index.writeFiles({ outputPath });
+          if (writeResult.errors.length > 0) {
+            throw new Error(writeResult.errors.join("; "));
+          }
+        } finally {
+          await pagefind.close();
+        }
+      },
+    },
+  };
+}
+
+export type { BlogThemeOptions } from "./types";

package/src/layouts/BaseLayout.astro

@@ -0,0 +1,59 @@
+---
+import "../styles/global.css";
+import Header from "../components/Header.astro";
+import Footer from "../components/Footer.astro";
+import DiagramEnhancer from "../components/DiagramEnhancer.astro";
+import CodeCopyEnhancer from "../components/CodeCopyEnhancer.astro";
+import EmojiEnhancer from "../components/EmojiEnhancer.astro";
+import EChartsEnhancer from "../components/EChartsEnhancer.astro";
+import SearchEnhancer from "../components/SearchEnhancer.astro";
+import config from "virtual:blog-theme/config";
+
+interface Props {
+  title?: string;
+  description?: string;
+}
+
+const title = Astro.props.title ? `${Astro.props.title} - ${config.site.title}` : config.site.title;
+const description = Astro.props.description ?? config.site.description;
+const defaultMode = config.theme.defaultMode;
+---
+
+<!doctype html>
+<html lang={config.site.lang} data-default-theme={defaultMode}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content={description} />
+    {config.author.avatar && (
+      <>
+        <link rel="icon" href={config.author.avatar} />
+        <link rel="apple-touch-icon" href={config.author.avatar} />
+      </>
+    )}
+    <title>{title}</title>
+    <script is:inline define:vars={{ defaultMode }}>
+      const stored = localStorage.getItem("theme");
+      const mode = stored || defaultMode;
+      const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+      document.documentElement.classList.toggle("dark", mode === "dark" || (mode === "system" && prefersDark));
+      document.documentElement.dataset.theme = mode;
+    </script>
+  </head>
+  <body class="min-h-dvh bg-[var(--page-bg)] text-[var(--text-body)] antialiased">
+    <Header />
+    <div class="mx-auto grid min-h-dvh max-w-7xl grid-cols-1 pt-14 lg:grid-cols-[2rem_minmax(0,1fr)_2rem]">
+      <div class="gutter-stripes hidden border-x border-[var(--border-soft)] lg:block" aria-hidden="true"></div>
+      <main id="main-content">
+        <slot />
+      </main>
+      <div class="gutter-stripes hidden border-x border-[var(--border-soft)] lg:block" aria-hidden="true"></div>
+    </div>
+    <Footer />
+    <EmojiEnhancer />
+    <EChartsEnhancer />
+    <CodeCopyEnhancer />
+    {config.routes.search && <SearchEnhancer />}
+    {(config.diagrams.mermaid || config.diagrams.plantuml.enabled) && <DiagramEnhancer diagrams={config.diagrams} />}
+  </body>
+</html>

package/src/pages/about.astro

@@ -0,0 +1,25 @@
+---
+import BaseLayout from "../layouts/BaseLayout.astro";
+import ProfileIntro from "../components/ProfileIntro.astro";
+import config from "virtual:blog-theme/config";
+import { Content } from "virtual:blog-theme/about-content";
+---
+
+<BaseLayout title="About" description={config.author.bio || config.site.description}>
+  <ProfileIntro />
+  <section class="mx-auto max-w-3xl px-4 pb-20 sm:px-6">
+    {Content ? (
+      <div class="prose" data-emoji-shortcodes>
+        <Content />
+      </div>
+    ) : (
+      <div class="prose">
+        <h2>About this site</h2>
+        <p>
+          This blog is built for technical notes, engineering decisions, and long-lived references. It keeps the author
+          signal visible without pushing the writing below a marketing-style landing page.
+        </p>
+      </div>
+    )}
+  </section>
+</BaseLayout>

package/src/pages/categories/[category].astro

@@ -0,0 +1,30 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import PostList from "../../components/PostList.astro";
+import { isPublished, sortPosts, uniqueSorted } from "../../utils";
+
+export async function getStaticPaths() {
+  const allPosts = (await getCollection("posts")).filter(isPublished);
+  const categories = uniqueSorted(allPosts.map((post) => post.data.category));
+  return categories.map((category) => ({
+    params: { category },
+    props: {
+      category,
+      posts: sortPosts(allPosts.filter((post) => post.data.category === category)),
+    },
+  }));
+}
+
+const { category, posts } = Astro.props;
+---
+
+<BaseLayout title={`Category: ${category}`} description={`Posts in ${category}`}>
+  <section class="mx-auto max-w-4xl px-4 py-12 sm:px-6">
+    <p class="font-mono text-xs font-medium uppercase tracking-widest text-[var(--text-muted)]">Category</p>
+    <h1 class="mt-3 text-4xl font-semibold tracking-tight text-[var(--text-strong)]">{category}</h1>
+    <div class="mt-8">
+      <PostList posts={posts} />
+    </div>
+  </section>
+</BaseLayout>

package/src/pages/categories/index.astro

@@ -0,0 +1,18 @@
+---
+import { getCollection } from "astro:content";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import { isPublished, uniqueSorted } from "../../utils";
+
+const posts = (await getCollection("posts")).filter(isPublished);
+const categories = uniqueSorted(posts.map((post) => post.data.category));
+---
+
+<BaseLayout title="Categories" description="Browse posts by category">
+  <section class="mx-auto max-w-4xl px-4 py-12 sm:px-6">
+    <p class="font-mono text-xs font-medium uppercase tracking-widest text-[var(--text-muted)]">Index</p>
+    <h1 class="mt-3 text-4xl font-semibold tracking-tight text-[var(--text-strong)]">Categories</h1>
+    <div class="mt-8 grid gap-3 sm:grid-cols-2">
+      {categories.map((category) => <a class="rounded-xl border border-[var(--border-soft)] bg-[var(--panel-bg)] p-4 text-[var(--text-strong)] hover:border-[var(--accent)]" href={`/categories/${category}`}>{category}</a>)}
+    </div>
+  </section>
+</BaseLayout>