hd-garden 0.3.0

package/app/components/GardenAdminGuide.tsx

@@ -0,0 +1,116 @@
+const adminCapabilities = [
+  {
+    number: "01",
+    title: "发布和管理随想",
+    description:
+      "新建随想、保存草稿、正式发布、撤回或删除。每次修改都会写回 content/thoughts/，不会另存一份数据库副本。",
+  },
+  {
+    number: "02",
+    title: "上传多媒体",
+    description:
+      "图片、音频和视频可以直接上传到阿里云 OSS，随想中只保存公开地址，避免把大文件塞进 Git 历史。",
+  },
+  {
+    number: "03",
+    title: "管理博文置顶",
+    description:
+      "后台可以切换博文的首页置顶状态，并查看博文所属专栏。正文仍然使用 Markdown 编辑，专栏顺序仍由 columns.yaml 管理。",
+  },
+  {
+    number: "04",
+    title: "分发到其他平台",
+    description:
+      "可以直接发布到 X，或调用自建服务同步到 CSDN、知乎和掘金；没有配置接口时，也能复制标题、栏目和公开链接。",
+  },
+];
+
+const adminFlow = [
+  ["GitHub 登录", "只允许白名单中的账号进入后台。"],
+  ["执行内容操作", "发布随想、上传附件、置顶或分发博文。"],
+  ["提交到内容仓库", "后台使用服务端令牌修改 Markdown。"],
+  ["自动更新博客", "main 分支变更后由 Actions 重新发布。"],
+];
+
+export function GardenAdminGuide() {
+  return (
+    <section className="garden-admin" id="admin" aria-labelledby="garden-admin-title">
+      <header className="garden-section-heading">
+        <div>
+          <p className="eyebrow">ADMIN / 管理后台</p>
+          <h2 id="garden-admin-title">管理后台能做什么</h2>
+        </div>
+        <p>
+          后台是一个可选的独立服务，处理需要登录和服务端密钥的工作。公开博客仍然是静态站点，内容仍然保存在 Git 仓库中。
+        </p>
+      </header>
+
+      <figure className="garden-admin-preview">
+        {/* vinext 的本地静态导出不提供 Next 图片优化端点，截图直接由 public 目录提供。 */}
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img
+          src="/images/garden/admin-studio.png"
+          alt="Garden 内容管理后台，包含随想发布、草稿管理与博文分发"
+          width={1440}
+          height={1000}
+          loading="lazy"
+        />
+        <figcaption>
+          <strong>实际后台界面</strong>
+          <span>随想编辑、已发布与草稿管理，以及博文置顶和分发都集中在同一个工作区。</span>
+        </figcaption>
+      </figure>
+
+      <div className="garden-admin-capabilities">
+        {adminCapabilities.map((capability) => (
+          <article key={capability.number}>
+            <span>{capability.number}</span>
+            <h3>{capability.title}</h3>
+            <p>{capability.description}</p>
+          </article>
+        ))}
+      </div>
+
+      <div className="garden-admin-boundary">
+        <strong>后台的边界</strong>
+        <p>
+          它不是一套完整 CMS。长文章继续在 Typora 或其他 Markdown 编辑器中编写，专栏继续在
+          <code> content/columns.yaml </code>
+          中编排；后台主要补上随想发布、媒体上传、博文置顶和内容分发。
+        </p>
+      </div>
+
+      <ol className="garden-admin-flow" aria-label="管理后台发布流程">
+        {adminFlow.map(([title, description], index) => (
+          <li key={title}>
+            <span>{String(index + 1).padStart(2, "0")}</span>
+            <strong>{title}</strong>
+            <p>{description}</p>
+          </li>
+        ))}
+      </ol>
+
+      <div className="garden-admin-enable">
+        <div>
+          <p className="eyebrow">ENABLE / 启用后台</p>
+          <h3>单独部署，再连接内容仓库</h3>
+          <ol>
+            <li>把同一份 Garden 部署到 Node、Docker 或 Cloudflare Workers。</li>
+            <li>配置 GitHub OAuth、允许登录的账号，以及仅能写入内容仓库的令牌。</li>
+            <li>需要上传附件或跨平台分发时，再配置 OSS 和各平台接口。</li>
+          </ol>
+        </div>
+        <pre aria-label="管理后台核心配置示例">
+          <code>{`ADMIN_URL=https://admin.example.com
+CONTENT_REPOSITORY=owner/repository
+CONTENT_BRANCH=main
+ADMIN_GITHUB_LOGINS=your-github-login
+
+# 令牌与密钥只保存在后台服务中
+CONTENT_GITHUB_TOKEN=github_pat_xxx
+GITHUB_OAUTH_CLIENT_ID=Ov23li_xxx`}</code>
+        </pre>
+      </div>
+    </section>
+  );
+}

