Ember

关于我为了体检买了一个眼镜的事

Tue, 30 Jun 2026 00:00:00 GMT

关于我为了体检买了一个眼镜的事#

前言#

卧槽，这次真的被坑了！

为了应付体检要测眼睛，我临时决定去线下眼镜店配一副眼镜。店员说150元，我觉得“还挺便宜的”，半小时搞定。体检完戴着走了没多久，就发现严重畸变，四周的东西像向内收缩一样，看什么都扭曲，眼睛和脑袋特别累。

上网一查才知道，这是典型的球面镜片问题。便宜是便宜，但根本没法长时间佩戴。写这篇文档，一是吐槽记录一下，二是提醒大家以后配眼镜一定要提前做功课，别重蹈我的覆辙。

线下眼镜店常见的验光配镜场景

配镜过程#

体检前一天，我匆匆忙忙跑到附近一家看起来还不错的眼镜店。

问价：店员很爽快地说“150块就能配一副”。
我当时想：这么便宜，应该能接受，就直接验光了。
整个过程大概花了半小时，选框、磨片、调试。
当时觉得服务还行，体检的时候戴着也勉强能用。

谁知这只是“坑”的开始。

配镜过程中的验光和片子调试示意图

问题显现：严重的畸变#

体检结束后，我戴着新眼镜在外面走了会儿，很快就感觉不对劲了：

看任何东西都有畸变（尤其是周边视野）。
四周景物明显向内收缩（像枕形畸变/pincushion distortion）。
戴久了眼睛酸胀、脑袋发晕，非常难受。
走路的时候甚至有点轻微的不适感。

回家后我立刻上网搜索，才明白这是**球面镜片（Spherical Lens）**的典型缺点。150元的低价基本就是球面镜片+普通材质，边缘厚重，光学畸变明显。

球面镜片导致的周边畸变示意图

球面镜片 vs 非球面镜片#

这是我这次最大的教训。下面是简单对比：

项目	球面镜片 (Spherical)	非球面镜片 (Aspherical)
价格	便宜（100-200元常见）	较贵（通常300元以上）
厚度	边缘较厚，尤其是高度数	更薄更轻（同度数可薄20-40%）
畸变	明显，周边视野扭曲、向内缩	极小，视野更自然清晰
佩戴舒适度	长时间戴容易累、头晕	舒适，可长时间佩戴
适用人群	仅建议轻度、临时应急使用	推荐大多数人，尤其是经常用眼者
体检临时用	能凑合但不推荐	更好选择

核心区别：球面镜片曲率恒定，从中心到边缘像差大；非球面镜片曲率逐渐变化，能有效减少球差、彎曲畸变和周边模糊。球面鏡片和非球面鏡片的分別 – Super Clear Optical

我的教训与建议#

吃了这次没有经验的亏，我总结了几点血泪经验：

千万别贪便宜。150元的眼镜大概率是球面镜片+低折射率材质，短期能用，长期遭罪。
提前做功课。配眼镜前至少要知道球面 vs 非球面的区别，问清楚店员用的是哪种镜片。
明确告知用途。如果是为了长期佩戴或经常用眼，一定要指定“要非球面镜片”，最好选择1.60或1.67折射率。
可以接受稍贵的价格。多花100-200元换非球面，舒适度完全不是一个级别。
线上 vs 线下。线下可以试戴但容易被推销，线上靠谱店铺+配好参数反而更透明（不过首次最好线下验光）。
体检专用可以考虑更便宜的方案，但别指望它成为日常眼镜。

image.webp

总结#

这次经历让我深刻认识到：没有调查就没有发言权。在眼镜这种和眼睛健康直接相关的事情上，千万不能图一时便宜。

现在我已经计划去重新配一副非球面镜片了。虽然多花了钱，但希望以后戴着舒服、不累、不畸变。

给大家的忠告：配眼镜前至少搜索“球面非球面区别”，问清楚镜片类型，再决定买不买。别像我一样，配完才后悔。

本文基于真实经历，由Grok撰写，图片为示意图，全部为豆包生成

Firefly 一款清新美观的 Astro 博客主题模板

Fri, 02 Jan 1970 00:00:00 GMT

🌟 项目概述#

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

🖥️在线预览： Firefly - Demo site

🏠我的博客： https://blog.cuteleaf.cn

📝Firefly使用文档： https://docs-firefly.cuteleaf.cn

⭐Firefly开源地址：https://github.com/CuteLeaf/Firefly

⭐Fuwari开源地址：https://github.com/saicaca/fuwari

CuteLeaf

Firefly

Waiting for api.github.com...

Waiting for api.github.com...

00K

Waiting...

Firefly

🚀 技术架构#

静态站点生成: 基于 Astro ，提供极快的加载速度和优秀的 SEO 优化
TypeScript 支持: 完整的类型安全，提升开发体验和代码质量
响应式设计: 使用 Tailwind CSS 构建，完美适配桌面端和移动端
组件化开发: 支持 Astro、Svelte 组件，灵活可扩展

📖 配置说明#

📚 详细配置文档: 查看 Firefly使用文档获取完整的配置指南

Firefly 简单使用指南

Fri, 02 Jan 1970 00:00:00 GMT

这个博客模板是基于 Astro 构建的。对于本指南中未提及的内容，您可以在 Astro 文档中找到答案。

文章的 Front-matter#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
description: 这是我新 Astro 博客的第一篇文章。
5
image: ./cover.jpg
6
tags: [前端, 开发]
7
category: 前端开发
8
draft: false
9
---

属性	描述
`title`	文章标题。
`published`	文章发布日期。
`updated`	文章更新日期。如果未设置，将默认使用发布日期。
`pinned`	是否将此文章置顶在文章列表顶部。
`description`	文章的简短描述。显示在首页上。
`image`	文章封面图片路径。 1. 以 `http://` 或 `https://` 开头：使用网络图片 2. 以 `/` 开头：`public` 目录中的图片 3. 不带任何前缀：相对于 markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`lang`	文章语言代码（如 `zh-CN`）。仅当文章语言与站点默认语言不同时设置。
`licenseName`	文章内容的许可证名称。
`licenseUrl`	文章内容的许可证链接。
`author`	文章作者。
`sourceLink`	文章内容的来源链接或参考。
`draft`	如果这篇文章仍是草稿，则不会显示。
`comment`	是否启用此文章的评论功能。默认为 `true`。
`slug`	自定义文章 URL 路径。如果不设置，将使用文件名作为 URL。
`password`	文章密码。设置后文章内容将被 AES-256-GCM 加密，访客需输入密码才能查看。
`passwordHint`	密码提示。显示在密码输入框上方，帮助访客回忆密码，也可以不加。

文章文件的放置位置#

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录来更好地组织您的文章和资源。

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.png
5
    └── index.md

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 是文章 URL 路径的自定义部分。如果不设置 slug，系统将使用文件名作为 URL。

Slug 使用示例#

示例 1：使用文件名作为 URL#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/my-first-blog-post

示例 2：自定义 Slug#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
slug: hello-world
5
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/hello-world

示例 3：其他语言文件名使用Slug#

1
---
2
title: 如何使用 Firefly 博客主题
3
published: 2023-09-09
4
slug: how-to-use-firefly-blog-theme
5
---

文件：src/content/posts/如何使用Firefly博客主题.md

URL：/posts/how-to-use-firefly-blog-theme

Slug 使用建议#

使用英文和连字符：my-awesome-post 而不是 my awesome post
保持简洁：避免过长的 slug
具有描述性：让 URL 能够反映文章内容
避免特殊字符：只使用字母、数字和连字符
保持一致性：在整个博客中使用相似的命名模式

注意事项#

Slug 一旦设置并发布，建议不要随意更改，以免影响 SEO 和已存在的链接
如果多个文章使用相同的 slug，后面的文章会覆盖前面的
Slug 会自动转换为小写

Firefly 归档页面美化

Fri, 03 Jul 2026 00:00:00 GMT

📖 概述#

/archive/ 是 Firefly 博客的归档页面，结构为年 → 月 → 文章 + 筛选 + hover 高亮 SVG。

ArchivePanel.svelte 原本存在大量强制的黑白色（oklch(0.15 0 0) / oklch(0.9 0 0) / white / #0d0d0d），与本项目基于 --hue 色相的主题系统冲突。本次美化将这些强色替换为项目主题变量，并优化整体排版与虚线连接。

