hd-garden 0.14.12 → 0.14.13

package/Makefile

@@ -13,7 +13,7 @@ export GARDEN_EMBED_URL := $(value URL)
 export GARDEN_CHECK_FILE := $(value FILE)
 
 help:
-	@printf "%s\n" "Garden 常用命令：" "  make new                 创建文章草稿（无需安装 npm 依赖）" '  make new TITLE="文章标题" SLUG=my-post DIR=writing' '  make embed URL="https://example.com"  拉取外部网页摘要，打印可粘贴的 embed 围栏' "  make skill               安装可交互图表 skill" "  make dev                 首次准备并本地预览" "  make check               全量严格预检后 lint/测试；FILE=路径 只限制预检" "  make check diff          只检查 Git 改动的 Markdown，不构建/跑全套测试" "  make build               构建公开站点" "  make update              检查、提交并触发自动发布" "  make update MESSAGE=\"新增一篇文章\"  自定义提交说明"
+	@printf "%s\n" "Garden 常用命令：" "  make new                 创建文章草稿（无需安装 npm 依赖）" '  make new TITLE="文章标题" SLUG=my-post DIR=writing' '  make embed URL="https://www.youtube.com/watch?v=..."  打印可粘贴的规范化视频链接或网页地址' "  make skill               安装可交互图表 skill" "  make dev                 首次准备并本地预览" "  make check               全量严格预检后 lint/测试；FILE=路径 只限制预检" "  make check diff          只检查 Git 改动的 Markdown，不构建/跑全套测试" "  make build               构建公开站点" "  make update              检查、提交并触发自动发布" "  make update MESSAGE=\"新增一篇文章\"  自定义提交说明"
 
 new:
 	@node scripts/new-post.mjs

package/app/api/admin/distribution/route.ts

@@ -1,5 +1,6 @@
 import { requireAdminApi, requireAdminMutation } from "../../../lib/admin-auth";
 import { findColumnEntry, findPost } from "../../../lib/content";
+import { postWithBody } from "../../../lib/content-body";
 import { absoluteUrl, getSiteUrl } from "../../../lib/site";
 import { contentForDistribution } from "../../../../ui/core/transform.mjs";
 