package/app/components/GardenContentGuide.tsx

@@ -0,0 +1,241 @@
+import type { ReactNode } from "react";
+
+type SourcePanelProps = {
+  path: string;
+  source: string;
+  language: string;
+};
+
+function SourcePanel({ path, source, language }: SourcePanelProps) {
+  return (
+    <div className="garden-source-panel">
+      <div className="garden-source-bar">
+        <span aria-hidden="true">
+          <i />
+          <i />
+          <i />
+        </span>
+        <code>{path}</code>
+      </div>
+      <pre>
+        <code className={`language-${language}`}>{source}</code>
+      </pre>
+    </div>
+  );
+}
+
+const postSource = `---
+title: 我的第一篇文章
+slug: first-post
+date: 2026-08-03T09:00:00+08:00
+description: 这篇文章记录我为什么重新开始写博客。
+topic: 写作
+tags: [Markdown, 博客]
+pinned: false
+cover: ./assets/cover.jpg
+---
+
+正文从这里开始。
+
+## 一个小标题
+
+可以继续插入图片、代码、公式和 Mermaid 图表。`;
+
+const thoughtSource = `---
+title: 雨后的散步
+slug: walk-after-rain
+date: 2026-08-03T18:30:00+08:00
+tags: [生活]
+media:
+  - type: image
+    src: ./assets/street.jpg
+    alt: 雨后的街道
+  - type: audio
+    src: ./assets/rain.mp3
+    title: 雨声
+---
+
+今天下班后多走了两公里。`;
+
+const columnSource = `columns:
+  - slug: writing-system
+    title: 写作系统
+    description: 记录从选题到发布的完整写作过程。
+    status: 持续更新
+    cover: /images/columns/writing-system.webp
+    coverAlt: 桌面上的笔记本与钢笔
+    posts:
+      - writing/why-write
+      - writing/collect-material
+      - writing/revise-and-publish`;
+
+type Guide = {
+  id: string;
+  number: string;
+  label: string;
+  title: string;
+  introduction: string;
+  steps: ReactNode[];
+  features: string[];
+  result: string;
+  path: string;
+  source: string;
+  language: string;
+};
+
+const guides: Guide[] = [
+  {
+    id: "write-post",
+    number: "01",
+    label: "博文",
+    title: "写一篇文章",
+    introduction:
+      "博文保存在 content/posts/ 中，可以按照主题建立任意层级的子目录。文件路径同时决定文章地址，正文仍然是普通 Markdown。",
+    steps: [
+      <>
+        在 <code>content/posts/</code> 中创建一个 <code>.md</code> 文件。
+      </>,
+      <>在 Front Matter 中填写标题、日期、摘要、主题、标签和封面。</>,
+      <>使用 Markdown 编写正文，图片和其他附件可以使用相对路径。</>,
+    ],
+    features: [
+      "GFM 表格、任务列表与脚注",
+      "TypeScript、Go、Rust 等代码高亮",
+      "数学公式与 Mermaid 图表",
+      "图片、音视频与平台嵌入",
+      "草稿、定时发布与置顶",
+      "文章目录、上一篇与下一篇",
+    ],
+    result:
+      "构建时会生成文章页面，并把标题、摘要和正文加入博文列表、主题归档、全文搜索与 RSS。",
+    path: "content/posts/writing/first-post.md",
+    source: postSource,
+    language: "markdown",
+  },
+  {
+    id: "write-thought",
+    number: "02",
+    label: "随想",
+    title: "发布一条随想",
+    introduction:
+      "随想适合记录几句话、一个链接或一组多媒体。它同样保存在 Git 仓库中，只需要更少的字段，也可以通过可选管理后台发布。",
+    steps: [
+      <>
+        直接创建 <code>content/thoughts/&lt;slug&gt;.md</code>，或者在管理后台填写内容。
+      </>,
+      <>填写标题、唯一 slug 和日期；需要暂存时加入草稿状态。</>,
+      <>
+        在 <code>media</code> 中按顺序添加图片、音频、视频或外部链接。
+      </>,
+    ],
+    features: [
+      "纯文字短内容",
+      "多张图片与混合图集",
+      "音频和视频",
+      "带标题的外部链接",
+      "草稿与公开状态",
+      "独立永久链接",
+    ],
+    result:
+      "发布后的内容会出现在随想时间线和首页最近随想中，每条随想都有可以单独分享的永久链接。",
+    path: "content/thoughts/walk-after-rain.md",
+    source: thoughtSource,
+    language: "markdown",
+  },
+  {
+    id: "make-column",
+    number: "03",
+    label: "专栏",
+    title: "创建一个专栏",
+    introduction:
+      "专栏不复制文章，而是在 content/columns.yaml 中引用已经存在的博文。posts 的排列顺序就是专栏的阅读顺序。",
+    steps: [
+      <>
+        在 <code>content/columns.yaml</code> 中添加专栏名称、介绍、状态和封面。
+      </>,
+      <>
+        在 <code>posts</code> 中填写博文相对 <code>content/posts/</code> 的路径。
+      </>,
+      <>按照希望读者阅读的顺序排列路径；同一篇文章可以加入多个专栏。</>,
+    ],
+    features: [
+      "专栏标题、说明和状态",
+      "独立专栏封面",
+      "文章顺序可控",
+      "复用同一份 Markdown",
+      "一篇文章加入多个专栏",
+      "系列文章导航",
+    ],
+    result:
+      "构建后会生成独立专栏页面。读者可以按照配置顺序浏览文章，文章页也会显示它所属的系列与前后篇目。",
+    path: "content/columns.yaml",
+    source: columnSource,
+    language: "yaml",
+  },
+];
+
+export function GardenContentGuide() {
+  return (
+    <section className="garden-guide" aria-labelledby="garden-guide-title">
+      <header className="garden-guide-heading">
+        <div>
+          <p className="eyebrow">CONTENT / 内容</p>
+          <h2 id="garden-guide-title">博文、随想和专栏</h2>
+        </div>
+        <p>
+          先选择内容类型，再编辑对应文件。三种内容都保存在源码仓库中，直接编辑文件即可完成全部公开内容的维护和发布。
+        </p>
+      </header>
+
+      <nav className="garden-guide-index" aria-label="内容类型">
+        {guides.map((guide) => (
+          <a href={`#${guide.id}`} key={guide.id}>
+            <span>{guide.number}</span>
+            <strong>{guide.title}</strong>
+            <small>{guide.label}</small>
+          </a>
+        ))}
+      </nav>
+
+      <div className="garden-guide-sections">
+        {guides.map((guide) => (
+          <article className="garden-content-guide" id={guide.id} key={guide.id}>
+            <div className="garden-content-copy">
+              <p className="eyebrow">
+                {guide.number} / {guide.label}
+              </p>
+              <h2>{guide.title}</h2>
+              <p className="garden-content-introduction">{guide.introduction}</p>
+
+              <ol className="garden-content-steps">
+                {guide.steps.map((step, index) => (
+                  <li key={index}>
+                    <strong>{index + 1}</strong>
+                    <span>{step}</span>
+                  </li>
+                ))}
+              </ol>
+
+              <ul className="garden-content-features" aria-label={`${guide.title}支持的能力`}>
+                {guide.features.map((feature) => (
+                  <li key={feature}>{feature}</li>
+                ))}
+              </ul>
+
+              <aside className="garden-content-result">
+                <strong>发布后</strong>
+                <p>{guide.result}</p>
+              </aside>
+            </div>
+
+            <SourcePanel
+              path={guide.path}
+              source={guide.source}
+              language={guide.language}
+            />
+          </article>
+        ))}
+      </div>
+    </section>
+  );
+}