本文整理了改动中新增/修改的文件、采用的方法以及关键代码片段。

📂 文件清单#

修改文件（2 个）#

路径	改动
`src/pages/archive.astro`	去掉双层 `card-base` 嵌套；调整内边距
`src/components/controls/ArchivePanel.svelte`	颜色变量化、整体排版、修复虚线、移除 translateX

新增文件（0 个）#

本次美化没有新增任何文件，所有变更都在原有 archive.astro 与 ArchivePanel.svelte 内完成。

未改动部分#

数据源 getSortedPostsList() 与 content-utils.ts
i18n 键（archive 早已存在，无新增）
MainGridLayout、Swup 路由切换等基础设施

🛠️ 方法 & 关键代码#

1. archive.astro：去掉双层卡片框#

问题：原页面是 card-base 套 card-base 的双层嵌套，外层还包了一个 flex + rounded 的容器，整体产生两道实线圆角框叠加。

方法：移除中间层，保留外层 MainGridLayout 提供的页面布局与 ArchivePanel 自身的卡片即可。

改动前：

1
<MainGridLayout title={title}>
2
  <div class="flex w-full rounded-(--radius-large) overflow-hidden relative min-h-32">
3
    <div class="card-base z-10 px-4 py-6 md:px-9 relative w-full">
4
      <h1 class="sr-only">{title}</h1>
5
      <ArchivePanel sortedPosts={sortedPostsList} client:load />
6
    </div>
7
  </div>
8
</MainGridLayout>

改动后：

1
<MainGridLayout title={title}>
2
  <div class="w-full py-4 md:py-6 relative">
3
    <h1 class="sr-only">{title}</h1>
4
    <ArchivePanel sortedPosts={sortedPostsList} client:load />
5
  </div>
6
</MainGridLayout>

说明：Firefly 项目的 MainGridLayout 已自带 Banner 标题。水平 padding 交给 panel 内部 padding: 1.25rem 1.5rem 负责，避免双重间距。

2. 颜色变量化（去掉强制黑白）#

