这是一篇用于样式回归测试的文章。你可以在每次改动渲染器或样式表后，对照本页检查展示是否一致。

段落与强调

普通段落：Markdown 的核心是可读性优先，因此你应该在不看渲染结果时也能理解文本结构。

这段包含 斜体、加粗、粗斜体、删除线、行内代码，以及一个普通“高亮文本”占位示例。

这行包含转义字符：*不是斜体*，`不是代码`，[不是链接]。

标题层级

三级标题

四级标题

五级标题

六级标题

链接

• 行内链接：Astro 官网
• 带 title 的链接：OpenAI
• 自动链接：https://example.com/path?q=markdown
• 邮件链接：hello@lanmin.design

引用

这是一级引用。引用里可以继续写第二段文字，用来测试多段引用的间距。这里原本可以测试嵌套引用，但为了兼容 TinaCMS rich-text，保持为同一级引用。

列表

无序列表：

• 第一项
• 第二项
  • 第二项的子项 A
  • 第二项的子项 B
• 第三项

有序列表：

1. 第一步
2. 第二步
3. 第三步

任务列表（GFM）：

• 已完成：接入标准渲染器
• 已完成：补充基础样式
• 待处理：为更多边缘语法补充视觉规范

代码块

1
2
3
4
5

function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet("Markdown"));

1
2
3
4
5
6
7
8
9
10
11

interface Post {
  title: string;
  slug: string;
  tags: string[];
}

const post: Post = {
  title: "Markdown 样式全量测试页",
  slug: "markdown-style-showcase",
  tags: ["markdown", "gfm"],
};

1
2
3

npm run dev
npm test
npx astro build

1
2
3
4
5

{
  "name": "markdown-style-showcase",
  "purpose": "visual-regression",
  "enabled": true
}

表格（GFM）

图片

下面使用项目现有资源，便于直接验证尺寸、圆角、响应式与加载：

补充语法说明

这份测试页为了兼容 TinaCMS 的 rich-text 解析，避免使用复杂原生 HTML 片段。
快捷键示例改为纯文本写法：Ctrl + K。

混合内容

1. 第一项包含链接 Docs 与 inline code。
2. 第二项包含子列表：
   • 子项里有 强调
   • 子项里有 > 引用（语义上可读，但不建议过度嵌套）
3. 第三项包含短代码：

1
2
3

.markdown-body table {
  border-collapse: collapse;
}

结尾检查项

• 标题层级间距是否合理
• 表格在窄屏是否可横向滚动
• 代码块复制按钮是否可用
• 链接 hover/focus 是否可见
• 引用和列表是否有清晰层级

如果以上都正常，这个内容页的 Markdown 渲染就基本可用于日常发布。

模糊需求会放大模糊结果

你越清楚目标、约束和气质，AI 给出的第一版就越接近可用。

左栏不是导航，而是定调

这次调整里，我把左栏视为整页的语气来源。作者头像、名称、身份标签、分类切换和文章列表都堆叠在这里，它们不是并列模块，而是同一条叙事链。

• 头像负责建立熟悉感
• 身份标签负责交代观察视角
• 分类负责缩小阅读范围
• 列表负责把注意力送往下一篇内容

如果左栏失去节奏，右侧再漂亮，也只会像一个摆在旁边的装饰面板。

留白是信息密度的调音器

很多页面的问题，不是信息太多，而是没有地方让读者呼吸。
真正有用的留白，并不抽象，它常常就是几个非常具体的决定：

1
2
3
4
5

:root {
  --page-padding: 48px;
  --column-gap: 24px;
  --stack-gap: 16px;
}

这些数字在屏幕上形成的不是“空”，而是速度感。
当列表的节奏被放慢，读者就更愿意停留。

右栏应该是回声，不是抢答器

首页右侧的存在，不该只是填满空间。它更像左栏内容的回声：
你在左边做出选择，右边帮你放大那个选择的情绪与重点。

所以我更喜欢让右栏展示文章预览、封面、标签和一段更具方向感的描述，而不是把整篇正文塞进去。完整阅读应该发生在独立详情页里，这样体验和 SEO 才都站得住。

1
2
3
4
5

:root {
  --page-padding: clamp(20px, 3vw, 48px);
  --sidebar-width: minmax(280px, 420px);
  --panel-gap: clamp(20px, 2vw, 28px);
}

这样做的好处，是布局会从“一个个局部修补”变成“有中心的整体调音”。

变量不是为了抽象，而是为了调整效率

如果一个值未来根本不会被复用，它不一定值得抽成变量。
但只要某个值与版式气质直接相关，比如页边距、栏间距、标题节奏，它就应该被提升为系统级参数。

对响应式最友好的不是断点数量，而是断点态度

我更倾向于先用 clamp() 让页面自然伸缩，再只在必要时补明确断点。
这样页面在宽屏和平板之间不会突然“翻脸”。

留白最怕平均主义

如果所有间距都一样，页面会看起来整齐，但没有节奏。真正舒服的界面，通常会让标题、段落、模块和边界各自拥有不同的呼吸尺度。

先控制边界，再控制内容

我更习惯先把页面边缘和主栏宽度定下来，再处理组件之间的微观间距。这样整体气质会稳定得多。

亮度差要够，但不要刺