package/app/components/GardenMediaGuide.tsx

@@ -0,0 +1,81 @@
+import {
+  Globe,
+  VideoCamera,
+  WechatLogo,
+  XLogo,
+} from "@phosphor-icons/react/ssr";
+
+const embedTypes = [
+  {
+    title: "YouTube / Bilibili",
+    description: "识别普通分享链接，自动转换成响应式播放器，并保留原站入口。",
+    Icon: VideoCamera,
+  },
+  {
+    title: "X / Twitter",
+    description: "以带平台标识的摘要卡片展示，避免依赖容易失效的第三方脚本。",
+    Icon: XLogo,
+  },
+  {
+    title: "微信公众号",
+    description: "保留标题、摘要和原文链接；微信禁止稳定 iframe 时仍有完整降级体验。",
+    Icon: WechatLogo,
+  },
+  {
+    title: "其他网站",
+    description: "手动提供标题、摘要与封面，生成不依赖远端抓取的网页预览卡片。",
+    Icon: Globe,
+  },
+];
+
+const embedSource = `\`\`\`embed
+url: https://www.youtube.com/watch?v=VIDEO_ID
+title: 这段视频讲了什么
+description: 给读者一个值得点开的理由。
+image: https://example.com/cover.jpg
+\`\`\``;
+
+export function GardenMediaGuide() {
+  return (
+    <section className="garden-media" id="media" aria-labelledby="garden-media-title">
+      <header>
+        <p className="eyebrow">EMBEDS / 高级嵌入</p>
+        <h2 id="garden-media-title">文章不只能放文字。</h2>
+        <p>
+          本地图片、音频和视频继续使用标准 Markdown / HTML；外部平台统一使用
+          <code> embed </code>代码块。可播放的平台直接播放，受平台限制的内容自动退化为摘要卡片。
+        </p>
+      </header>
+
+      <div className="garden-media-layout">
+        <ul className="garden-media-providers">
+          {embedTypes.map(({ title, description, Icon }, index) => (
+            <li key={title}>
+              <span>{String(index + 1).padStart(2, "0")}</span>
+              <Icon size={22} aria-hidden="true" />
+              <div>
+                <strong>{title}</strong>
+                <p>{description}</p>
+              </div>
+            </li>
+          ))}
+        </ul>
+
+        <div className="garden-media-source">
+          <div>
+            <span>content/posts/example.md</span>
+            <small>Markdown</small>
+          </div>
+          <pre><code>{embedSource}</code></pre>
+        </div>
+      </div>
+
+      <aside className="garden-media-boundary">
+        <strong>为什么不自动抓网页摘要？</strong>
+        <p>
+          构建阶段主动抓取任意 URL 会带来 SSRF、超时和内容漂移风险。Garden 选择把摘要写进 Markdown：发布结果可预测，原站失效时文章也仍然可读。写稿时可用 <code>make embed URL=...</code> 拉一次 Open Graph，检查后再贴进围栏。
+        </p>
+      </aside>
+    </section>
+  );
+}