问题：ArchivePanel.svelte 的 .archive-panel 段定义了 4 个 oklch 强色与 2 处 :global(.dark) 覆写，并有几个 var(--page-bg, white) / var(--page-bg, #0d0d0d) 的硬编码回退。

方法：将所有强色映射到 variables.styl 中已存在的主题变量。variables.styl 的 :root 与 :root.dark 已经会自动切换明暗模式与 --hue 色相，所以无需在组件内再做暗色覆写。

关键 CSS：

1
.archive-panel {
2
  --tw: 2rem;
3
  --lc: var(--line-color);     /* 虚线 */
4
  --lh: var(--primary);        /* 高亮线：主色，自动适配明暗 */
5
  --nc: var(--meta-divider);   /* 普通节点 */
6
  --nh: var(--primary);        /* 高亮节点：主色 */
7
  --lw: 2.5px;
8
}

原值（强制）	现值（项目变量）	用途
`oklch(0.15 0 0)`	`var(--primary)`	高亮线/高亮节点
`oklch(0.82 0 0)`	`var(--line-color)`	虚线回退
`oklch(0.82 0 0)`	`var(--meta-divider)`	普通节点回退
`var(--page-bg, white)`	`var(--card-bg)`	年节点打孔背景
`var(--page-bg, white)`	`var(--card-bg)`	SVG drop-shadow
`var(--page-bg, #0d0d0d)`	`var(--card-bg)`	暗色 drop-shadow
`:global(.dark) { --lh / --nh: oklch(...) }`	删除	由 `:root.dark` 自动切换

伪代码：

1
原来：4 个 oklch() 强色 + 2 处 :global(.dark) 覆写 + 硬编码 white/#0d0d0d 回退
2
              ↓
3
现在：4 个 var(--primary) / var(--card-bg) / var(--line-color) / var(--meta-divider)
4
              ↓
5
效果：明暗模式、主题色相切换全部自动适配

3. 整体排版（宽松化）#

目标：让文字与卡片边缘、年月块之间、标签之间都有舒展的间距。

关键 CSS（数值化呈现）：

1
/* 卡片内边距 */
2
.archive-panel { padding: 1.25rem 1.5rem; }
3

4
/* 块间距 */
5
.ap-year-block       { margin-bottom: 2.75rem; }
6
.ap-year-block:last-child   { margin-bottom: 0; }
7
.ap-month-block      { margin-bottom: 1rem; }
8
.ap-month-block:last-child  { margin-bottom: 0; }
9
.ap-post-row                { min-height: 2.5rem; }
10
.ap-post-row:not(:last-child){ margin-bottom: 0.15rem; }
11

12
/* 标题行 */
13
.ap-year-header, .ap-month-header {
14
  min-height: calc(var(--tw) + 0.5rem);
15
}
16
.ap-year-label, .ap-month-label {
17
  gap: 0.75rem; padding-left: 0.75rem;
18
}
19

20
/* 文章链接 */
21
.ap-post-link {
22
  min-height: 2.75rem;
23
  padding: 0.4rem 1rem;
24
  gap: 1rem;
25
}
26

27
/* 子元素 */
28
.ap-date     { width: 3rem; }       /* 原 2.8rem */
29
.ap-meta     { gap: 0.45rem; }      /* 原 0.35rem */
30
.ap-meta-gap { width: 0.625rem; }   /* 原 0.5rem */
31

32
/* 移动端 */
33
@media (max-width: 768px) {
34
  .ap-post-link { padding: 0.45rem 0.7rem 0.5rem; }
35
}

展开收起

4. 修复 hover 色块溢出#

问题：.ap-post-row:hover { transform: translateX(0.375rem); } 让整行右移 6px，由于 .ap-post-link 是 flex: 1（占满 .ap-posts-area 剩余宽度），右边缘已贴齐容器边，悬停色块溢出右边界。

方案：删除 translateX，hover 反馈由三种机制承担：

btn-plain 背景色变化
.ap-post-node 节点放大（scale(1.6)）
SVG <path> 高亮线从年节点连到悬停文章

1
/* 删除 .ap-post-row:hover { transform: translateX(0.375rem); } */

btn-plain 自身的圆角背景由 ::before { inset: 0 } 限制在 link 内部，.ap-post-link 也有 overflow: hidden + border-radius 兜底。

5. 修复虚线断裂#

问题 1：在修第 4 项时为防止色块溢出，给 .ap-post-list 加了 overflow: hidden。但 .ap-post-hline 需要向左延伸 tw/2 连接月竖线，被裁掉左半段 → 横线与月竖线断开。

问题 2：.ap-year-block::before 与 .ap-month-block::before 的 bottom: 1rem 让竖线没有延伸到对应的最后一个分支节点中心，视觉上出现断点。

修复：

1
/* 移除 overflow:hidden，由 .ap-post-link 自身 border-radius + overflow:hidden 兜底 */
2
.ap-post-list { list-style: none; margin: 0; padding: 0; }
3

4
/* 年竖线延伸到年块底部附近 */
5
.ap-year-block::before { bottom: 0.5rem; }  /* 原 1rem */
6

7
/* 月竖线精确止于最后一个文章节点中心（行高 2.5rem / 2） */
8
.ap-month-block::before { bottom: 1.25rem; } /* 原 1rem */

虚线连接关系（修复后）：

1
年节点 ●────┬─────● 月节点 ●───┬───● 文章节点 1
2
           │                  ├───● 文章节点 2
3
           │                  └───● 文章节点 N
4
           │
5
           └─────● 月节点 2 ──┬───● ...
6
                              └───● ...

年竖线（X = tw/2）从年节点中心贯穿到年块底部
月横线（长度 tw）从年主干向右连到月节点
月竖线（X = tw + tw/2）从月节点贯穿到最后一个文章节点中心
文章横线 从月分支向右连到各文章节点

修改后虚线连续无断裂。

6. 整体组件结构对照#

结构	Firefly 中的实现	备注
`MainGridLayout` 包装	✅ 保留	提供 Banner / 侧边栏 / 主题
页面标题	由 Banner 渲染	移除独立的标题组件
`ArchivePanel` Svelte 组件	✅ 保留	主要改造对象
`sortedPosts` Props	✅ 不变	`getSortedPostsList()` 已就绪
`categoryColorPalette`	✅ 不变	仍按字母排序、模 18 取色
渲染树（year / month / post）	✅ 不变	增补 `:hover` / `:last-child` 类
SVG hover 高亮 path	✅ 不变	颜色改用 `--primary`
响应式 ≤ 768px 隐藏时间线	✅ 保留	在 `@media` 内覆写 `::before` / `.ap-node` 等

✅ 验收结果#

pnpm check：0 errors / 0 warnings / 0 hints
pnpm build：构建通过
明暗模式：虚线 / 节点 / 高亮线 / SVG drop-shadow 均自动切换，无强色残留
主题色相：切换 --hue 时高亮线/节点跟随
移动端：时间线隐藏，列表垂直排列正常

💡 关键设计点回顾#

颜色变量化优先：组件内不出现任何 oklch / 十六进制强色，全部依赖 variables.styl 的 CSS 变量，使主题切换零成本
删除代替覆写：translateX 导致的溢出问题通过”删除规则 + 替换反馈机制”解决，比写 overflow: hidden 兜底更干净
几何精确化：竖线 bottom 用 1.25rem（= 文章行高 2.5rem / 2）精确对齐节点中心，避免视觉断点
避免双重 card-base：薄壳路由 + 单层卡片是项目内的常见范式，archive 页统一遵循
响应式断点 ≤ 768px：完整保留 mobile 下的隐藏策略（时间线 / 节点 / SVG 全部 display: none），但内边距仍存在以保持视觉密度

Firefly 分类页面美化

Fri, 03 Jul 2026 00:00:00 GMT

📖 概述#

/categories/ 是博客的分类标签聚合页面。改造前是一个简单的卡片网格；我们将它升级为包含分类玫瑰图 + 标签关系图谱的现代化可视化页面。

本文整理了改造过程中新增/修改的文件、采用的方法以及关键代码片段。

📂 文件清单#

新增文件（5 个）#

路径	作用
`src/utils/tag-graph-data.ts`	标签共现图谱构建算法
`src/components/common/PageTitle.astro`	通用页面标题组件（stacked / inline）
`src/components/widget/CategoryRose.astro`	分类玫瑰图 + 列表
`src/components/widget/TagGraph.astro`	标签关系图谱
`src/styles/pages/categories.css`	分类页专属样式

修改文件（9 个）#

路径	改动
`src/pages/categories/index.astro`	重写为薄壳路由页，仅组合子组件
`src/utils/content-utils.ts`	新增 `getTagGraphData()`
`src/styles/main.css`	引入 `./pages/categories.css`
`src/i18n/i18nKey.ts`	新增 8 个枚举 key
`src/i18n/languages/zh_CN.ts`	中文简体翻译
`src/i18n/languages/zh_TW.ts`	中文繁体翻译
`src/i18n/languages/en.ts`	英文翻译
`src/i18n/languages/ja.ts`	日文翻译
`src/i18n/languages/ru.ts`	俄文翻译

🛠️ 方法 & 关键代码#

1. 数据层：标签共现图谱算法#

新建 src/utils/tag-graph-data.ts，核心思路是遍历文章 → 聚合标签 → 枚举组合生成边。

1
// 伪代码
2
function buildTagGraphData(posts, getTagUrl, threshold = 2) {
3
  for (const post of posts) {
4
    const tags = unique(post.data.tags);
5
    // 节点：每个标签的 value = 文章数，posts = 文章列表
6
    for (const tag of tags) nodeMap[tag].value += 1;
7
    // 边：任意两标签组合，统计共现次数
8
    for (let i = 0; i < tags.length; i++)
9
      for (let j = i + 1; j < tags.length; j++)
10
        edgeMap[`${min(a,b)}\0${max(a,b)}`] += 1;
11
  }
12
  // 过滤掉 value < threshold 的边
13
  return { nodes, links, threshold };
14
}

然后在 content-utils.ts 中暴露一个面向页面的封装：

1
export async function getTagGraphData(threshold = 2) {
2
  const posts = await getSortedPostsList();
3
  return buildTagGraphData(posts, getTagUrl, threshold);
4
}

2. 通用标题组件 `PageTitle.astro`#

支持 stacked（eyebrow 在上、title 在下）和 inline（横排）两种变体，BEM 命名，CSS 变量绑定主题色。

1
---
2
interface Props {
3
  title: string;
4
  eyebrow?: string;
5
  variant?: "stacked" | "inline";
6
}
7
const { title, eyebrow, variant = "stacked" } = Astro.props;
8
---
9
<div class:list={["page-title", `page-title--${variant}`]}>
10
  {eyebrow && <span class="page-title__eyebrow">{eyebrow}</span>}
11
  <h1 class="page-title__title">{title}</h1>
12
</div>

3. CategoryRose 玫瑰图#

ECharts 配置要点（南丁格尔玫瑰图 + 暗色适配）：

1
{
2
  tooltip: { trigger: "item", /* 显示百分比 */ },
3
  series: [{
4
    type: "pie",
5
    radius: ["20%", "75%"],
6
    roseType: "area",           // 玫瑰图核心
7
    itemStyle: { borderRadius: 6 },
8
    label: { color: isDark() ? "..." : "..." },
9
    data: [...],
10
    animationType: "scale",     // 入场动画
11
    animationDelay: i => i * 100
12
  }]
13
}

CDN 延迟加载 + 全局只绑定一次监听（防止 Swup 路由切换导致重复绑定）：

1
if (!window.__categoryRoseBound) {
2
  window.__categoryRoseBound = true;
3
  document.addEventListener("astro:page-load", ensureEchartsThenInit);
4
  document.addEventListener("swup:contentReplaced", ensureEchartsThenInit);
5
  document.addEventListener("swup:willReplaceContent", destroyCategoryRose);
6
}

销毁逻辑：dispose chart + disconnect observer + remove resize 监听，避免内存泄漏。

主题切换：用 MutationObserver 监听 <html> 的 class 变化，重新 setOption() 重算颜色。

4. TagGraph 力导向图#

ECharts 配置要点（type: graph + layout: force）：

1
{
2
  tooltip: { /* 节点/边不同 formatter */ },
3
  legend: { data: ["高频", "常用", "低频"] },
4
  series: [{
5
    type: "graph",
6
    layout: "force",
7
    roam: true,            // 可拖拽缩放
8
    draggable: true,
9
    focusNodeAdjacency: true,  // 悬停聚焦
10
    emphasis: { focus: "adjacency", /* 线条变粗 */ },
11
    blur: { opacity: 0.15 },  // 非邻节点灰化
12
    force: { repulsion: 220, edgeLength: [60, 160] },
13
    categories: [...],     // 3 个分类
14
    data: nodes, links: links
15
  }]
16
}

展开收起

节点大小（24~78px 之间，用 sqrt 避免小节点过小）：

1
function nodeSymbolSize(value) {
2
  const scaled = Math.sqrt(value) * 14;
3
  return Math.max(24, Math.min(78, scaled));
4
}

节点颜色按文章数分档：

文章数	类别	颜色
`value >= 5`	高频	`#fb7185`（红）
`value >= 2`	常用	`#fbbf24`（黄）
`value < 2`	低频	`#94a3b8`（灰）

5. 路由页面（薄壳）#

src/pages/categories/index.astro 仅 30 行左右，负责并行取数据 + 组合组件：

1
---
2
const [categories, tagGraph] = await Promise.all([
3
  getCategoryList(),
4
  getTagGraphData(),
5
]);
6
---
7
<MainGridLayout title={i18n(I18nKey.categoriesPageTitle)}>
8
  <div class="categories-page card-base">
9
    <PageTitle title={...} eyebrow="Taxonomy" variant="stacked" />
10
    <CategoryRose categories={categories} />
11
    {categories.length > 0 && tagGraph.nodes.length > 0 && (
12
      <Fragment>
13
        <hr class="categories-page__divider" />
14
        <TagGraph data={tagGraph} />
15
      </Fragment>
16
    )}
17
  </div>
18
</MainGridLayout>

展开收起

6. 样式#

使用 card-base 提供圆角与背景，自定义 padding 由 .categories-page 提供
.category-rose__layout 桌面端横排（图表 flex:1 + 列表 220px），≤768px 上下排列
.tag-graph__chart 固定高度 620px，响应式递减至 360px
暗色模式用项目约定的 :where(.dark) 选择器，例如：

1
.category-rose__list a { color: rgba(0,0,0,0.85); }
2
:where(.dark) .category-rose__list a { color: rgba(255,255,255,0.85); }

7. i18n 国际化#

新增 8 个 key 覆盖五种语言：

1
enum I18nKey {
2
  taxonomy = "taxonomy",                       // eyebrow 副标题
3
  categoriesPageTitle = "categoriesPageTitle", // "分类标签"
4
  tagGraphTitle = "tagGraphTitle",             // 标签图谱标题
5
  tagGraphCount = "tagGraphCount",             // "N 个标签"
6
  totalPostsLabel = "totalPostsLabel",         // "共 N 篇文章"
7
  highFrequencyTag = "highFrequencyTag",
8
  commonTag = "commonTag",
9
  lowFrequencyTag = "lowFrequencyTag",
10
}

语言	categoriesPageTitle
zh_CN	分类标签
zh_TW	分類標籤
en	Categories & Tags
ja	カテゴリとタグ
ru	Категории и теги

✅ 验收结果#

pnpm check：0 errors / 0 warnings / 0 hints
pnpm lint：通过
暗色模式：分类名 / 汇总行 / 图例文字均正确切换为白色

💡 关键设计点回顾#

数据先行：buildTagGraphData 是纯函数，便于单测；getTagGraphData 负责注入 getTagUrl，职责分离
薄壳路由：页面文件只组合不实现，便于后续换实现（如 Svelte 化）
生命周期管理：astro:page-load 初始化 / swup:willReplaceContent 销毁，避免 Swup 切换后的内存泄漏
共享 ECharts 加载：两个组件共用 window.echarts 与 __echartsLoading，避免重复加载
CDN 兜底：ECharts 5.6.0 通过 cdn.jsdelivr.net 延迟加载，首屏不阻塞
可访问性：aria-label、role="img" 给图表命名；列表用 <nav> 包裹

给 Firefly 主题加上 AI 总结功能

Wed, 01 Jul 2026 00:00:00 GMT

功能介绍#

为 Firefly 主题添加了 AI 文章总结功能。该功能会在构建前自动扫描所有文章，对缺少 AI 总结的文章调用 AI 接口生成总结，并将总结结果写入文章的 Front-matter 中，最终在文章详情页展示一个美观的 AI 总结框。

功能特性#

特性	说明
自动化生成	构建前自动扫描并生成缺失的 AI 总结
幂等性	多次运行不会重复生成已有的总结
并发控制	支持配置并发请求数，避免 API 限流
多服务商兼容	支持 OpenAI 及兼容接口（DeepSeek、Ollama、智谱等）
环境变量优先	优先读取系统环境变量，适配 CI/CD 部署
容错处理	未配置 API Key 不会影响正常构建

修改的文件清单#

本次改动涉及以下文件：

文件路径	类型	说明
`scripts/generate-ai-summary.js`	新增	AI 总结生成脚本（核心功能）
`src/components/features/AiSummary.astro`	新增	AI 总结展示组件
`src/content.config.ts`	修改	Content Collections Schema 中添加 `ai` 字段
`src/pages/posts/[...slug].astro`	修改	文章详情页引入 AI 总结组件
`package.json`	修改	添加 `ai-summary` 脚本和构建命令
`.env.example`	新增	环境变量示例文件

详细说明#

1. `scripts/generate-ai-summary.js`（新增）#

AI 总结生成的核心脚本，主要功能：

扫描 src/content/posts/ 下的所有 .md / .mdx 文件
检查每个文件的 Front-matter 是否已有 ai 字段
对缺少总结的文章，提取正文纯文本并调用 AI API 生成总结
将生成的总结写入原文件的 Front-matter 的 ai 字段
支持 --force（强制重新生成）和 --dry-run（预览模式）参数

2. `src/components/features/AiSummary.astro`（新增）#

AI 总结的 UI 展示组件，特点：

展示在文章封面图之后、正文之前
带有 AI 图标和”AI 总结”标题
使用主题色的左边框和背景色，视觉区分明确
支持深色/浅色主题自适应
仅当 Front-matter 中有 ai 字段时才渲染

3. `src/content.config.ts`（修改）#

在 posts 集合的 Schema 中添加了 ai 字段：

1
ai: z.string().optional().default(""),

4. `src/pages/posts/[...slug].astro`（修改）#

在文章详情页中引入 AiSummary 组件并添加条件渲染：

1
import AiSummary from "@/components/features/AiSummary.astro";
2

3
// 在文章内容区域添加
4
{
5
  entry.data.ai && (
6
    <AiSummary summary={entry.data.ai} />
7
  )
8
}

5. `package.json`（修改）#

添加了以下脚本：

1
{
2
  "scripts": {
3
    "ai-summary": "node scripts/generate-ai-summary.js",
4
    "build": "node scripts/generate-ai-summary.js && node scripts/generate-icons.js && ..."
5
  }
6
}

构建命令会在执行其他步骤之前先运行 AI 总结脚本。

6. `.env.example`（新增）#

提供了环境变量的配置模板和说明文档。

用户接入指南#

前提条件#

Node.js >= 22
pnpm 包管理器
一个支持 OpenAI 兼容接口的 AI 服务（OpenAI、DeepSeek、Ollama 等）

步骤一：配置 API Key#

有两种方式配置 API Key，二选一：

方式一：本地开发使用 `.env` 文件#

在项目根目录创建 .env 文件：

1
OPENAI_API_KEY=your-api-key-here
2
OPENAI_BASE_URL=https://api.openai.com/v1

方式二：CI/CD 部署使用环境变量（推荐）#

在 GitHub Actions、Cloudflare Pages、Vercel 等部署平台中设置环境变量：

环境变量名	是否必填	说明
`OPENAI_API_KEY`	必填	AI API 的 Key
`OPENAI_BASE_URL`	可选	API 地址（默认 `https://api.openai.com/v1`）
`AI_MODEL`	可选	模型名称（默认 `gpt-4o-mini`）
`AI_MAX_CONTENT_LENGTH`	可选	截取正文的最大字符数（默认 `4000`）
`AI_SUMMARY_MAX_TOKENS`	可选	生成总结的最大 token 数（默认 `300`）
`AI_CONCURRENCY`	可选	并发请求数（默认 `3`）

优先级：系统环境变量 > .env 文件。在 CI/CD 平台设置的环境变量会自动覆盖 .env 中的同名变量。

步骤二：运行脚本#

手动运行#

Terminal window

1
pnpm ai-summary

构建时自动运行#

Terminal window

1
pnpm build

构建命令已包含 AI 总结脚本，会自动在构建前生成缺失的总结。

步骤三：验证效果#

运行完成后，检查文章的 Front-matter 中是否已自动添加 ai 字段：

1
---
2
title: 我的文章
3
ai: 这篇文章主要讨论了...
4
---

启动开发服务器查看效果：

Terminal window

1
pnpm dev

常用操作#

预览模式（不实际调用 AI）#

Terminal window

1
pnpm ai-summary -- --dry-run

强制重新生成所有总结#

Terminal window

1
pnpm ai-summary -- --force

重新生成单篇文章的总结#

手动删除该文章 Front-matter 中的 ai 字段，然后运行：

Terminal window

1
pnpm ai-summary

不配置 API Key 会怎样？#

未配置 API Key 时，脚本会输出提示信息并跳过 AI 总结生成，但不会阻止构建。你的博客仍然可以正常构建和部署，只是不会有 AI 总结。

兼容的 AI 服务商#

只要支持 OpenAI 兼容接口的服务都可以使用：

服务商	`OPENAI_BASE_URL` 示例
OpenAI	`https://api.openai.com/v1`
DeepSeek	`https://api.deepseek.com/v1`
智谱 AI	`https://open.bigmodel.cn/api/paas/v4`
Ollama（本地）	`http://localhost:11434/v1`
其他兼容服务	对应的 API 地址

Front-matter 示例#

处理前#

1
---
2
title: 我的博客文章
3
published: 2026-07-01
4
description: 这是一篇示例文章
5
tags:
6
  - 示例
7
---

处理后#

1
---
2
title: 我的博客文章
3
published: 2026-07-01
4
description: 这是一篇示例文章
5
tags:
6
  - 示例
7
ai: 这篇文章是一篇示例文章，演示了 Firefly 主题的基本功能...
8
---

注意事项#

API Key 安全：不要将 API Key 硬编码到代码中，务必使用 .env 文件或平台环境变量
.env 已在 .gitignore 中：本地的 .env 文件不会被提交到 Git 仓库
总结长度：默认生成的总结不超过 100 字（约 300 tokens），保持简洁
幂等性：已有的 ai 字段不会被覆盖，只有缺失时才会生成
错误容忍：单篇文章的 AI 调用失败不会影响其他文章的处理和整体构建

Firefly 代码块示例

Sat, 03 Jan 1970 00:00:00 GMT

在这里，我们将探索如何使用 Expressive Code 展示代码块。提供的示例基于官方文档，您可以参考以获取更多详细信息。

表达性代码#

语法高亮#

语法高亮

常规语法高亮#

1
console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

Terminal window展开收起

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

展开收起

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

my-test-file.js

1
console.log('标题属性示例')

src/content/index.html

1
<div>文件名注释示例</div>

终端框架#

Terminal window

1
echo "此终端框架没有标题"

PowerShell 终端示例

1
Write-Output "这个有标题!"

覆盖框架类型#

1
echo "看，没有框架!"

PowerShell Profile.ps1

1
# 如果不覆盖，这将是一个终端框架
2
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
3
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

标记整行和行范围#

1
// 第1行 - 通过行号定位
2
// 第2行
3
// 第3行
4
// 第4行 - 通过行号定位
5
// 第5行
6
// 第6行
7
// 第7行 - 通过范围 "7-8" 定位
8
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)#