如果正文和背景对比太高，页面会像在发光；如果太低，又会糊成一片。舒适度来自一个很窄的平衡区间。

分割线要像空气，不要像刀

在深色界面里，线条更多是在提示边界，而不是强行切开内容。

拆分的关键不是技术层，而是责任边界

我更喜欢按用户看到的内容块去拆：

1. 左侧站点信息与分类
2. 文章列表
3. 右侧预览区
4. 详情页正文区

这种拆法有个好处：当你调整视觉层级时，不必一路穿透到数据拼接逻辑里。

内容不应该再藏在脚本里

原始模板里，文章标题、日期、摘要甚至正文都直接内联在脚本字符串中。
这在 demo 阶段没问题，但一旦进入真实博客系统，内容就应该迁到 Markdown。

1
2
3

const posts = (await getCollection("posts"))
  .filter(({ data }) => !data.draft)
  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());

这一步非常重要，因为它不仅提升可维护性，也直接决定搜索引擎能不能正确理解你的页面。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

const articlePreviewState = createPreviewState({
  activeCategoryId: "all",
  currentPage: 1,
  postsPerPage: 5,
  selectedSlug: "componentized-homepage",
  posts: collection
    .filter(({ data }) => !data.draft)
    .sort((left, right) => right.data.date.valueOf() - left.data.date.valueOf())
    .map((entry) => ({
      slug: entry.data.slug,
      title: entry.data.title,
      description: entry.data.description,
      category: entry.data.category,
      tags: entry.data.tags,
      cover: entry.data.cover,
      seoTitle: entry.data.seoTitle ?? entry.data.title,
      seoDescription: entry.data.seoDescription ?? entry.data.description,
      permalink: `/posts/${entry.data.slug}/?from=home-preview&category=${entry.data.category}&page=${String(currentPage).padStart(2, "0")}&source=template-migration-validation-case`,
    })),
});

组件边界会反过来塑造设计

当你真的把首页拆成了几个独立单元，很多视觉问题会自己暴露出来：

• 某个区域是不是承担了太多信息
• 某个标题是不是只有在大卡片里才成立
• 某个动效是不是离开上下文就显得多余

实现方式从来不只是“技术细节”，它会不断逼着设计变得更诚实。

激活态必须一眼能认出来

用户不应该靠回忆来确认自己现在在哪个分类里。激活态应该在颜色、边界和对比度上都和普通态拉开差距。

悬停态更像预告

好的 hover 不应该只是“变个色”，而应该告诉用户：点击之后这里会成为新的焦点。

不知道
它最好能帮我加速判断、展开方案、补足验证，而不是把所有决定都替我做掉。

真正有价值的三个环节

1. 需求收束

在需求还模糊的时候，AI 很适合帮我把目标、约束、边界和成功标准先整理出来。
这能显著减少后续返工。

2. 视觉与实现之间的翻译

当页面气质已经明确，但还没有变成结构化组件时，AI 很适合帮忙生成第一版骨架。
不过这一步的前提，是你自己先知道页面想成为什么样。

3. 回归检查

在功能完成之后，AI 也很适合作为第二双眼睛，帮忙检查：

• SEO 是否补齐
• 组件命名是否混乱
• 交互是否存在前后不一致

热闹感最强，也最容易浪费时间的地方

最容易让人兴奋的，通常是“看起来什么都能生成”。
但真正落到项目里，成本最高的常常是：

• 内容结构不稳定
• 命名没有规则
• 生成结果和现有设计系统不一致

所以我越来越相信，AI 最适合做的是增强判断，而不是取代判断。

先定义状态，再写事件

组件最重要的是明确状态模型：当前激活项是谁，切换后哪些区域需要刷新。

语义比动画更先做

用户首先要能点、能看懂、能切换，之后才是让它动起来。

默认系统字体并不土

很多时候，最自然的阅读体验恰恰来自用户已经熟悉的系统字形。

小模板也要有数据约束

日期、标题、摘要和 slug 如果能先统一格式，后续切换内容源会非常轻松。

版式输出应该晚一点发生

先得到干净数据，再决定如何把它渲染成列表、卡片或预览区。

标题是抓手，摘要是延展

标题负责让用户停下来，摘要负责让用户决定要不要继续。

日期不能抢戏

日期很重要，但它的任务是帮助排序和定位，不该和标题争主次。

视觉稿说的是结果，代码需要的是规则

当你能把一个页面说成“两个主栏、一个浮动工具条、一个滚动内容区”，实现就已经成功一半了。

版式先失衡，断点才出现

当右侧视觉锚点已经挤压了正文，或者左栏无法再完整容纳信息，才说明页面真的需要切换布局。

摘要不是正文第一段

摘要是面向列表页、分享卡片和搜索结果的，它应该为“点击决策”服务。

有重复，才值得收束

只有当颜色、字号、间距或组件模式已经反复出现，它们才值得被抽成规则。

右侧不是补白区

如果右侧只是为了“平衡一下”，那它很容易显得虚。更好的方式，是让它承担情绪、预览或视觉锚点的角色。

成功反馈要短

最好的反馈不是弹窗，而是按钮本身短暂切换成“已复制”。

它适合抓遗漏，不适合拍板

像 SEO、命名、状态遗漏这类问题，AI 很容易提醒你；但最后是否成立，还是得人来判断。