hd-garden 0.3.0

package/app/components/Webmentions.tsx

@@ -0,0 +1,194 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import {
+  ArrowSquareOut,
+  Heart,
+  LinkSimple,
+  Quotes,
+  Repeat,
+} from "@phosphor-icons/react";
+
+type WebmentionEntry = {
+  author?: {
+    name?: string;
+    url?: string;
+    photo?: string;
+  };
+  url?: string;
+  published?: string;
+  "wm-received"?: string;
+  "wm-property"?: string;
+  "wm-private"?: boolean;
+  content?: {
+    text?: string;
+  };
+};
+
+type WebmentionFeed = {
+  children?: WebmentionEntry[];
+};
+
+const reactionProperties = new Set(["like-of", "repost-of", "bookmark-of"]);
+
+export function Webmentions({
+  target,
+  endpoint,
+}: {
+  target: string;
+  endpoint?: string;
+}) {
+  const [entries, setEntries] = useState<WebmentionEntry[]>([]);
+  const [loading, setLoading] = useState(Boolean(endpoint));
+  const [failed, setFailed] = useState(false);
+
+  useEffect(() => {
+    if (!endpoint) return;
+    const controller = new AbortController();
+    const url = new URL(endpoint);
+    url.searchParams.set("target", target);
+
+    fetch(url, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" },
+    })
+      .then((response) => {
+        if (!response.ok) throw new Error("Webmentions unavailable");
+        return response.json() as Promise<WebmentionFeed>;
+      })
+      .then((feed) => {
+        setEntries(
+          (feed.children ?? []).filter(
+            (entry) => !entry["wm-private"] && entry.url,
+          ),
+        );
+        setFailed(false);
+      })
+      .catch((error: unknown) => {
+        if (error instanceof DOMException && error.name === "AbortError") return;
+        setFailed(true);
+      })
+      .finally(() => setLoading(false));
+
+    return () => controller.abort();
+  }, [endpoint, target]);
+
+  const reactions = useMemo(
+    () =>
+      entries.filter((entry) =>
+        reactionProperties.has(entry["wm-property"] ?? ""),
+      ),
+    [entries],
+  );
+  const responses = useMemo(
+    () =>
+      entries.filter(
+        (entry) => !reactionProperties.has(entry["wm-property"] ?? ""),
+      ),
+    [entries],
+  );
+
+  return (
+    <section className="webmentions" aria-labelledby="webmentions-heading">
+      <div className="webmention-title">
+        <LinkSimple size={21} />
+        <div>
+          <h2 id="webmentions-heading">来自开放网络的回应</h2>
+          <p>引用、喜欢、转发和站外回复会通过 Webmention 回到这里。</p>
+        </div>
+      </div>
+
+      {!endpoint && (
+        <div className="integration-notice">
+          <Quotes size={20} weight="fill" />
+          <p>接收与展示代码已经就绪，注册正式域名后即可开始收集回应。</p>
+        </div>
+      )}
+
+      {endpoint && loading && (
+        <p className="integration-status" role="status">
+          正在读取开放网络回应…
+        </p>
+      )}
+
+      {endpoint && failed && (
+        <p className="integration-status" role="status">
+          暂时无法读取回应，稍后会自动恢复。
+        </p>
+      )}
+
+      {endpoint && !loading && !failed && entries.length === 0 && (
+        <div className="integration-notice">
+          <Quotes size={20} weight="fill" />
+          <p>还没有站外回应。任何链接到这篇文章的网站都可以向它发送 Webmention。</p>
+        </div>
+      )}
+
+      {reactions.length > 0 && (
+        <div className="webmention-reactions">
+          <span>
+            <Heart size={16} weight="fill" />
+            <Repeat size={16} />
+            {reactions.length} 个喜欢、转发或收藏
+          </span>
+          <div className="webmention-facepile" aria-label="回应者">
+            {reactions.slice(0, 16).map((entry, index) => (
+              <a
+                href={entry.url}
+                target="_blank"
+                rel="noopener noreferrer"
+                aria-label={entry.author?.name ?? "查看站外回应"}
+                key={`${entry.url}-${index}`}
+              >
+                {entry.author?.photo ? (
+                  // eslint-disable-next-line @next/next/no-img-element
+                  <img
+                    src={entry.author.photo}
+                    alt=""
+                    loading="lazy"
+                    referrerPolicy="no-referrer"
+                  />
+                ) : (
+                  <span>{(entry.author?.name ?? "?").slice(0, 1)}</span>
+                )}
+              </a>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {responses.length > 0 && (
+        <div className="webmention-list">
+          {responses.map((entry, index) => {
+            const received = entry.published ?? entry["wm-received"];
+            return (
+              <article key={`${entry.url}-${index}`}>
+                <header>
+                  <strong>{entry.author?.name ?? "开放网络访客"}</strong>
+                  {received && (
+                    <time dateTime={received}>
+                      {new Intl.DateTimeFormat("zh-CN", {
+                        year: "numeric",
+                        month: "2-digit",
+                        day: "2-digit",
+                      }).format(new Date(received))}
+                    </time>
+                  )}
+                </header>
+                {entry.content?.text && <p>{entry.content.text}</p>}
+                <a
+                  href={entry.url}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                >
+                  查看原文
+                  <ArrowSquareOut size={14} />
+                </a>
+              </article>
+            );
+          })}
+        </div>
+      )}
+    </section>
+  );
+}

package/app/components/WidgetChart.tsx

@@ -0,0 +1,222 @@
+"use client";
+
+import { ArrowUpRight, Browser, CaretDown, FilePdf } from "@phosphor-icons/react";
+import { useEffect, useRef, useState } from "react";
+import { parse } from "yaml";
+
+type WidgetKind = "chart" | "html" | "pdf";
+
+type WidgetData = {
+  src: string;
+  caption: string;
+  kind: WidgetKind;
+  height?: number;
+};
+
+const widgetKinds = new Set<WidgetKind>(["chart", "html", "pdf"]);
+
+function kindFromInput(src: string, requested: unknown): WidgetKind | null {
+  if (typeof requested === "string" && widgetKinds.has(requested.trim() as WidgetKind)) {
+    return requested.trim() as WidgetKind;
+  }
+  if (/\.pdf(?:[?#]|$)/iu.test(src)) return "pdf";
+  if (/\.html(?:[?#]|$)/iu.test(src)) return "chart";
+  return null;
+}
+
+function readWidgetData(source: string): WidgetData | null {
+  try {
+    const value = parse(source.trim()) as unknown;
+    if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+    const input = value as Record<string, unknown>;
+    if (typeof input.src !== "string" || !input.src.trim()) return null;
+    if (typeof input.caption !== "string" || !input.caption.trim()) return null;
+
+    const src = input.src.trim();
+    if (!src.startsWith("/") || src.startsWith("//")) return null;
+    const kind = kindFromInput(src, input.kind);
+    if (!kind) return null;
+
+    const height =
+      typeof input.height === "number" && Number.isFinite(input.height) && input.height > 0
+        ? Math.round(input.height)
+        : undefined;
+    return { src, caption: input.caption.trim(), kind, height };
+  } catch {
+    return null;
+  }
+}
+
+function themeFromDocument() {
+  return document.documentElement.getAttribute("data-theme") === "dark" ? "dark" : "light";
+}
+
+function withTheme(src: string, theme: "light" | "dark") {
+  const [path, query = ""] = src.split("?", 2);
+  const params = new URLSearchParams(query);
+  params.set("theme", theme);
+  return `${path}?${params.toString()}`;
+}
+
+function fileName(src: string) {
+  const path = src.split(/[?#]/u, 1)[0] ?? src;
+  const segment = path.split("/").filter(Boolean).pop() ?? path;
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+function DocumentThumb({ kind }: { kind: "html" | "pdf" }) {
+  return (
+    <span className={`garden-doc-thumb garden-doc-thumb-${kind}`} aria-hidden="true">
+      <span className="garden-doc-thumb-bar" />
+      <span className="garden-doc-thumb-line" />
+      <span className="garden-doc-thumb-line" />
+      <span className="garden-doc-thumb-line garden-doc-thumb-line-short" />
+    </span>
+  );
+}
+
+export function WidgetChart({ source }: { source: string }) {
+  const data = readWidgetData(source);
+  const src = data?.src;
+  const kind = data?.kind;
+  const isDocument = kind === "html" || kind === "pdf";
+  const frameRef = useRef<HTMLIFrameElement>(null);
+  const [theme, setTheme] = useState<"light" | "dark">("light");
+  const [height, setHeight] = useState(data?.height ?? (data?.kind === "pdf" ? 720 : 360));
+  const [expanded, setExpanded] = useState(false);
+  const [armed, setArmed] = useState(!isDocument);
+  const active = Boolean(src && kind && armed);
+  const frameSrc =
+    !active || !src
+      ? undefined
+      : kind === "pdf"
+        ? src
+        : withTheme(src, theme);
+
+  useEffect(() => {
+    const root = document.documentElement;
+    const sync = () => setTheme(themeFromDocument());
+    sync();
+    const observer = new MutationObserver(sync);
+    observer.observe(root, { attributes: true, attributeFilter: ["data-theme"] });
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    if (!src || !kind || !active || kind === "pdf") return;
+
+    const onMessage = (event: MessageEvent) => {
+      const frame = frameRef.current;
+      if (!frame || event.source !== frame.contentWindow) return;
+      const payload = event.data;
+      if (
+        !payload ||
+        typeof payload !== "object" ||
+        (payload as { source?: unknown }).source !== "garden-chart" ||
+        typeof (payload as { height?: unknown }).height !== "number" ||
+        !Number.isFinite((payload as { height: number }).height)
+      ) {
+        return;
+      }
+      setHeight(Math.max(160, Math.min(1600, Math.round((payload as { height: number }).height))));
+    };
+
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [src, kind, active]);
+
+  if (!data) {
+    return (
+      <p className="external-embed-error">
+        无法解析这个嵌入块。请在与 Markdown 同名的目录里放一份 .html 或 .pdf，并在围栏中写 src 与 caption。
+      </p>
+    );
+  }
+
+  const frame = (
+    <div className="garden-chart-frame" style={{ height: isDocument ? data.height : height }}>
+      <iframe
+        ref={frameRef}
+        src={frameSrc}
+        title={data.caption}
+        sandbox={data.kind === "pdf" ? undefined : "allow-scripts"}
+        referrerPolicy="no-referrer"
+      />
+    </div>
+  );
+
+  if (!isDocument) {
+    return (
+      <figure className="garden-chart">
+        {frame}
+        <figcaption>
+          <span>{data.caption}</span>
+          <a href={data.src} target="_blank" rel="noopener noreferrer">
+            打开页面
+          </a>
+        </figcaption>
+        <noscript>
+          <p>{data.caption}</p>
+        </noscript>
+      </figure>
+    );
+  }
+
+  const Icon = data.kind === "pdf" ? FilePdf : Browser;
+  const kindLabel = data.kind === "pdf" ? "PDF" : "页面";
+  const openLabel = data.kind === "pdf" ? "打开 PDF" : "打开页面";
+
+  return (
+    <figure
+      className={`garden-chart garden-doc garden-doc-${data.kind}`}
+      data-expanded={expanded ? "true" : "false"}
+    >
+      <div className="garden-doc-launch">
+        <button
+          type="button"
+          className="garden-doc-toggle"
+          aria-expanded={expanded}
+          onClick={() => {
+            setExpanded((current) => {
+              const next = !current;
+              if (next) setArmed(true);
+              return next;
+            });
+          }}
+        >
+          <DocumentThumb kind={data.kind} />
+          <span className="garden-doc-copy">
+            <small>
+              <Icon size={15} weight="regular" />
+              {kindLabel} · {fileName(data.src)}
+            </small>
+            <strong>{data.caption}</strong>
+          </span>
+          <span className="garden-doc-action">
+            {expanded ? "收起" : "展开"}
+            <CaretDown size={14} className="garden-doc-caret" />
+          </span>
+        </button>
+        <a className="garden-doc-open" href={data.src} target="_blank" rel="noopener noreferrer">
+          {openLabel}
+          <ArrowUpRight size={14} />
+        </a>
+      </div>
+      <div className="garden-doc-pane">
+        <div className="garden-doc-pane-inner">{armed ? frame : null}</div>
+      </div>
+      <noscript>
+        <p>
+          {data.caption}{" "}
+          <a href={data.src} target="_blank" rel="noopener noreferrer">
+            {openLabel}
+          </a>
+        </p>
+      </noscript>
+    </figure>
+  );
+}

package/app/garden/page.tsx

@@ -0,0 +1,284 @@
+import { ArrowRight, ArrowUpRight, GithubLogo } from "@phosphor-icons/react/ssr";
+import { GardenAdminGuide } from "../components/GardenAdminGuide";
+import { GardenContentGuide } from "../components/GardenContentGuide";
+import { GardenMediaGuide } from "../components/GardenMediaGuide";
+import { PageIntro } from "../components/PageIntro";
+import { TableOfContents } from "../components/TableOfContents";
+import { siteConfig } from "../site.config";
+
+export const metadata = {
+  title: `Garden · ${siteConfig.pages.garden.title}`,
+  description:
+    "一个以 Markdown 为内容源、通过 GitHub Pages 发布的个人博客框架，支持博文、随想、专栏、搜索、RSS 与多媒体。",
+};
+
+const systemCapabilities = [
+  {
+    title: "Markdown 与多媒体",
+    description:
+      "兼容 Typora 常用写法，支持 GFM、代码高亮、数学公式、Mermaid，以及图片、音视频、平台嵌入和网页摘要。",
+  },
+  {
+    title: "阅读与内容发现",
+    description:
+      "自动生成文章目录、阅读时长、字数、前后篇导航、主题归档和全文搜索，搜索结果会高亮命中内容。",
+  },
+  {
+    title: "发布与订阅",
+    description:
+      "推送到 main 后由 GitHub Actions 构建并发布到 GitHub Pages，同时生成 RSS、sitemap、robots 和 Open Graph 元数据。",
+  },
+  {
+    title: "开放集成",
+    description:
+      "需要时可以接入 Giscus 评论、Webmention、无 Cookie 统计和对象存储；不配置这些服务也能正常写作和发布。",
+  },
+];
+
+const responsibilityBoundaries = [
+  {
+    number: "01",
+    title: "Garden 框架",
+    description:
+      "公开模板和上游代码，负责内容模型、页面生成与发布工作流。使用模板后，不需要在这里保存个人文章。",
+  },
+  {
+    number: "02",
+    title: "源码仓库",
+    description:
+      "文章、随想、专栏、配置和草稿的唯一真源。你直接编辑这里，管理后台也只向这里提交内容。",
+  },
+  {
+    number: "03",
+    title: "公开博客",
+    description:
+      "GitHub Actions 从源码生成静态文件，再交给 GitHub Pages。双仓模式下，公开产物仓库只保存生成结果，不手工修改。",
+  },
+  {
+    number: "04",
+    title: "可选服务",
+    description:
+      "管理后台补充随想发布和媒体上传；Giscus 评论可以使用独立公开仓库。它们都不会替代源码仓库。",
+  },
+];
+
+const gardenHeadings = [
+  { depth: 2, text: "仓库和服务怎么分工", id: "garden-responsibilities-title" },
+  { depth: 2, text: "博文、随想和专栏", id: "garden-guide-title" },
+  { depth: 3, text: "写一篇文章", id: "write-post" },
+  { depth: 3, text: "发布一条随想", id: "write-thought" },
+  { depth: 3, text: "创建一个专栏", id: "make-column" },
+  { depth: 2, text: "高级嵌入", id: "garden-media-title" },
+  { depth: 2, text: "系统能力", id: "garden-system-title" },
+  { depth: 2, text: "管理后台", id: "garden-admin-title" },
+  { depth: 2, text: "安装与配置", id: "garden-setup-title" },
+];
+
+export default function GardenPage() {
+  return (
+    <main className="page-shell garden-page">
+      <div className="garden-page-toc">
+        <TableOfContents headings={gardenHeadings} label="本页目录" />
+      </div>
+
+      <PageIntro
+        eyebrow="GARDEN / 博客框架"
+        title={siteConfig.pages.garden.title}
+        subtitle={siteConfig.pages.garden.subtitle}
+      >
+        <p className="garden-lede">
+          Garden 是公开的博客框架，不是你的内容仓库。使用模板后，你只在自己的源码仓库里维护
+          Markdown；推送后，GitHub Actions 会把它生成并发布为公开博客。
+        </p>
+        <div className="garden-actions">
+          <a
+            className="garden-primary-link"
+            href="https://github.com/hedon954/garden"
+            target="_blank"
+            rel="noreferrer"
+          >
+            <GithubLogo size={18} weight="fill" />
+            在 GitHub 查看源码
+            <ArrowUpRight size={16} />
+          </a>
+          <a
+            className="inline-cta"
+            href="#setup"
+          >
+            查看安装与配置
+            <ArrowRight size={16} />
+          </a>
+        </div>
+        <ul className="garden-proof-list" aria-label="Garden 核心特点">
+          <li><strong>01</strong><span>Markdown 唯一真源</span></li>
+          <li><strong>02</strong><span>GitHub 自动发布</span></li>
+          <li><strong>03</strong><span>长文、随想与专栏</span></li>
+        </ul>
+      </PageIntro>
+
+      <section
+        className="garden-responsibilities"
+        id="responsibilities"
+        aria-labelledby="garden-responsibilities-title"
+      >
+        <header className="garden-section-heading">
+          <div>
+            <p className="eyebrow">FLOW / 职责划分</p>
+            <h2 id="garden-responsibilities-title">你只需要维护源码仓库</h2>
+          </div>
+          <p>
+            日常写作从源码仓库开始，也在源码仓库结束。框架提供能力，Actions 负责构建，Pages
+            只负责展示；管理后台和评论都是可选补充。
+          </p>
+        </header>
+
+        <div className="garden-responsibility-flow" aria-label="Garden 发布链路">
+          <strong>Garden 模板</strong>
+          <ArrowRight size={16} aria-hidden="true" />
+          <strong>你的源码仓库</strong>
+          <ArrowRight size={16} aria-hidden="true" />
+          <strong>GitHub Actions</strong>
+          <ArrowRight size={16} aria-hidden="true" />
+          <strong>公开博客</strong>
+        </div>
+
+        <div className="garden-responsibility-grid">
+          {responsibilityBoundaries.map((boundary) => (
+            <article key={boundary.number}>
+              <span>{boundary.number}</span>
+              <h3>{boundary.title}</h3>
+              <p>{boundary.description}</p>
+            </article>
+          ))}
+        </div>
+      </section>
+
+      <GardenContentGuide />
+
+      <GardenMediaGuide />
+
+      <section className="garden-system" aria-labelledby="garden-system-title">
+        <header>
+          <p className="eyebrow">SYSTEM / 系统能力</p>
+          <h2 id="garden-system-title">Markdown、搜索与自动发布</h2>
+          <p>
+            写作者只维护 Markdown、附件和专栏配置。页面生成、搜索索引和订阅文件由构建脚本统一处理。
+          </p>
+        </header>
+        <div className="garden-system-grid">
+          {systemCapabilities.map((capability, index) => (
+            <article key={capability.title}>
+              <span>{String(index + 1).padStart(2, "0")}</span>
+              <h3>{capability.title}</h3>
+              <p>{capability.description}</p>
+            </article>
+          ))}
+        </div>
+      </section>
+
+      <GardenAdminGuide />
+
+      <section className="garden-setup" id="setup" aria-labelledby="garden-setup-title">
+        <header className="garden-section-heading">
+          <div>
+            <p className="eyebrow">SETUP / 安装与配置</p>
+            <h2 id="garden-setup-title">从模板到公开博客</h2>
+          </div>
+          <p>
+            公开博客不需要数据库和服务器。创建仓库、替换配置与内容，再推送到 main，GitHub Actions 就会完成构建和发布。
+          </p>
+        </header>
+
+        <div className="garden-setup-grid">
+          <article>
+            <span>01</span>
+            <h3>创建自己的站点</h3>
+            <p>
+              运行 <code>npx hd-garden init my-blog</code>，站点里只保留
+              <code>content/</code> 和 <code>site.config.yaml</code>。也可以继续用 GitHub 的
+              <strong>Use this template</strong>。推荐将仓库命名为
+              <code> &lt;owner&gt;.github.io</code>。
+            </p>
+          </article>
+          <article>
+            <span>02</span>
+            <h3>在本地启动</h3>
+            <pre>
+              <code>make dev</code>
+            </pre>
+            <p>第一次运行会自动安装依赖并创建本地配置，随后启动预览。浏览器打开终端显示的地址即可。</p>
+          </article>
+          <article>
+            <span>03</span>
+            <h3>替换配置与内容</h3>
+            <dl>
+              <div>
+                <dt>site.config.yaml</dt>
+                <dd>站点名称、作者资料和各页面标题</dd>
+              </div>
+              <div>
+                <dt>content/posts/</dt>
+                <dd>长文章与附件</dd>
+              </div>
+              <div>
+                <dt>content/thoughts/</dt>
+                <dd>随想 Markdown</dd>
+              </div>
+              <div>
+                <dt>content/columns.yaml</dt>
+                <dd>专栏资料与文章顺序</dd>
+              </div>
+            </dl>
+          </article>
+          <article>
+            <span>04</span>
+            <h3>提交并发布</h3>
+            <pre>
+              <code>make update</code>
+            </pre>
+            <p>
+              命令会先完成检查，再提交并推送源码仓库。main 分支更新后，Actions 自动生成页面、搜索索引、RSS 和 sitemap。
+            </p>
+          </article>
+        </div>
+
+        <div className="garden-setup-notes">
+          <div>
+            <strong>两种部署方式</strong>
+            <p>
+              公开源码使用单仓即可；需要隐藏草稿时，把源码放进私有仓库，并配置 <code>PAGES_REPOSITORY</code>
+              指向公开产物仓库。两种方式都只运行 <code>make update</code>。
+            </p>
+          </div>
+          <div>
+            <strong>草稿预览</strong>
+            <p>
+              本地使用 <code>CONTENT_INCLUDE_DRAFTS=1 make dev</code>，即可预览草稿和未来定时文章。
+            </p>
+          </div>
+          <div>
+            <strong>可选服务</strong>
+            <p>评论、Webmention、统计和管理后台按需配置；任何密钥都只放在部署平台的 Secret 中。</p>
+          </div>
+        </div>
+
+        <div className="garden-setup-finish">
+          <div>
+            <p className="eyebrow">START / 开始使用</p>
+            <h3>先把公开博客跑起来，再决定是否接入后台。</h3>
+          </div>
+          <a
+            className="garden-primary-link"
+            href="https://github.com/hedon954/garden"
+            target="_blank"
+            rel="noreferrer"
+          >
+            <GithubLogo size={18} weight="fill" />
+            使用 Garden 模板
+            <ArrowUpRight size={16} />
+          </a>
+        </div>
+      </section>
+    </main>
+  );
+}