line-markers.js

1
function demo() {
2
  console.log('此行标记为已删除')
3
  // 此行和下一行标记为已插入
4
  console.log('这是第二个插入行')
5

6
  return '此行使用中性默认标记类型'
7
}

为行标记添加标签#

labeled-line-markers.jsx

1
<button
2
  role="button"
3
  {...props}
4
  value={value}
5
  className={buttonClassName}
6
  disabled={disabled}
7
  active={active}
8
>
9
  {children &&
10
    !active &&
11
    (typeof children === 'string' ? <span>{children}</span> : children)}
12
</button>

在单独行上添加长标签#

labeled-line-markers.jsx展开收起

1
<button
2
  role="button"
3
  {...props}
4

5
  value={value}
6
  className={buttonClassName}
7

8
  disabled={disabled}
9
  active={active}
10
>
11

12
  {children &&
13
    !active &&
14
    (typeof children === 'string' ? <span>{children}</span> : children)}
15
</button>

展开收起

使用类似 diff 的语法#

1
此行将标记为已插入
2
此行将标记为已删除
3
这是常规行

1
--- a/README.md
2
+++ b/README.md
3
@@ -1,3 +1,4 @@
4
+this is an actual diff file
5
-all contents will remain unmodified
6
 no whitespace will be removed either

