Merge pull request #341 from InvolutionHell/feat/seo-meta-description

feat(seo): fix 118 short meta descriptions reported by Bing

Author: longsizhuo

.github/workflows/content-check.yml

@@ -76,3 +76,10 @@ jobs:
 
       - name: Lint image references (non-blocking)
         run: pnpm lint:images || echo "[warn] image lint found issues (non-blocking)"
+
+      # Block PR if newly added/modified MDX is missing a proper description.
+      # Old files are grandfathered via lib/seo-description.ts (Layer 1 fallback);
+      # this check only fires on changed files in the PR (uses GITHUB_BASE_REF diff).
+      # leetcode/ and _translated.md are exempt — see scripts/check-frontmatter-description.mjs
+      - name: Check MDX frontmatter description
+        run: pnpm check:frontmatter

.gitignore

@@ -62,3 +62,6 @@ AGENTS.md
 
 .npmrc
 /.env.*
+
+# scripts/generate-descriptions.mjs 的 dry-run / apply 报表（产物，不进 git）
+scripts/.descriptions-report.json

.husky/pre-commit

@@ -11,5 +11,11 @@ pnpm test || exit 1
 pnpm check:pnpm-version || true
 pnpm check:lockfile || true
 
-# 5) 其余按 lint-staged 处理（如 Prettier）
+# 5) 校验新增/修改的 docs MDX 必须有 description（>= 60 字符）
+#    Bing 2026-05 报告 118 个页面 description 太短，老内容由 lib/seo-description.ts
+#    代码层兜底，但新增/修改必须手写，避免再积累低质量 SEO 内容。
+#    leetcode/ 和 _translated 自动豁免，详见 scripts/check-frontmatter-description.mjs
+pnpm check:frontmatter || exit 1
+
+# 6) 其余按 lint-staged 处理（如 Prettier）
 pnpm exec lint-staged

app/[locale]/docs/[...slug]/page.tsx

@@ -1,6 +1,7 @@
 import { source } from "@/lib/source";
 import { safeJsonLdString } from "@/lib/json-ld";
 import { SITE_URL } from "@/lib/site-url";
+import { ensureSeoDescription } from "@/lib/seo-description";
 import { DocsPage, DocsBody } from "fumadocs-ui/page";
 import { notFound } from "next/navigation";
 import type { Metadata } from "next";