@@ -42,8 +43,9 @@ export async function POST(request: Request) {
   const entry = kind === "post" ? findPost(path) : undefined;
   const column = typeof payload.column === "string" ? payload.column : "";
   const columnEntry = kind === "column" ? findColumnEntry(column, path) : undefined;
-  const source = entry ?? columnEntry;
-  if (!source) return Response.json({ error: "未找到对应内容。" }, { status: 404 });
+  const found = entry ?? columnEntry;
+  if (!found) return Response.json({ error: "未找到对应内容。" }, { status: 404 });
+  const source = postWithBody(found);
 
   const publicPath = kind === "post" ? `/blog/${source.path}` : `/columns/${source.column}/${source.path}`;
   const siteUrl = await getSiteUrl();

package/app/blog/[...path]/page.tsx

@@ -6,6 +6,7 @@ import {
   postHref,
   posts,
 } from "../../lib/content";
+import { postWithBody } from "../../lib/content-body";
 import { PostReadingView } from "../../components/PostReadingView";
 import { adjacentByDate } from "../../../ui/garden/adjacent.mjs";
 import {
@@ -59,11 +60,12 @@ export default async function PostPage({
   params: Promise<{ path: string[] }>;
 }) {
   const { path } = await params;
-  const post = findPost(path.join("/"));
-  if (!post) {
+  const found = findPost(path.join("/"));
+  if (!found) {
     if (isStaticPlaceholder(path)) return null;
     notFound();
   }
+  const post = postWithBody(found);
   const baseUrl = await getSiteUrl();
   const pathname = postHref(post);
   const canonicalUrl = absoluteUrl(pathname, baseUrl);

package/app/columns/[column]/[...path]/page.tsx

@@ -7,6 +7,7 @@ import {
   columnHref,
   columnEntryPath,
 } from "../../../lib/content";
+import { postWithBody } from "../../../lib/content-body";
 import { PostReadingView } from "../../../components/PostReadingView";
 import {
   absoluteUrl,
@@ -69,11 +70,12 @@ export default async function ColumnEntryPage({
   params: Promise<{ column: string; path: string[] }>;
 }) {
   const { column, path } = await params;
-  const entry = findColumnEntry(column, path.join("/"));
-  if (!entry) {
+  const found = findColumnEntry(column, path.join("/"));
+  if (!found) {
     if (isStaticPlaceholder(column)) return null;
     notFound();
   }
+  const entry = postWithBody(found);
   const series = columns.filter((item) => item.column === column);
   const listed = [...series].sort((left, right) => Date.parse(right.date) - Date.parse(left.date));
   const currentIndex = series.findIndex((item) => item.path === entry.path);

package/app/components/GardenMediaGuide.tsx

@@ -1,28 +1,17 @@
-const embedTypes = [
+const mediaTypes = [
   {
     title: "YouTube / Bilibili",
-    description: "贴上分享链接，页面里就能播放，也能回到原站。",
-  },
-  {
-    title: "X / Twitter",
-    description: "显示成一张带出处的卡片。",
-  },
-  {
-    title: "微信公众号",
-    description: "留下标题、摘要和原文链接。微信不允许嵌进页面时，卡片仍然能点开。",
+    description: "把可播放的视频链接单独占一行，页面里就能播放，也能回到原站。",
   },
   {
     title: "其他网站",
-    description: "自己写标题、摘要和封面。",
+    description: "单独一行的网址显示为链接卡片；句子里的链接在后面紧跟 {card} 才会变成卡片。",
   },
 ];
 
-const embedSource = `\`\`\`embed
-url: https://www.youtube.com/watch?v=VIDEO_ID
-title: 这段视频讲了什么
-description: 给读者一个值得点开的理由。
-image: https://example.com/cover.jpg
-\`\`\``;
+const mediaSource = `https://www.youtube.com/watch?v=VIDEO_ID
+
+https://www.bilibili.com/video/BV1xx411c7mD`;
 
 export function GardenMediaGuide() {
   return (
@@ -30,9 +19,8 @@ export function GardenMediaGuide() {
       <header>
         <h2 id="garden-media-title">视频和链接</h2>
         <p>
-          自己的图片、音频和视频用 Markdown。别人的页面用
-          <code> embed </code>
-          围栏。能播的直接播，不能播的显示成一张卡片。
+          自己的图片、音频和视频用 Markdown 或 <code>audio</code> / <code>video</code> 标签。
+          YouTube / Bilibili 只要把链接单独一行。其他网站用链接卡片，不要写任意 iframe。
         </p>
       </header>
 
@@ -40,11 +28,11 @@ export function GardenMediaGuide() {
         <div>
           <span>content/posts/example.md</span>
         </div>
-        <pre><code>{embedSource}</code></pre>
+        <pre><code>{mediaSource}</code></pre>
       </div>
 
       <ul className="garden-media-providers">
-        {embedTypes.map(({ title, description }) => (
+        {mediaTypes.map(({ title, description }) => (
           <li key={title}>
             <strong>{title}</strong>
             <p>{description}</p>
@@ -53,7 +41,7 @@ export function GardenMediaGuide() {
       </ul>
 
       <p className="garden-media-boundary">
-        摘要写在文章里。原站打不开，文章还在。需要时用 <code>make embed URL=...</code> 拉一次，看过再贴进去。
+        需要规范化短链或核对标题时，用 <code>npx garden embed URL</code> 打印一行可粘贴的地址，看过再贴进文章。
       </p>
     </section>
   );

package/app/components/GardenPlayer.tsx

@@ -0,0 +1,25 @@
+import { resolvePlayer } from "../../ui/garden/player.mjs";
+
+export function GardenPlayer({ href, title }: { href: string; title?: string }) {
+  const player = resolvePlayer(href);
+  if (!player.ok) return null;
+  const open = player.provider === "youtube" ? "在 YouTube 打开" : "在 Bilibili 打开";
+  const frameTitle = title?.trim() || `${player.label} video`;
+  return (
+    <figure className={`g-player g-player-${player.provider}`}>
+      <div className="g-player-frame">
+        <iframe
+          src={player.playerUrl}
+          title={frameTitle}
+          loading="lazy"
+          allow="fullscreen; picture-in-picture; encrypted-media"
+          referrerPolicy="strict-origin-when-cross-origin"
+          allowFullScreen
+        />
+      </div>
+      <figcaption>
+        <a className="ext" href={player.pageUrl} target="_blank" rel="noopener noreferrer">{open}</a>
+      </figcaption>
+    </figure>
+  );
+}

package/app/components/HandbookView.tsx

@@ -9,6 +9,7 @@ import { HandbookLangRedirect } from "./HandbookLangRedirect";
 import { MarkdownArticle } from "./MarkdownArticle";
 import { TableOfContents } from "./TableOfContents";
 import { extractHeadings, handbookDocs, handbookIndexDoc, hasHandbookPage, type GardenDocEntry } from "../lib/content";
+import { docWithBody } from "../lib/content-body";
 import { pageAlternates } from "../lib/page-alternates";
 import { absoluteUrl, getSiteUrl } from "../lib/site";
 import { siteHref } from "../lib/site-href";
@@ -143,7 +144,7 @@ export async function handbookDocMetadata(lang: HandbookLang, doc: GardenDocEntr
 export function HandbookOverview({ lang }: { lang: HandbookLang }) {
   const t = HANDBOOK_UI[lang];
   const docs = handbookDocs(lang);
-  const indexDoc = handbookIndexDoc(lang);
+  const indexDoc = docWithBody(handbookIndexDoc(lang), lang);
   const navItems = toHandbookNavItems(docs);
   const firstDoc = orderedHandbookDocs(docs)[0] ?? null;
   const content = indexDoc?.content ?? "";
@@ -197,13 +198,14 @@ export function HandbookOverview({ lang }: { lang: HandbookLang }) {
 
 export function HandbookDoc({ lang, doc }: { lang: HandbookLang; doc: GardenDocEntry }) {
   const t = HANDBOOK_UI[lang];
+  const resolved = docWithBody(doc, lang);
   const docs = handbookDocs(lang);
   const ordered = orderedHandbookDocs(docs);
   const navItems = toHandbookNavItems(docs);
   const index = ordered.findIndex((item) => item.path === doc.path);
   const prev = index > 0 ? ordered[index - 1] : null;
   const next = index >= 0 && index < ordered.length - 1 ? ordered[index + 1] : null;
-  const headings = extractHeadings(doc.content);
+  const headings = extractHeadings(resolved.content);
   const sectionMeta = HANDBOOK_SECTIONS.find((sec) => sec.id === doc.section);
   const componentBadge = COMPONENT_BADGE[doc.path];
 
@@ -229,7 +231,7 @@ export function HandbookDoc({ lang, doc }: { lang: HandbookLang; doc: GardenDocE
         <ArticleMeasure />
 
         <div className="e-content">
-          <MarkdownArticle content={doc.content} lang={lang} fieldTables handbook refDemos={isReferencePath(doc.path)} />
+          <MarkdownArticle content={resolved.content} lang={lang} fieldTables handbook refDemos={isReferencePath(doc.path)} />
         </div>
 
         <ArticleReferences references={doc.references} lang={lang} />

package/app/components/MarkdownArticle.tsx

@@ -38,6 +38,8 @@ import { LinkCardRefresh } from "./LinkCardRefresh";
 import { linkHost } from "../../scripts/link-meta-core.mjs";
 import { FaviconProvider, SourceMark } from "./garden/patterns";
 import { rehypeFieldTables } from "../lib/rehype-field-tables.mjs";
+import { GardenPlayer } from "./GardenPlayer";
+import { resolvePlayer } from "../../ui/garden/player.mjs";
 import { cardDate } from "../../ui/garden/card-refresh.mjs";
 import { siteHref } from "../lib/site-href";
 import { codeLanguageLabel, fenceLanguage } from "../../ui/garden/code-language.mjs";
@@ -271,8 +273,11 @@ export function MarkdownArticle({ content, lang, fieldTables, refDemos, handbook
             const only = nodes.length === 1 && isValidElement<{ href?: string; children?: ReactNode }>(nodes[0]) ? nodes[0] : null;
             const href = only?.props.href;
             const text = only ? headingText(only.props.children).trim() : "";
-            // Bare http(s) URL alone in a paragraph → link card (same path for every jump link).
-            if (href && text === href && /^https?:\/\//iu.test(href)) return <LinkCard href={href} />;
+            // Bare http(s) URL alone in a paragraph → player for YouTube / Bilibili, otherwise a link card.
+            if (href && text === href && /^https?:\/\//iu.test(href)) {
+              if (resolvePlayer(href).ok) return <GardenPlayer href={href} />;
+              return <LinkCard href={href} />;
+            }
             return <p {...domProps}>{children}</p>;
           },
           a: ({ href: written, children, ...props }) => {

package/app/components/PostReadingView.tsx

@@ -53,8 +53,8 @@ export function PostReadingView({
 }) {
   const displayTitle = title ?? post.title;
   const numbering = (post as ContentEntry & { numbering?: boolean }).numbering;
-  const headings = extractHeadings(post.content, { numbering });
-  const wordCount = estimateWordCount(post.content);
+  const headings = extractHeadings(post.content ?? "", { numbering });
+  const wordCount = estimateWordCount(post.content ?? "");
   const t = ui();
 
   return (
@@ -116,7 +116,7 @@ export function PostReadingView({
             <ArticleMeasure />
             <div className="e-content">
               {post.description ? <p className="lead quote-plain p-summary">{post.description}</p> : null}
-              <MarkdownArticle content={post.content} numbering={numbering} />
+              <MarkdownArticle content={post.content ?? ""} numbering={numbering} />
             </div>
             <ArticleReferences references={post.references} />
             <Webmentions target={canonicalUrl} endpoint={webmentionApiEndpoint()} />

package/app/garden-modules.d.ts

@@ -14,7 +14,7 @@ declare module "@garden/generated-content" {
     readingTime?: string;
     kind: "post" | "column";
     sourcePath: string;
-    content: string;
+    content?: string;
     column?: string;
     columnTitle?: string;
     columnDescription?: string;
@@ -42,7 +42,7 @@ declare module "@garden/generated-content" {
     readingTime?: string;
     references?: { title: string; url?: string; domain?: string }[];
     sourcePath: string;
-    content: string;
+    content?: string;
     lang?: "zh" | "en";
   };
   export const gardenDocs: GardenDocEntry[];
@@ -64,6 +64,14 @@ declare module "@garden/generated-content" {
   export const imageSizes: Record<string, { width: number; height: number }>;
 }
 
+declare module "@garden/generated-post-bodies" {
+  export const postBodies: Record<string, string>;
+}
+
+declare module "@garden/generated-handbook-bodies" {
+  export const handbookBodies: Record<string, string>;
+}
+
 declare module "@garden/site-config" {
   export const searchIndexUrl: string;
   /** The full-text index file and the hash its contents are cached under. */

package/app/globals.css

@@ -2141,7 +2141,8 @@ button {
   -webkit-line-clamp: 2;
 }
 
-.external-embed-error {
+.external-embed-error,
+.g-player-error {
   margin: 32px 0;
   padding: 18px;
   border-left: 3px solid var(--accent);
@@ -2150,6 +2151,62 @@ button {
   font-size: 12px;
 }
 
+.markdown-body .g-player,
+.markdown-body .g-player-fallback {
+  width: 100%;
+  max-width: 100%;
+  margin: 36px 0;
+  background: transparent;
+  border: 0;
+  box-shadow: none;
+}
+
+/* The video uses the article radius token --r (12px). Standalone body
+   images have no border-radius; covers use --r-lg; figure-card photos
+   use 8px inside a padded card shell we are not copying. */
+.g-player-frame {
+  width: 100%;
+  max-width: 100%;
+  aspect-ratio: 16 / 9;
+  border-radius: var(--r);
+  overflow: hidden;
+  background: #111;
+}
+
+@supports (overflow-clip-margin: 4px) {
+  .g-player-frame {
+    overflow: clip;
+    overflow-clip-margin: 4px;
+  }
+}
+
+.g-player-frame:focus-within {
+  outline: 2px solid var(--blue);
+  outline-offset: 2px;
+}
+
+.g-player-frame iframe {
+  width: 100%;
+  max-width: 100%;
+  height: 100%;
+  display: block;
+  border: 0;
+  border-radius: inherit;
+}
+
+/* Same typography as .markdown-body .fig figcaption: a quiet line, not a bar. */
+.markdown-body .g-player figcaption {
+  margin-top: 12px;
+  font-size: var(--fs-small);
+  line-height: 1.6;
+  color: var(--muted);
+  text-align: center;
+}
+
+.markdown-body .g-player figcaption a {
+  color: var(--muted);
+}
+
 .markdown-body .garden-chart {
   margin: 36px 0;
   border: 1px solid var(--line-strong);

package/app/lib/content-body.ts

@@ -0,0 +1,20 @@
+import { handbookBodies } from "@garden/generated-handbook-bodies";
+import { postBodies } from "@garden/generated-post-bodies";
+import type { ContentEntry, GardenDocEntry } from "./content";
+
+export function postWithBody<T extends Pick<ContentEntry, "path">>(entry: T): T & { content: string } {
+  return { ...entry, content: postBodies[entry.path] ?? "" };
+}
+
+export function docWithBody<T extends Pick<GardenDocEntry, "path">>(
+  doc: T,
+  lang: "zh" | "en",
+): T & { content: string };
+export function docWithBody(
+  doc: GardenDocEntry | null | undefined,
+  lang: "zh" | "en",
+): (GardenDocEntry & { content: string }) | null | undefined;
+export function docWithBody(doc: GardenDocEntry | null | undefined, lang: "zh" | "en") {
+  if (!doc) return doc;
+  return { ...doc, content: handbookBodies[`${lang}:${doc.path}`] ?? "" };
+}

package/app/lib/garden-docs-meta.ts

@@ -69,6 +69,7 @@ export const HANDBOOK_SECTIONS: HandbookSectionMeta[] = [
   { id: "getting-started", title: "快速上手", titleEn: "Getting Started" },
   { id: "writing-and-reading", title: "写作与排版", titleEn: "Writing & Layout" },
   { id: "components", title: "内置组件", titleEn: "Built-in Components" },
+  { id: "diagrams", title: "推荐图示", titleEn: "Recommended figures" },
   { id: "workflow", title: "检查与补全", titleEn: "Checks & Shortcuts" },
   { id: "reference", title: "组件参考", titleEn: "Component reference" },
 ];
@@ -129,6 +130,7 @@ export const NAV_SHORT_TITLE: Record<string, string> = {
   "components/link-card": "链接卡片",
   "components/source": "来源胶囊",
   "components/image": "本地图片",
+  "components/diagrams": "推荐图示",
   workflow: "语法检查与快捷输入",
   reference: "总览",
 };

package/app/lib/markdown-plugins.ts

@@ -1,6 +1,11 @@
 import type { PluggableList } from "unified";
 import { markdownSyntaxPlugins } from "../../ui/garden/markdown-syntax.mjs";
 import { remarkGarden } from "./remark-garden.mjs";
+import { remarkVideoPlayer } from "./remark-video-player.mjs";
 
 // Keep article rendering and heading extraction on the same Markdown syntax.
+// The spread + remarkGarden list already fails PluggableList checking on HEAD.
+// Adding another plugin in that literal would report a new slot error even when
+// the plugin itself is a Plugin; append it as a typed Pluggable instead.
 export const markdownPlugins: PluggableList = [...markdownSyntaxPlugins, remarkGarden];
+markdownPlugins.push(remarkVideoPlayer);

package/app/lib/remark-video-player.d.mts

@@ -0,0 +1,10 @@
+import type { Root } from "mdast";
+import type { Plugin } from "unified";
+
+/**
+ * Remark plugin: a paragraph that is only a YouTube or Bilibili video URL
+ * becomes an in-article player. This is the attacher itself (Plugin), not a
+ * factory that returns a Plugin.
+ */
+declare const remarkVideoPlayer: Plugin<[], Root>;
+export { remarkVideoPlayer };

package/app/lib/remark-video-player.mjs

@@ -0,0 +1,70 @@
+/**
+ * A paragraph whose only content is one YouTube / Bilibili video link becomes
+ * an in-article player. `{card}` keeps a link card. In-sentence links, lists
+ * of several links, and code stay unchanged. Historical ```embed fences with
+ * a playable URL still render, so older drafts are not left as dead code.
+ */
+import { toString } from "mdast-util-to-string";
+import { renderLegacyEmbed, renderPlayerHtml, resolvePlayer } from "../../ui/garden/player.mjs";
+
+const CARD_MARKER = "{card}";
+
+const meaningful = (children) =>
+  (children ?? []).filter((child) => !(child.type === "text" && !child.value.trim()) && child.type !== "break");
+
+function htmlNode(value) {
+  return { type: "html", value };
+}
+
+function asksForCard(node) {
+  const children = node.children ?? [];
+  for (let index = 0; index < children.length - 1; index += 1) {
+    const link = children[index];
+    const next = children[index + 1];
+    if (link.type === "link" && next.type === "text" && next.value.startsWith(CARD_MARKER)) return true;
+  }
+  return false;
+}
+
+function exclusiveLink(node) {
+  const rest = meaningful(node.children);
+  return rest.length === 1 && rest[0].type === "link" ? rest[0] : null;
+}
+
+function replaceParagraph(parent, index, node) {
+  if (asksForCard(node)) return false;
+  const link = exclusiveLink(node);
+  if (!link) return false;
+  const player = resolvePlayer(link.url);
+  if (!player.ok) return false;
+  const title = toString(link).trim();
+  parent.children[index] = htmlNode(renderPlayerHtml(player, {
+    title: title && title !== link.url ? title : undefined,
+  }));
+  return true;
+}
+
+function walk(parent) {
+  const children = parent.children ?? [];
+  for (let index = 0; index < children.length; index += 1) {
+    const node = children[index];
+    if (node.type === "inlineCode" || node.type === "html") continue;
+    if (node.type === "code") {
+      if (String(node.lang ?? "").toLowerCase() === "embed") {
+        children[index] = htmlNode(renderLegacyEmbed(node.value));
+      }
+      continue;
+    }
+    if (node.type === "paragraph") {
+      replaceParagraph(parent, index, node);
+      continue;
+    }
+    if (node.children) walk(node);
+  }
+}
+
+export function remarkVideoPlayer() {
+  return (tree) => {
+    walk(tree);
+  };
+}

package/app/rss.xml/route.ts

@@ -1,5 +1,6 @@
 import { marked } from "marked";
 import { columnHref, columns, postHref, posts } from "../lib/content";
+import { postWithBody } from "../lib/content-body";
 import { configuredSiteUrl, siteDescription, siteName } from "../lib/site";
 import { contentForFeed } from "../../ui/core/transform.mjs";
 import { withTrailingSlash } from "../../ui/garden/site-href.mjs";
@@ -20,9 +21,9 @@ const cdata = (value: string) => value.replaceAll("]]>", "]]]]><![CDATA[>");
 export async function GET() {
   const origin = configuredSiteUrl();
   const entries = [
-    ...posts.map((post) => ({ ...post, path: postHref(post) })),
+    ...posts.map((post) => ({ ...postWithBody(post), path: postHref(post) })),
     ...columns.map((entry) => ({
-      ...entry,
+      ...postWithBody(entry),
       path: columnHref(entry),
     })),
   ].sort((a, b) => Date.parse(b.date) - Date.parse(a.date));