结合语法高亮和类似 diff 的语法#

1
function thisIsJavaScript() {
2
  // 整个块都会以 JavaScript 高亮显示，
3
  // 并且我们仍然可以为其添加 diff 标记！
4
  console.log('要删除的旧代码')
5
  console.log('新的闪亮代码！')
6
}

标记行内的单独文本#

1
function demo() {
2
  // 标记行内的任何给定文本
3
  return '支持给定文本的多个匹配项';
4
}

正则表达式#

1
console.log('单词 yes 和 yep 将被标记。')

转义正斜杠#

Terminal window

1
echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)#

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  // return 语句使用默认标记类型
4
  return true;
5
}

自动换行#

自动换行

为每个块配置自动换行#

1
// 启用换行的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// wrap=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

配置换行的缩进#

1
// preserveIndent 示例（默认启用）
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

可折叠部分#

可折叠部分


5 collapsed lines
1
// 所有这些样板设置代码将被折叠
2
import { someBoilerplateEngine } from '@example/some-boilerplate'
3
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
4

5
const engine = someBoilerplateEngine(evenMoreBoilerplate())
6

7
// 这部分代码默认可见
8
engine.doSomething(1, 2, 3, calcFn)
9

10
function calcFn() {
11
  // 您可以有多个折叠部分
3 collapsed lines
12
  const a = 1
13
  const b = 2
14
  const c = a + b
15

16
  // 这将保持可见
17
  console.log(`计算结果: ${a} + ${b} = ${c}`)
18
  return c
19
}
20

4 collapsed lines
21
// 直到块末尾的所有代码将再次被折叠
22
engine.closeConnection()
23
engine.freeMemory()
24
engine.shutdown({ reason: '示例样板代码结束' })

展开收起

行号#

行号

为每个块显示行号#

1
// 此代码块将显示行号
2
console.log('来自第2行的问候!')
3
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号#

5
console.log('来自第5行的问候!')
6
console.log('我在第6行')

Firefly 布局系统详解

Sat, 03 Jan 1970 00:00:00 GMT

📖 概述#

Firefly 提供了灵活的布局系统，允许您根据内容需求和个人喜好自定义博客的视觉呈现方式。布局系统主要包括侧边栏布局和文章列表布局两个维度，它们相互配合，共同决定了页面的整体结构。

本文将详细介绍 Firefly 的各种布局模式、它们的特点、使用场景，以及不同布局组合的效果。

左侧边栏+列表布局

右侧边栏+网格布局

左侧边栏+三列网格布局

双侧边栏+列表布局

双侧边栏+网格布局

双侧边栏+网格瀑布流布局

一、侧边栏布局系统#

侧边栏是博客页面的重要组成部分，用于展示导航、分类、标签、统计信息等辅助内容。Firefly 支持两种侧边栏布局模式。

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

左侧边栏布局

右侧边栏 (position: “right”)#

右侧边栏布局

特点#

侧边栏固定在页面其中一侧
文章阅读区域体验更佳，更宽敞
更加简约，没有那么紧凑

适用场景#

传统博客风格
强调导航和分类的博客
需要突出用户资料的个人博客
内容为主，辅助信息次之的场景

Tip

可以通过showBothSidebarsOnPostPage配置是否在文章详情页显示双侧边栏

当position为left或right时开启此项后，文章详情页将显示双侧边栏，主页等其他页面保持单侧边栏

适用在只想用单侧栏，但在文章详情页想用对侧栏的目录等组件的场景

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
  showBothSidebarsOnPostPage: true, // 是否在文章详情页显示双侧边栏
5
};

1.2 双侧边栏模式 (position: “both”)#

特点#

左右两侧同时存在侧边栏
主内容区域位于中间
最大化利用屏幕空间
可以展示更多辅助信息
适合宽屏显示器

布局结构#

双侧边栏+列表布局

双侧边栏+网格布局

适用场景#

宽屏桌面端浏览
信息密集型博客
需要展示大量辅助内容
专业性强的技术博客

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "both", // 双侧边栏

二、文章列表布局系统#

文章列表是博客首页和归档页的核心内容，Firefly 提供两种展示方式，并支持多种网格配置。

2.1 列表模式 (defaultMode: “list”)#

特点#

单列纵向排列
显示文章封面图
展示更多文章摘要
适合深度阅读

列表布局结构#

列表模式布局

优点#

✅ 视觉冲击力强，封面图吸引眼球
✅ 可以展示更多文章信息（摘要、标签等）
✅ 适合图片内容丰富的博客
✅ 移动端友好，单列更易阅读
✅ 兼容所有侧边栏配置（单侧、双侧）

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "list", // 列表模式
4
    allowSwitch: true,   // 允许用户切换
5
  },
6
};

2.2 网格模式 (defaultMode: “grid”)#

特点#

自适应列数，根据浏览器宽度自动调整
紧凑布局，信息密度高
适合快速浏览

自适应网格#

网格模式通过 columnWidth 配置卡片的最小宽度（单位 px），浏览器会根据容器可用宽度自动计算能容纳多少列。

网格布局

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "grid",
4
    allowSwitch: true,
5
    grid: {
6
      masonry: true,      // 开启瀑布流
7
      columnWidth: 320,   // 卡片最小宽度(px)，浏览器自动计算列数
8
    },
9
  },
10
};

2.3 瀑布流布局 (Masonry)#