package/app/components/GiscusComments.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+export type GiscusConfig = {
+  repo: string;
+  repoId: string;
+  category: string;
+  categoryId: string;
+};
+
+function currentGiscusTheme() {
+  return document.documentElement.dataset.theme === "dark" ? "dark" : "light";
+}
+
+export function GiscusComments({
+  slug,
+  config,
+}: {
+  slug: string;
+  config: GiscusConfig;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+    const container = containerRef.current;
+    container.replaceChildren();
+
+    const script = document.createElement("script");
+    script.src = "https://giscus.app/client.js";
+    script.async = true;
+    script.crossOrigin = "anonymous";
+    script.dataset.repo = config.repo;
+    script.dataset.repoId = config.repoId;
+    script.dataset.category = config.category;
+    script.dataset.categoryId = config.categoryId;
+    script.dataset.mapping = "pathname";
+    script.dataset.strict = "1";
+    script.dataset.reactionsEnabled = "1";
+    script.dataset.emitMetadata = "0";
+    script.dataset.inputPosition = "bottom";
+    script.dataset.theme = currentGiscusTheme();
+    script.dataset.lang = "zh-CN";
+    script.dataset.loading = "lazy";
+    container.append(script);
+
+    const observer = new MutationObserver(() => {
+      const frame = container.querySelector<HTMLIFrameElement>(".giscus-frame");
+      frame?.contentWindow?.postMessage(
+        {
+          giscus: {
+            setConfig: { theme: currentGiscusTheme() },
+          },
+        },
+        "https://giscus.app",
+      );
+    });
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-theme"],
+    });
+
+    return () => {
+      observer.disconnect();
+      container.replaceChildren();
+    };
+  }, [config, slug]);
+
+  return <div className="giscus-container" ref={containerRef} />;
+}

