@guzhongren/sha 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guzhongren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# Astro Blog Theme
+
+Config-driven Astro blog theme for technical writing. The theme is consumed as an Astro integration and injects default pages, layouts, and styling.
+
+## Install
+
+```sh
+pnpm add @guzhongren/sha astro @astrojs/mdx tailwindcss @tailwindcss/vite
+```
+
+## Configure
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import mdx from "@astrojs/mdx";
+import tailwindcss from "@tailwindcss/vite";
+import blogTheme from "@guzhongren/sha";
+
+export default defineConfig({
+  site: "https://example.com",
+  integrations: [
+    blogTheme({
+      site: {
+        name: "谷中的博客",
+        description: "全栈开发者的技术写作与知识沉淀",
+        lang: "zh-CN",
+      },
+      author: {
+        name: "谷中",
+        headline: "全栈开发者 / 技术顾问",
+        bio: "写工程实践、架构思考、开源与日常观察。",
+        avatar: "/avatar.svg",
+      },
+      diagrams: {
+        mermaid: true,
+        plantuml: {
+          serverUrl: "https://www.plantuml.com/plantuml/svg",
+        },
+      },
+    }),
+    mdx(),
+  ],
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});
+```
+
+Register `blogTheme(...)` before `mdx()` when using theme shortcodes such as ECharts. The theme pre-processes content before MDX parses it.
+
+## Content collections
+
+Astro requires the app to export content collections:
+
+```ts
+// src/content.config.ts
+export { collections } from "@guzhongren/sha/content";
+```
+
+Posts live in `src/content/posts`.
+
+```md
+---
+title: "用 Astro 构建技术博客主题"
+description: "一次从内容模型到主题集成方式的工程化拆解。"
+publishDate: 2026-07-31
+category: "Engineering"
+tags: ["Astro", "Tailwind", "Theme"]
+cover: "/covers/astro-theme.svg"
+featured: true
+draft: false
+---
+```
+
+## Routes
+
+The integration injects these routes by default:
+
+- `/`
+- `/posts`
+- `/posts/[...slug]`
+
+Post files can be placed directly under `src/content/posts` or nested by date, for example `src/content/posts/2024/05/12/my-post.mdx`. Nested posts are rendered at matching URLs such as `/posts/2024/05/12/my-post`.
+- `/tags`
+- `/tags/[tag]`
+- `/categories`
+- `/categories/[category]`
+- `/about`
+- `/search`
+
+Set `routes: false` to disable injected pages and use the exported components manually.
+
+## Diagrams
+
+Enable Mermaid and PlantUML from `astro.config.mjs`:
+
+```js
+blogTheme({
+  diagrams: {
+    mermaid: true,
+    plantuml: {
+      serverUrl: "https://www.plantuml.com/plantuml/svg",
+    },
+  },
+});
+```
+
+Use normal fenced code blocks in MDX:
+
+````md
+```mermaid
+flowchart TD
+  A --> B
+```
+
+```plantuml
+@startuml
+A -> B
+@enduml
+```
+````
+
+Mermaid is rendered client-side from the bundled `mermaid` package. PlantUML is rendered as an image using the configured PlantUML server.
+
+## ECharts
+
+Use Hugo-style shortcode blocks for ECharts options:
+
+````md
+{{< echarts >}}
+{
+  "title": { "text": "折线统计图", "left": "center" },
+  "xAxis": { "type": "category", "data": ["周一", "周二"] },
+  "yAxis": { "type": "value" },
+  "series": [{ "type": "line", "data": [120, 200] }]
+}
+{{< /echarts >}}
+````
+
+The theme converts the shortcode before MDX parsing and renders the chart client-side with the bundled `echarts` package.
+
+## Search
+
+The `/search` route and header search button use Pagefind full-text search. The theme builds the Pagefind index automatically after `astro build` when the search route is enabled.
+
+Search indexes only post detail pages marked by the theme, so drafts and listing pages are excluded from results. During `astro dev`, the Pagefind bundle may not exist yet; the search page keeps a static published-post fallback.
+
+## V1 limits
+
+- Single author.
+- No CMS.
+- No React/Vue dependency.
+- No component override framework.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@guzhongren/sha",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "个人 Astro 博客主题 — 开箱即用的内容驱动博客",
+  "license": "MIT",
+  "author": "guzhongren",
+  "keywords": ["astro", "astro-component", "astro-integration", "withastro", "blog", "theme"],
+  "files": ["src/", "README.md", "LICENSE"],
+  "exports": {
+    ".": "./src/index.ts",
+    "./content": "./src/content.ts",
+    "./styles.css": "./src/styles/global.css"
+  },
+  "scripts": {
+    "dev": "cd example && astro dev",
+    "sync": "cd example && astro sync",
+    "check": "cd example && astro check",
+    "build": "cd example && astro build"
+  },
+  "peerDependencies": {
+    "astro": "^7.0.0",
+    "@astrojs/mdx": "^7.0.0",
+    "@astrojs/markdown-remark": "^7.0.0",
+    "@tailwindcss/vite": "^4.0.0",
+    "tailwindcss": "^4.0.0"
+  },
+  "dependencies": {
+    "echarts": "^6.1.0",
+    "gemoji": "^8.1.0",
+    "mermaid": "^11.16.0",
+    "pagefind": "^1.5.2",
+    "plantuml-encoder": "^1.4.0",
+    "remark-gemoji": "^8.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2"
+  }
+}

package/src/avatar.ts

@@ -0,0 +1,3 @@
+export function avatarInitial(siteName: string, authorName: string) {
+  return [...(siteName.trim() || authorName.trim() || "B")][0]?.toUpperCase() ?? "B";
+}

package/src/components/Avatar.astro

@@ -0,0 +1,23 @@
+---
+import { avatarInitial } from "../avatar";
+import config from "virtual:blog-theme/config";
+
+interface Props {
+  size?: "sm" | "lg";
+  class?: string;
+}
+
+const { size = "sm", class: className } = Astro.props;
+const sizeClass = size === "lg" ? "size-24 text-4xl" : "size-7 text-xs";
+const initial = avatarInitial(config.site.name, config.author.name);
+---
+
+{
+  config.author.avatar ? (
+    <img class:list={["avatar-mark shrink-0 rounded-full object-cover", sizeClass, className]} src={config.author.avatar} alt={config.author.name} />
+  ) : (
+    <span class:list={["avatar-mark grid shrink-0 place-items-center rounded-full font-mono font-semibold text-[var(--text-muted)]", sizeClass, className]} aria-label={config.author.name}>
+      {initial}
+    </span>
+  )
+}

package/src/components/CodeCopyEnhancer.astro

@@ -0,0 +1,31 @@
+---
+---
+
+<script>
+  const blocks = [...document.querySelectorAll(".prose pre > code")];
+
+  blocks.forEach((code) => {
+    const pre = code.parentElement;
+    if (!pre || pre.parentElement?.classList.contains("code-copy-frame")) return;
+
+    const frame = document.createElement("div");
+    const button = document.createElement("button");
+
+    frame.className = "code-copy-frame";
+    button.type = "button";
+    button.className = "code-copy-button";
+    button.textContent = "Copy";
+    button.setAttribute("aria-label", "Copy code");
+
+    pre.replaceWith(frame);
+    frame.append(button, pre);
+
+    button.addEventListener("click", async () => {
+      await navigator.clipboard.writeText(code.textContent || "");
+      button.textContent = "Copied";
+      window.setTimeout(() => {
+        button.textContent = "Copy";
+      }, 1200);
+    });
+  });
+</script>

package/src/components/DiagramEnhancer.astro

@@ -0,0 +1,96 @@
+---
+import type { NormalizedBlogThemeOptions } from "../types";
+
+interface Props {
+  diagrams: NormalizedBlogThemeOptions["diagrams"];
+}
+
+const { diagrams } = Astro.props;
+---
+
+<script id="blog-theme-diagrams" type="application/json" set:html={JSON.stringify(diagrams)}></script>
+
+<script>
+  function readDiagramConfig() {
+    const element = document.getElementById("blog-theme-diagrams");
+    return element?.textContent ? JSON.parse(element.textContent) : null;
+  }
+
+  function diagramBlocks(language) {
+    return [
+      ...document.querySelectorAll(`pre[data-language="${language}"] > code`),
+      ...document.querySelectorAll(`pre > code.language-${language}`),
+    ];
+  }
+
+  function plantUmlBlocks() {
+    return [
+      ...diagramBlocks("plantuml"),
+      ...[...document.querySelectorAll('pre[data-language="plaintext"] > code')].filter((code) =>
+        (code.textContent || "").trimStart().startsWith("@startuml"),
+      ),
+    ];
+  }
+
+  async function renderPlantUml(diagrams) {
+    if (!diagrams.plantuml.enabled) return;
+
+    const blocks = plantUmlBlocks();
+    if (blocks.length === 0) return;
+
+    const { encode } = await import("plantuml-encoder");
+
+    blocks.forEach((code) => {
+      const pre = code.parentElement;
+      const source = code.textContent || "";
+      const figure = document.createElement("figure");
+      const img = document.createElement("img");
+      const serverUrl = diagrams.plantuml.serverUrl.replace(/\/$/, "");
+
+      figure.className = "diagram diagram-plantuml";
+      img.alt = "PlantUML diagram";
+      img.loading = "lazy";
+      img.src = `${serverUrl}/${encode(source)}`;
+      figure.append(img);
+      pre.replaceWith(figure);
+    });
+  }
+
+  async function renderMermaid(diagrams) {
+    if (!diagrams.mermaid) return;
+
+    const blocks = diagramBlocks("mermaid");
+    if (blocks.length === 0) return;
+
+    const { default: mermaid } = await import("mermaid/dist/mermaid.esm.min.mjs");
+    mermaid.initialize({
+      startOnLoad: false,
+      securityLevel: "strict",
+      theme: document.documentElement.classList.contains("dark") ? "dark" : "default",
+    });
+
+    await Promise.all(
+      blocks.map(async (code, index) => {
+        const pre = code.parentElement;
+        const source = code.textContent || "";
+        const figure = document.createElement("figure");
+        figure.className = "diagram diagram-mermaid";
+
+        try {
+          const { svg } = await mermaid.render(`mermaid-${index}`, source);
+          figure.innerHTML = svg;
+          pre.replaceWith(figure);
+        } catch (error) {
+          pre.dataset.diagramError = "mermaid";
+          console.error(error);
+        }
+      }),
+    );
+  }
+
+  const diagrams = readDiagramConfig();
+  if (diagrams) {
+    renderPlantUml(diagrams);
+    renderMermaid(diagrams);
+  }
+</script>

package/src/components/EChartsEnhancer.astro

@@ -0,0 +1,31 @@
+<script>
+  const chartBlocks = [...document.querySelectorAll("[data-echarts-options]")];
+
+  if (chartBlocks.length > 0) {
+    const echarts = await import("echarts");
+
+    chartBlocks.forEach((chart, index) => {
+      const figure = chart.closest(".echarts-frame");
+      const caption = document.createElement("figcaption");
+
+      chart.setAttribute("role", "img");
+      chart.setAttribute("aria-label", `ECharts chart ${index + 1}`);
+      caption.className = "utility-note echarts-error";
+      caption.hidden = true;
+      figure?.append(caption);
+
+      try {
+        const options = JSON.parse(decodeURIComponent(chart.getAttribute("data-echarts-options") || "%7B%7D"));
+        const instance = echarts.init(chart, document.documentElement.classList.contains("dark") ? "dark" : undefined);
+        instance.setOption(options);
+
+        const resize = () => instance.resize();
+        window.addEventListener("resize", resize);
+      } catch (error) {
+        caption.hidden = false;
+        caption.textContent = "Invalid ECharts options.";
+        console.error(error);
+      }
+    });
+  }
+</script>

package/src/components/EmojiEnhancer.astro

@@ -0,0 +1,30 @@
+---
+import { emojiShortcodes } from "../emoji";
+---
+
+<script is:inline define:vars={{ emojiShortcodes }}>
+  const shortcodePattern = /:([+-]1|[a-z0-9_+-]+):/gi;
+  const skipSelector = "code, pre, kbd, samp, script, style, textarea";
+  const roots = document.querySelectorAll("[data-emoji-shortcodes]");
+
+  function renderShortcodes(value) {
+    return value.replace(shortcodePattern, (match, shortcode) => emojiShortcodes[shortcode.toLowerCase()] || match);
+  }
+
+  function enhance(root) {
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+      acceptNode(node) {
+        if (!node.nodeValue || !shortcodePattern.test(node.nodeValue)) return NodeFilter.FILTER_REJECT;
+        shortcodePattern.lastIndex = 0;
+        if (node.parentElement?.closest(skipSelector)) return NodeFilter.FILTER_REJECT;
+        return NodeFilter.FILTER_ACCEPT;
+      },
+    });
+
+    const nodes = [];
+    while (walker.nextNode()) nodes.push(walker.currentNode);
+    for (const node of nodes) node.nodeValue = renderShortcodes(node.nodeValue || "");
+  }
+
+  for (const root of roots) enhance(root);
+</script>

package/src/components/Footer.astro

@@ -0,0 +1,12 @@
+---
+import config from "virtual:blog-theme/config";
+---
+
+<footer class="border-t border-[var(--border-soft)] bg-[var(--page-bg)]">
+  <div class="mx-auto flex max-w-7xl flex-col gap-4 px-4 py-10 text-sm text-[var(--text-muted)] sm:flex-row sm:items-center sm:justify-between sm:px-6">
+    <p>&copy; {new Date().getFullYear()} {config.author.name}</p>
+    <div class="flex flex-wrap gap-4">
+      {config.nav.map((item) => <a class="hover:text-[var(--text-strong)]" href={item.href}>{item.label}</a>)}
+    </div>
+  </div>
+</footer>

package/src/components/Header.astro

@@ -0,0 +1,30 @@
+---
+import config from "virtual:blog-theme/config";
+import Avatar from "./Avatar.astro";
+import ThemeToggle from "./ThemeToggle.astro";
+---
+
+<header class="fixed inset-x-0 top-0 z-50 border-b border-[var(--border-soft)] bg-[var(--page-bg)]/90 backdrop-blur">
+  <div class="mx-auto flex h-14 max-w-7xl items-center justify-between gap-4 px-4 sm:px-6">
+    <a href="/" class="flex min-w-0 items-center gap-2 font-semibold text-[var(--text-strong)]" aria-label={config.site.name}>
+      <Avatar size="sm" />
+      <span class="truncate">{config.site.name}</span>
+    </a>
+    <nav class="header-nav hidden items-center text-sm font-medium text-[var(--text-muted)] md:flex" aria-label="Primary">
+      {config.nav.map((item) => <a class="hover:text-[var(--text-strong)]" href={item.href}>{item.label}</a>)}
+      {
+        config.routes.search && (
+          <button class="search-trigger" type="button" data-search-trigger aria-label="Open search">
+            <span>Search</span>
+            <kbd>⌘K</kbd>
+          </button>
+        )
+      }
+      <ThemeToggle />
+    </nav>
+    <div class="flex items-center gap-3 md:hidden">
+      {config.routes.search && <button class="text-sm font-medium text-[var(--text-muted)] hover:text-[var(--text-strong)]" type="button" data-search-trigger>Search</button>}
+      <ThemeToggle />
+    </div>
+  </div>
+</header>

package/src/components/Pagination.astro

@@ -0,0 +1,29 @@
+---
+interface Props {
+  current: number;
+  total: number;
+  base: string;
+}
+
+const { current, total, base } = Astro.props;
+---
+
+{
+  total > 1 && (
+    <nav class="mt-12 flex items-center justify-between border-t border-[var(--border-soft)] pt-8" aria-label="Pagination">
+      {current > 1 ? (
+        <a class="text-sm font-medium text-[var(--text-muted)] hover:text-[var(--accent)]" href={current === 2 ? base : `${base}page/${current - 1}/`}>
+          ← Newer posts
+        </a>
+      ) : <span />}
+      <span class="text-sm text-[var(--text-muted)]">
+        Page {current} of {total}
+      </span>
+      {current < total ? (
+        <a class="text-sm font-medium text-[var(--text-muted)] hover:text-[var(--accent)]" href={`${base}page/${current + 1}/`}>
+          Older posts →
+        </a>
+      ) : <span />}
+    </nav>
+  )
+}

package/src/components/PostCard.astro

@@ -0,0 +1,44 @@
+---
+import type { Post } from "../utils";
+import { formatDate, postHref } from "../utils";
+import { renderEmojiShortcodes } from "../emoji";
+import TagList from "./TagList.astro";
+
+interface Props {
+  post: Post;
+  featured?: boolean;
+}
+
+const { post, featured = false } = Astro.props;
+const title = renderEmojiShortcodes(post.data.title);
+const description = renderEmojiShortcodes(post.data.description);
+---
+
+<article
+  class:list={[
+    "post-item group line-b px-3 py-8 sm:px-4",
+    post.data.cover && (featured ? "grid gap-6 md:grid-cols-[minmax(0,1.15fr)_minmax(18rem,0.85fr)] md:items-center" : "grid gap-5 sm:grid-cols-[minmax(0,1fr)_9rem] sm:items-start"),
+  ]}
+>
+  {
+    post.data.cover && (
+      <a href={postHref(post)} class:list={["surface-block block overflow-hidden p-1", !featured && "sm:order-last"]}>
+        <img class:list={["w-full rounded-lg object-cover", featured ? "aspect-[16/8] md:aspect-[16/10]" : "aspect-[16/9] sm:aspect-square"]} src={post.data.cover} alt="" />
+      </a>
+    )
+  }
+  <div>
+    <p class="font-mono text-xs/6 font-medium uppercase tracking-widest text-[var(--text-muted)]">
+      <a class="hover:text-[var(--accent)]" href={`/categories/${post.data.category}`}>{post.data.category}</a>
+      <span class="px-1 text-[var(--border-soft)]" aria-hidden="true">/</span>
+      {post.data.publishDate && <time datetime={post.data.publishDate.toISOString()}>{formatDate(post.data.publishDate)}</time>}
+    </p>
+    <h2 class:list={["mt-2 font-semibold tracking-tight text-[var(--text-strong)] group-hover:text-[var(--accent)]", featured ? "text-3xl" : "text-xl"]}>
+      <a href={postHref(post)}>{title}</a>
+    </h2>
+    <p class="mt-3 text-sm/7 text-[var(--text-muted)]">{description}</p>
+    <div class="mt-5">
+      <TagList tags={post.data.tags} />
+    </div>
+  </div>
+</article>

package/src/components/PostList.astro

@@ -0,0 +1,15 @@
+---
+import type { Post } from "../utils";
+import PostCard from "./PostCard.astro";
+
+interface Props {
+  posts: Post[];
+  featuredFirst?: boolean;
+}
+
+const { posts, featuredFirst = false } = Astro.props;
+---
+
+<div>
+  {posts.map((post, index) => <PostCard post={post} featured={featuredFirst && index === 0} />)}
+</div>

package/src/components/ProfileIntro.astro

@@ -0,0 +1,17 @@
+---
+import Avatar from "./Avatar.astro";
+import config from "virtual:blog-theme/config";
+---
+
+<section class="mx-auto max-w-4xl px-4 py-12 text-center sm:px-6 sm:py-16">
+  <div class="section-frame rounded-xl px-4 py-10 sm:px-8">
+  <div class="utility-note mb-5 text-xs">prose dark:system latest-posts</div>
+  <Avatar size="lg" class="mx-auto profile-mark" />
+  <h1 class="mt-5 text-2xl font-semibold tracking-tight text-[var(--text-strong)]">{config.site.name}</h1>
+  {config.author.headline && <p class="mt-3 text-sm text-[var(--text-body)]">{config.author.headline}</p>}
+  {config.author.bio && <p class="mx-auto mt-4 max-w-2xl text-sm/7 text-[var(--text-muted)]">{config.author.bio}</p>}
+  <div class="mt-5 flex justify-center gap-4 text-sm font-medium text-[var(--text-muted)]">
+    {config.socialLinks.map((link) => <a class="hover:text-[var(--accent)]" href={link.href}>{link.label}</a>)}
+  </div>
+  </div>
+</section>