Firefly 的网格模式内置了智能瀑布流布局支持，解决了网格布局中因图文混合文章导致的卡片高度不一致导致的空白问题。

瀑布流布局

智能排版：自动将卡片放置到最短的列，最大化利用垂直空间。
消除空白：通过绝对定位精确计算每个卡片的位置，让卡片紧贴上方卡片，消除垂直方向的空白间隙。
自适应列数：瀑布流同样根据 columnWidth 和容器宽度动态计算列数，无需固定配置。
配置灵活：您可以在 siteConfig.ts 中通过 postListLayout.grid.masonry 选项自由开启或关闭此功能。

三、布局组合指南#

Firefly 允许您自由组合侧边栏和文章列表布局。以下是各种组合的效果说明。

侧边栏模式	文章列表模式	推荐度	适用场景
单侧边栏	列表模式	⭐⭐⭐⭐⭐	摄影、设计、生活类博客，强调图片和沉浸感
单侧边栏	网格模式	⭐⭐⭐⭐⭐	技术、笔记类博客，平衡阅读与检索效率
双侧边栏	列表模式	⭐⭐⭐⭐⭐	需要展示大量侧边栏信息的站点
双侧边栏	网格模式	⭐⭐⭐⭐⭐	极客风格，追求最高信息密度

四、响应式布局行为#

Firefly 的布局系统具有智能的响应式设计，会根据屏幕尺寸自动调整。

为了保证最佳阅读体验，系统会在屏幕变窄时自动调整布局：

网格列数自动减少：网格模式的列数由 columnWidth 和容器宽度自动决定，屏幕越窄列数越少。
列表模式 -> 网格模式：当屏幕宽度小于 380px（超小屏设备）时，列表模式会自动切换为网格模式，以保证卡片内容的可读性。
双侧边栏 -> 单侧边栏：当屏幕宽度小于 1280px 时，会根据tabletSidebar配置显示单侧边栏，隐藏其中一个侧边栏，文章目录导航会切换成浮动目录导航。

五、常见问题#

Q1: 如何调整网格列数？#

A: 通过 columnWidth 配置卡片最小宽度即可。值越小，同等宽度下列数越多；值越大，列数越少。浏览器会自动根据可用宽度计算最佳列数。

六、总结#

Firefly 的布局系统给予了您更大的自由度，您都可以通过简单的配置实现。

我们建议您根据自己的内容类型和目标读者的设备偏好，尝试不同的组合，找到最适合您的博客形态。

文章加密

Fri, 02 Jan 1970 00:00:00 GMT

这是一篇密码保护的示例文章，用于演示文章加密功能。

KaTeX 数学公式示例

Fri, 02 Jan 1970 00:00:00 GMT

本文展示了 Firefly 主题对 KaTeX 数学公式的渲染支持。

行内公式 (Inline)#

行内公式使用单个 $ 符号包裹。

例如：欧拉公式 eiπ+1=0e^{i\pi} + 1 = 0eiπ+1=0 是数学中最优美的公式之一。

质能方程 E=mc2E = mc^2E=mc2 也是家喻户晓。

块级公式 (Block)#

块级公式使用两个 $$ 符号包裹，会居中显示。

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}∫−∞∞e−x2dx=πx=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}x=2a−b±b2−4ac

复杂示例#

矩阵 (Matrices)#

(abcd)(αβγδ)=(aα+bγaβ+bδcα+dγcβ+dδ)\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} \alpha & \beta \\ \gamma & \delta \end{pmatrix} = \begin{pmatrix} a\alpha + b\gamma & a\beta + b\delta \\ c\alpha + d\gamma & c\beta + d\delta \end{pmatrix}(acbd)(αγβδ)=(aα+bγcα+dγaβ+bδcβ+dδ)

极限与求和 (Limits and Sums)#

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2lim⁡x→0sin⁡xx=1\lim_{x \to 0} \frac{\sin x}{x} = 1x→0limxsinx=1

麦克斯韦方程组 (Maxwell’s Equations)#

∇⋅E=ρε0∇⋅B=0∇×E=−∂B∂t∇×B=μ0J+μ0ε0∂E∂t\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0\mathbf{J} + \mu_0\varepsilon_0\frac{\partial \mathbf{E}}{\partial t} \end{aligned}∇⋅E∇⋅B∇×E∇×B=ε0ρ=0=−∂t∂B=μ0J+μ0ε0∂t∂E

化学方程式 (Chemical Equations)#

\ceCH4+2O2−>CO2+2H2O\ce{CH4 + 2O2 -> CO2 + 2H2O}\ceCH4+2O2−>CO2+2H2O

符号	代码	渲染结果
Alpha	`\alpha`	α\alphaα
Beta	`\beta`	β\betaβ
Gamma	`\Gamma`	Γ\GammaΓ
Pi	`\pi`	π\piπ
Infinity	`\infty`	∞\infty∞
Right Arrow	`\rightarrow`	→\rightarrow→
Partial	`\partial`	∂\partial∂

MDX 格式文章示例

Fri, 02 Jan 1970 00:00:00 GMT

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

使用组件#

这是一个图标组件：

1
import { Icon } from 'astro-icon/components'
2

3
<div class="flex items-center gap-2 my-4">
4
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
5
  <span>火箭发射！</span>
6
</div>

火箭发射！

使用 JSX#

你也可以直接写 HTML/JSX：

1
<div className="p-4 bg-blue-100 dark:bg-blue-900 rounded-lg my-4">
2
  这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。
3
</div>

这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。

简单的变量导出#

1
export const year = new Date().getFullYear()
2

3
今年是 {year} 年。

今年是 2026 年。

更多信息，请查看 MDX 文档

Markdown 扩展功能

Thu, 01 Jan 1970 00:00:00 GMT

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

展开收起

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

展开收起

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

展开收起

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

展开收起

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

示例图片一

示例图片二

基本语法

1
[grid]
2
![示例图片一](./images/firefly1.avif)
3
![示例图片二](./images/firefly2.avif)
4
![示例图片二](./images/firefly3.avif)
5
[/grid]

Markdown Mermaid 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、甘特图、类图和状态图。

流程图示例#

流程图非常适合表示流程或算法步骤。

graph TD A[开始] --> B{条件检查} B -->|是| C[处理步骤 1] B -->|否| D[处理步骤 2] C --> E[子过程] D --> E subgraph E [子过程详情] E1[子步骤 1] --> E2[子步骤 2] E2 --> E3[子步骤 3] end E --> F{另一个决策} F -->|选项 1| G[结果 1] F -->|选项 2| H[结果 2] F -->|选项 3| I[结果 3] G --> J[结束] H --> J I --> J

时序图示例#

时序图显示对象之间随时间的交互。

sequenceDiagram participant User as 用户 participant WebApp as 网页应用 participant Server as 服务器 participant Database as 数据库 User->>WebApp: 提交登录请求 WebApp->>Server: 发送认证请求 Server->>Database: 查询用户凭据 Database-->>Server: 返回用户数据 Server-->>WebApp: 返回认证结果 alt 认证成功 WebApp->>User: 显示欢迎页面 WebApp->>Server: 请求用户数据 Server->>Database: 获取用户偏好 Database-->>Server: 返回偏好设置 Server-->>WebApp: 返回用户数据 WebApp->>User: 加载个性化界面 else 认证失败 WebApp->>User: 显示错误消息 WebApp->>User: 提示重新输入 end

甘特图示例#

甘特图非常适合显示项目进度和时间线。

gantt title 网站开发项目时间线 dateFormat YYYY-MM-DD axisFormat %m/%d section 设计阶段需求分析 :a1, 2023-10-01, 7d UI设计 :a2, after a1, 10d 原型创建 :a3, after a2, 5d section 开发阶段前端开发 :b1, 2023-10-20, 15d 后端开发 :b2, after a2, 18d 数据库设计 :b3, after a1, 12d section 测试阶段单元测试 :c1, after b1, 8d 集成测试 :c2, after b2, 10d 用户验收测试 :c3, after c2, 7d section 部署生产环境部署 :d1, after c3, 3d 发布 :milestone, after d1, 0d

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