package/app/components/GithubLiveOverview.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import {
+  ArrowUpRight,
+  GitCommit,
+  GithubLogo,
+  MapPin,
+  Users,
+} from "@phosphor-icons/react";
+
+export type GithubPublicProfile = {
+  avatar_url: string;
+  name: string | null;
+  login: string;
+  bio: string | null;
+  public_repos: number;
+  followers: number;
+  html_url: string;
+  location: string | null;
+};
+
+function visibleGithubText(value: string) {
+  return Array.from(value)
+    .filter((character) => (character.codePointAt(0) ?? 0) >= 32)
+    .join("")
+    .trim();
+}
+
+export function GithubLiveOverview({
+  username,
+  initialProfile,
+  initialLive,
+  statusMessage,
+  recentCommits,
+}: {
+  username: string;
+  initialProfile: GithubPublicProfile;
+  initialLive: boolean;
+  statusMessage?: string;
+  recentCommits?: number;
+}) {
+  const [profile, setProfile] = useState(initialProfile);
+  const [syncState, setSyncState] = useState<"syncing" | "synced" | "snapshot">("syncing");
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    fetch(`https://api.github.com/users/${encodeURIComponent(username)}`, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+      cache: "no-store",
+      signal: controller.signal,
+    })
+      .then((response) => {
+        if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
+        return response.json() as Promise<GithubPublicProfile>;
+      })
+      .then((nextProfile) => {
+        setProfile(nextProfile);
+        setSyncState("synced");
+      })
+      .catch((error: unknown) => {
+        if (error instanceof DOMException && error.name === "AbortError") return;
+        setSyncState("snapshot");
+      });
+
+    return () => controller.abort();
+  }, [username]);
+
+  const displayName = visibleGithubText(profile.name ?? profile.login) || profile.login;
+  const profileBio = profile.bio?.trim();
+  const signature = statusMessage?.trim() || profileBio;
+  const syncLabel = syncState === "synced"
+    ? "本次访问已同步"
+    : syncState === "snapshot"
+      ? "暂用发布时快照"
+      : "正在同步当前资料";
+
+  return (
+    <>
+      <header className="github-overview">
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img src={profile.avatar_url} alt={`${profile.login} 的 GitHub 头像`} />
+        <div className="github-identity">
+          <span className="eyebrow" aria-live="polite"><GithubLogo size={17} /> GitHub 公开资料 · {syncLabel}</span>
+          <h2>{displayName}</h2>
+          {signature && <p>{signature}</p>}
+          {profile.location && <span className="github-location"><MapPin size={14} />{profile.location}</span>}
+        </div>
+        <a href={profile.html_url} target="_blank" rel="noopener noreferrer">
+          查看 GitHub
+          <ArrowUpRight size={16} />
+        </a>
+      </header>
+
+      <dl className="github-metrics">
+        <div>
+          <GithubLogo size={21} aria-hidden="true" />
+          <dt>公开仓库</dt>
+          <dd>{syncState === "synced" || initialLive ? profile.public_repos : "—"}</dd>
+        </div>
+        <div>
+          <Users size={21} aria-hidden="true" />
+          <dt>Followers</dt>
+          <dd>{syncState === "synced" || initialLive ? profile.followers : "—"}</dd>
+        </div>
+        <div>
+          <GitCommit size={21} aria-hidden="true" />
+          <dt>近 30 天 commits</dt>
+          <dd>{recentCommits ?? "—"}</dd>
+        </div>
+      </dl>
+    </>
+  );
+}