@@ -65,12 +66,23 @@ export default async function DocPage({ params }: Param) {
     ? `${SITE_URL}/${locale}/docs/${slugPath}`
     : `${SITE_URL}/${locale}/docs`;
 
+  // JSON-LD description 同步走兜底：避免结构化数据里出现空字符串，否则
+  // Google Rich Results 测试会 warning。与 generateMetadata 里的逻辑一致。
+  const sectionPathForJsonLd =
+    (slug ?? []).length > 1 ? (slug ?? []).slice(0, -1) : [];
+  const articleDescription = ensureSeoDescription({
+    description: page.data.description,
+    title: page.data.title,
+    sectionPath: sectionPathForJsonLd,
+    locale,
+  });
+
   // TechArticle: 让 docs 在 Google 搜索结果上更可能展示为技术文章卡片
   const articleJsonLd = {
     "@context": "https://schema.org",
     "@type": "TechArticle",
     headline: page.data.title,
-    description: page.data.description,
+    description: articleDescription,
     url: docUrl,
     inLanguage: locale === "en" ? "en-US" : "zh-CN",
     publisher: {
@@ -190,21 +202,35 @@ export async function generateMetadata({ params }: Param): Promise<Metadata> {
     "",
   );
 
+  // SEO description 兜底：page.data.description 可能为 undefined/空/极短
+  // （96 个 leetcode 题解完全没 description，67 个空，35 个 < 20 字符）。
+  // 用 ensureSeoDescription 拼 title + 面包屑 + 站点 tagline 补到 80+ 字符，
+  // 让 Bing/Google 拿到完整摘要而不是从正文随便抓一段。
+  // sectionPath 取 slug 除末段外的所有段（末段是当前页本身，已在 title 里）。
+  const slugArr = slug ?? [];
+  const sectionPath = slugArr.length > 1 ? slugArr.slice(0, -1) : [];
+  const safeDescription = ensureSeoDescription({
+    description: page.data.description,
+    title: page.data.title,
+    sectionPath,
+    locale,
+  });
+
   return {
     title: page.data.title,
-    description: page.data.description,
+    description: safeDescription,
     alternates: { canonical, languages: langs },
     openGraph: {
       type: "article",
       title: page.data.title,
-      description: page.data.description,
+      description: safeDescription,
       url: canonical,
       locale: locale === "en" ? "en_US" : "zh_CN",
     },
     twitter: {
       card: "summary_large_image",
       title: page.data.title,
-      description: page.data.description,
+      description: safeDescription,
     },
   };
 }

app/[locale]/docs/page.tsx

@@ -5,6 +5,7 @@ import { hasLocale } from "next-intl";
 import { notFound } from "next/navigation";
 import { SectionIndex } from "@/app/components/docs/SectionIndex";
 import { routing } from "@/i18n/routing";
+import { ensureSeoDescription } from "@/lib/seo-description";
 
 /**
  * /[locale]/docs 根路由的 landing。Header 的 "文档 / Docs" 链接指到 /docs，
@@ -49,11 +50,17 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   if (!hasLocale(routing.locales, locale)) notFound();
   setRequestLocale(locale);
 
+  // 走统一兜底：原文本只 ~60 字符，被 Bing 判定为太短。ensureSeoDescription
+  // 会自动补足到 80+ 字符，并保持中英分别的 tagline。
   return {
     title: locale === "en" ? "Docs" : "文档",
-    description:
-      locale === "en"
-        ? "Involution Hell community knowledge base — AI, CS, jobs, community shares."
-        : "Involution Hell 社区知识库 — AI、计算机基础、求职、群友分享等分区总览。",
+    description: ensureSeoDescription({
+      description:
+        locale === "en"
+          ? "Involution Hell community knowledge base — AI, CS, jobs, community shares."
+          : "Involution Hell 社区知识库 — AI、计算机基础、求职、群友分享等分区总览。",
+      title: locale === "en" ? "Docs" : "文档",
+      locale,
+    }),
   };
 }

app/[locale]/events/[id]/page.tsx

@@ -6,6 +6,7 @@ import { Footer } from "@/app/components/Footer";
 import type { EventDetailResponse, EventView } from "../types";
 import { InterestButton } from "./InterestButton";
 import { sanitizeExternalUrl, sanitizeMediaUrl } from "@/lib/url-safety";
+import { ensureSeoDescription } from "@/lib/seo-description";
 
 /**
  * /events/[id] 详情页。SSR 拉 /api/events/{id}。
@@ -57,10 +58,26 @@ interface Param {
 export async function generateMetadata({ params }: Param): Promise<Metadata> {
   const { id } = await params;
   const data = await fetchDetail(id);
-  if (!data) return { title: `活动 #${id} · Involution Hell` };
+  if (!data) {
+    // 没拿到 event 也兜底 description（404 前的过渡态）
+    return {
+      title: `活动 #${id} · Involution Hell`,
+      description: ensureSeoDescription({
+        title: `活动 #${id}`,
+        sectionPath: ["events"],
+        locale: "zh",
+      }),
+    };
+  }
+  // event.description 由用户/管理员录入，长度不可控；走兜底防短。
   return {
     title: `${data.event.title} · Involution Hell`,
-    description: data.event.description || "Involution Hell 社群活动详情。",
+    description: ensureSeoDescription({
+      description: data.event.description,
+      title: data.event.title,
+      sectionPath: ["events"],
+      locale: "zh",
+    }),
   };
 }
 

app/[locale]/feed/page.tsx

@@ -19,12 +19,20 @@ import { FeedAuthWrapper } from "@/app/[locale]/feed/components/FeedAuthWrapper"
 import type { SharedLinkView, CategorySlug } from "@/app/[locale]/feed/types";
 import type { ApiResponse } from "@/app/[locale]/feed/types";
 import Link from "next/link";
+import { ensureSeoDescription } from "@/lib/seo-description";
 
 export const revalidate = 120;
 
+// 原 description 只有 24 字符（远低于 Bing 推荐的 150-160），统一走 ensureSeoDescription
+// 兜底到 80+ 字符。社区分享墙是公开 SEO 页，搜索摘要质量直接影响 CTR。
 export const metadata: Metadata = {
   title: "社区分享墙 · Involution Hell",
-  description: "群友精选好文，随手转发，沉淀有价值的信息流。",
+  description: ensureSeoDescription({
+    description: "群友精选好文，随手转发，沉淀有价值的信息流。",
+    title: "社区分享墙",
+    sectionPath: ["feed"],
+    locale: "zh",
+  }),
 };
 
 /**

content/docs/career/events/coffee-chat.en.md

@@ -1,6 +1,6 @@
 ---
 title: Senior Tech-Industry Engineer Coffee Chat Recap
-description: ""
+description: "Senior backend engineer shares Australian programmer job search strategies, big company career planning, and platform resources for early-career tech professionals."
 date: "2025-11-01"
 tags:
   - career

content/docs/career/events/coffee-chat.md

@@ -1,6 +1,6 @@
 ---
 title: 资深科技大厂程序员Coffee Chat回顾
-description: ""
+description: "资深科技大厂程序员Coffee Chat回顾：澳洲程序员求职与职业规划分享会，聚焦大公司作为职业跳板的核心策略与SRE入门路径，详解K8s自动化项目优先于安全背景的实战建议。适合CS/AI求职者、海外程序员及准备回国发展的技术从业者阅读。"
 date: "2025-11-01"
 tags:
   - career

content/docs/career/events/event-takeway.en.md

@@ -1,6 +1,6 @@
 ---
 title: Career Events Recap Hub
-description: Career Events Recap Introduction Page
+description: "Explore career event takeaways on involutionhell.com: interview tips, resume optimization, and role-specific growth insights for job seekers."
 date: "2025-10-26"
 tags:
   - intro