classDiagram class User { +String username +String password +String email +Boolean active +login() +logout() +updateProfile() } class Article { +String title +String content +Date publishDate +Boolean published +publish() +edit() +delete() } class Comment { +String content +Date commentDate +addComment() +deleteComment() } class Category { +String name +String description +addArticle() +removeArticle() } User "1" -- "*" Article : 写作 User "1" -- "*" Comment : 发表 Article "1" -- "*" Comment : 拥有 Article "1" -- "*" Category : 属于

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

stateDiagram-v2 [*] --> 草稿草稿 --> 审核中 : 提交审核中 --> 草稿 : 拒绝审核中 --> 已批准 : 批准已批准 --> 已发布 : 发布已发布 --> 已归档 : 归档已发布 --> 草稿 : 撤回 state 已发布 { [*] --> 活跃活跃 --> 隐藏 : 临时隐藏隐藏 --> 活跃 : 恢复活跃 --> [*] 隐藏 --> [*] } 已归档 --> [*]

饼图示例#

饼图非常适合显示比例和百分比数据。

pie title 网站流量来源分析 "搜索引擎" : 45.6 "直接访问" : 30.1 "社交媒体" : 15.3 "推荐链接" : 6.4 "其他来源" : 2.6

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了如何使用流程图、时序图、甘特图、类图、状态图和饼图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。Mermaid 会自动将这些描述转换为美观的可视化图表。

尝试在您的下一篇技术博客文章或项目文档中使用 Mermaid 图表 - 它们将使您的内容更加专业且更易理解！

Markdown PlantUML 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

活动图示例#

状态图示例#

用例图示例#

组件图示例#

部署图示例#

ER 图示例#

时序图示例（登录与刷新令牌）#

C4 风格容器图示例#

Markdown 教程

Thu, 01 Jan 1970 00:00:00 GMT

这是一个展示如何编写 Markdown 文件的示例。本文档汇总了核心语法与常见扩展（GFM）。

块级元素
- 段落与换行
- 标题
- 引用
- 列表
- 代码块
- 分割线
- 表格
内联元素
- 链接
- 强调
- 行内代码
- 图片
- 删除线
杂项
- 自动链接
- 反斜杠转义
内联 HTML

块级元素#

段落与换行#

段落#

HTML 标签：<p>

使用一个或多个空行分隔段落。（仅包含空格或制表符的行也视为空行。）

代码：

1
This will be
2
inline.
3

4
This is second paragraph.

预览：

This will be inline.

This is second paragraph.

换行#

HTML 标签：<br />

在行末添加两个或更多空格来产生换行。

代码：

1
This will be not
2
inline.

预览：

This will be not
inline.

标题#

Markdown 支持两种标题样式：Setext 与 atx。

Setext#

HTML 标签：<h1>，<h2>

使用等号 (=) 表示 <h1>、使用短横线 (-) 表示 <h2>，数量不限，作为“下划线”。

代码：

1
This is an H1
2
=============
3
This is an H2
4
-------------

预览：

This is an H1#

This is an H2#

atx#

HTML 标签：<h1>，<h2>，<h3>，<h4>，<h5>，<h6>

在行首使用 1-6 个井号 (#)，对应 <h1> 至 <h6>。

代码：

1
# This is an H1
2
## This is an H2
3
###### This is an H6

预览：

This is an H1#

This is an H2#

This is an H6#

可选：你可以在行尾“闭合” atx 标题。末尾的井号数量不必与开头一致。

代码：

1
# This is an H1 #
2
## This is an H2 ##
3
### This is an H3 ######

预览：

This is an H1#

This is an H2#

This is an H3#

引用#

HTML 标签：<blockquote>

Markdown 使用邮件风格的 > 作为引用符号。若手动换行并在每行前加 >，显示效果最佳。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4
>
5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
> id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown 允许“偷懒”：在一个硬换行段落中，只在第一行前加 > 即可。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4

5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

引用可以嵌套（引用中的引用），通过增加 > 层级实现。

代码：

1
> This is the first level of quoting.
2
>
3
> > This is nested blockquote.
4
>
5
> Back to the first level.

预览：

This is the first level of quoting.
This is nested blockquote.
Back to the first level.

引用内可包含其他 Markdown 元素，包括标题、列表与代码块。

代码：

1
> ## This is a header.
2
>
3
> 1.   This is the first list item.
4
> 2.   This is the second list item.
5
>
6
> Here's some example code:
7
>
8
>     return shell_exec("echo $input | $markdown_script");

预览：

This is a header.#

This is the first list item.

This is the second list item.

Here’s some example code:
1
return shell_exec("echo $input | $markdown_script");

列表#

Markdown 支持有序（数字）与无序（圆点）列表。

无序列表#

HTML 标签：<ul>

无序列表可使用 星号 (*)、加号 (+) 或 短横线 (-)。

代码：

1
*   Red
2
*   Green
3
*   Blue

预览：

Red
Green
Blue

等价于：

代码：

1
+   Red
2
+   Green
3
+   Blue

或者：

代码：

1
-   Red
2
-   Green
3
-   Blue

有序列表#

HTML 标签：<ol>

有序列表使用数字加英文句点：

代码：

1
1.  Bird
2
2.  McHale
3
3.  Parish

预览：

Bird
McHale
Parish

注意：像下面这样可能会“意外触发”有序列表：

代码：

1
1986. What a great season.

预览：

What a great season.

你可以用反斜杠转义 (\) 句点：

代码：

1
1986\. What a great season.

预览：

1986. What a great season.

列表中的缩进内容#

列表项里的引用#

在列表项内放置引用，需要将 > 符号整体缩进：

代码：

1
*   A list item with a blockquote:
2

3
    > This is a blockquote
4
    > inside a list item.

预览：

A list item with a blockquote:

This is a blockquote inside a list item.

列表项里的代码块#

在列表项内放置代码块，需要缩进两层——8 个空格或两个 Tab：

代码：

1
*   A list item with a code block:
2

3
        <code goes here>

预览：

A list item with a code block:
```
1
<code goes here>
```

嵌套列表#

代码：

1
* A
2
  * A1
3
  * A2
4
* B
5
* C

预览：

A
- A1
- A2
B
C

代码块#

HTML 标签：<pre>

将代码块中的每行缩进至少4 个空格或1 个制表符。

代码：

1
This is a normal paragraph:
2

3
    This is a code block.

预览：

This is a normal paragraph:

1
This is a code block.

代码块会一直持续，直到遇到未缩进的行（或文末）。

在代码块内，与号 (&) 和尖括号 (< >) 会自动转为 HTML 实体。

代码：

1
    <div class="footer">
2
        &copy; 2004 Foo Corporation
3
    </div>

预览：

1
<div class="footer">
2
    &copy; 2004 Foo Corporation
3
</div>

下文的“围栏代码块”和“语法高亮”属于扩展语法，你也可以用它们来书写代码块。

围栏代码块#

使用成对的反引号围起来（如下所示），就不需要四空格缩进了。

代码：

1
Here's an example:
2

3
```
4
function test() {
5
  console.log("notice the blank line before this function?");
6
}
7
```

预览：

Here’s an example:

1
function test() {
2
  console.log("notice the blank line before this function?");
3
}

语法高亮#

在围栏代码块后添加可选的语言标识，即可启用语法高亮（参见支持语言列表）。

代码：

1
```ruby
2
require 'redcarpet'
3
markdown = Redcarpet.new("Hello World!")
4
puts markdown.to_html
5
```

预览：

1
require 'redcarpet'
2
markdown = Redcarpet.new("Hello World!")
3
puts markdown.to_html

分割线（水平线）#

HTML 标签：<hr /> 一行中放置三个或以上的短横线 (-)、星号 (*) 或下划线 (_)。符号之间允许有空格。

代码：

1
* * *
2
***
3
*****
4
- - -
5
---------------------------------------
6
___

预览：

表格#

HTML 标签：<table>

这是扩展语法。

用竖线 (|) 分隔列，用短横线 (-) 分隔表头，使用冒号 (:) 指定对齐方式。

两侧的竖线 (|) 与对齐可选。用于表头分隔时，每列至少需要 3 个短横线。

代码：

1
| Left | Center | Right |
2
|:-----|:------:|------:|
3
|aaa   |bbb     |ccc    |
4
|ddd   |eee     |fff    |
5

6
 A | B
7
---|---
8
123|456
9

10

11
A |B
12
--|--
13
12|45

预览：

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

内联元素#

链接#

HTML 标签：<a>

Markdown 支持两种链接样式：行内链接与引用式链接。

行内链接#

行内链接格式：[文本](URL "标题")

标题可选。

代码：

1
This is [an example](http://example.com/ "Title") inline link.
2

3
[This link](http://example.net/) has no title attribute.

预览：

This is an example inline link.

This link has no title attribute.

如果引用同一站点的本地资源，可以使用相对路径：

代码：

1
See my [About](/about/) page for details.

预览：

See my About page for details.

引用式链接#

可以预定义链接引用。定义格式：[id]: URL "标题"

标题同样可选。引用时使用：[文本][id]

代码：

1
[id]: http://example.com/  "Optional Title Here"
2
This is [an example][id] reference-style link.

预览：

This is an example reference-style link.

说明：

方括号中包含链接标识（不区分大小写，可在左侧缩进最多三格空格）；
随后是冒号；
再跟一个或多个空格（或 tab）；
然后是链接 URL；
URL 可选地用尖括号包裹；
可选地跟随标题属性，用引号或圆括号包裹。

以下三种定义等价：

代码：

1
[foo]: http://example.com/  "Optional Title Here"
2
[foo]: http://example.com/  'Optional Title Here'
3
[foo]: http://example.com/  (Optional Title Here)
4
[foo]: <http://example.com/>  "Optional Title Here"

如果使用空的方括号，则链接文本本身会作为名称。

代码：

1
[Google]: http://google.com/
2
[Google][]

预览：

Google

强调#

HTML 标签：<em>，<strong>

Markdown 使用 星号 (*) 或 下划线 (_) 表示强调。一个分隔符对应 <em>；两个分隔符对应 <strong>。

代码：

1
*single asterisks*
2

3
_single underscores_
4

5
**double asterisks**
6

7
__double underscores__

预览：

single asterisks

single underscores

double asterisks

double underscores

但如果两侧有空格，则会被视作普通字符而非强调语法。

你可以使用反斜杠进行转义：

代码：

1
\*this text is surrounded by literal asterisks\*

预览：

*this text is surrounded by literal asterisks*

行内代码#

HTML 标签：<code>

用反引号 (`) 包裹。

代码：

1
Use the `printf()` function.

预览：

Use the printf() function.

若行内代码中需要包含反引号字符，可使用多重反引号作为定界符：

代码：

1
``There is a literal backtick (`) here.``

预览：

There is a literal backtick (`) here.

行内代码两侧的定界符允许包含空格（开头一个、结尾一个），方便在代码起始或结尾放置反引号字符：

代码：

1
A single backtick in a code span: `` ` ``
2

3
A backtick-delimited string in a code span: `` `foo` ``

预览：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

图片#

HTML 标签：<img />

Markdown 的图片语法与链接类似，支持行内与引用两种方式。

行内图片#

行内图片语法：![替代文本](URL "标题")

标题可选。

代码：

1
![Alt text](/path/to/img.jpg)
2

3
![Alt text](/path/to/img.jpg "Optional title")

预览：

Alt text

说明：

一个感叹号 !；
后接方括号，放置图片的替代文本；
再接圆括号，内含图片 URL/路径，及可选的标题（引号包裹）。

引用式图片#

引用式图片语法：![替代文本][id]

代码：

1
[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
2
![Alt text][img id]

预览：

Alt text

删除线#

HTML 标签：<del>

这是扩展语法。

GFM 增加了删除线语法。

代码：

1
~~Mistaken text.~~

预览：

Mistaken text.

杂项#

自动链接#

Markdown 支持一种便捷写法来创建“自动链接”（URL 与邮箱地址）：只需用尖括号将其包住即可。

代码：

1
<http://example.com/>
2

3
<address@example.com>

预览：

http://example.com/

address@example.com

GFM 会自动识别标准 URL 并转换为链接。

代码：

1
https://github.com/emn178/markdown

预览：

https://github.com/emn178/markdown

反斜杠转义#

Markdown 允许使用反斜杠来转义那些本用于 Markdown 语法的特殊字符，使其按字面显示。

代码：

1
\*literal asterisks\*

预览：

*literal asterisks*

以下字符可通过反斜杠转义以按字面量输出：

Code:

1
\   backslash
2
`   backtick
3
*   asterisk
4
_   underscore
5
{}  curly braces
6
[]  square brackets
7
()  parentheses
8
#   hash mark
9
+   plus sign
10
-   minus sign (hyphen)
11
.   dot
12
!   exclamation mark

内联 HTML#

对于 Markdown 语法未覆盖的标记，直接使用原生 HTML 即可。无需特别声明从 Markdown 切换到 HTML，直接写标签就行。

代码：

1
This is a regular paragraph.
2

3
<table>
4
    <tr>
5
        <td>Foo</td>
6
    </tr>
7
</table>
8

9
This is another regular paragraph.

预览：

This is a regular paragraph.

Foo

This is another regular paragraph.

请注意：在块级 HTML 标签内不会处理 Markdown 语法。

与块级标签不同，在行内级标签内会处理 Markdown 语法。

代码：

1
<span>**Work**</span>
2

3
<div>
4
    **No Work**
5
</div>

预览：

Work

**No Work**

***

在文章中嵌入视频

Thu, 01 Jan 1970 00:00:00 GMT

只需从 YouTube 或其他平台复制嵌入代码，然后将其粘贴到 markdown 文件中。

1
---
2
title: 在文章中嵌入视频
3
published: 2023-10-19
4
// ...
5
---
6

7
<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

Ember

关于我为了体检买了一个眼镜的事

关于我为了体检买了一个眼镜的事#

前言#

配镜过程#

问题显现：严重的畸变#

球面镜片 vs 非球面镜片#

我的教训与建议#

总结#

Firefly 一款清新美观的 Astro 博客主题模板

🌟 项目概述#

🚀 技术架构#

📖 配置说明#

Firefly 简单使用指南

文章的 Front-matter#

文章文件的放置位置#

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 使用示例#

示例 1：使用文件名作为 URL#

示例 2：自定义 Slug#

示例 3：其他语言文件名使用Slug#

Slug 使用建议#

注意事项#

Firefly 归档页面美化

📖 概述#

📂 文件清单#

修改文件（2 个）#

新增文件（0 个）#

未改动部分#

🛠️ 方法 & 关键代码#

1. archive.astro：去掉双层卡片框#

2. 颜色变量化（去掉强制黑白）#

3. 整体排版（宽松化）#

4. 修复 hover 色块溢出#

5. 修复虚线断裂#

6. 整体组件结构对照#

✅ 验收结果#

💡 关键设计点回顾#

Firefly 分类页面美化

📖 概述#

📂 文件清单#

新增文件（5 个）#

修改文件（9 个）#

🛠️ 方法 & 关键代码#

1. 数据层：标签共现图谱算法#

2. 通用标题组件 PageTitle.astro#

3. CategoryRose 玫瑰图#

4. TagGraph 力导向图#

5. 路由页面（薄壳）#

6. 样式#

7. i18n 国际化#

✅ 验收结果#

💡 关键设计点回顾#

给 Firefly 主题加上 AI 总结功能

功能介绍#

功能特性#

修改的文件清单#

详细说明#

1. scripts/generate-ai-summary.js（新增）#

2. src/components/features/AiSummary.astro（新增）#

3. src/content.config.ts（修改）#

4. src/pages/posts/[...slug].astro（修改）#

5. package.json（修改）#

6. .env.example（新增）#

用户接入指南#

前提条件#

步骤一：配置 API Key#

方式一：本地开发使用 .env 文件#

方式二：CI/CD 部署使用环境变量（推荐）#

步骤二：运行脚本#

手动运行#

构建时自动运行#

步骤三：验证效果#

常用操作#

预览模式（不实际调用 AI）#

强制重新生成所有总结#

重新生成单篇文章的总结#

不配置 API Key 会怎样？#

兼容的 AI 服务商#

2. 通用标题组件 `PageTitle.astro`#

1. `scripts/generate-ai-summary.js`（新增）#

2. `src/components/features/AiSummary.astro`（新增）#

3. `src/content.config.ts`（修改）#

4. `src/pages/posts/[...slug].astro`（修改）#

5. `package.json`（修改）#

6. `.env.example`（新增）#

方式一：本地开发使用 `.env` 文件#