Astro Gyoza 内容标签使用指南

Astro Gyoza 内容标签使用指南

# Astro # Gyoza # MDX # KaTeX # Markdown
茗辰原
Published date:
6 min read
编辑此文

Gyoza 主题内置了丰富的排版增强功能，远超标准 Markdown。本文档完整介绍所有功能，涵盖内联标签、数学公式、代码块、表格、MDX 组件等，适配亮色/暗黑模式。

文字特效

下划线

使用 ++文字++ 包裹即可生成红色下划线：

这是一段 含有下划线的文字，效果明显。

波浪下划线

在 <ins> 标签上加 class="wavy" 实现波浪线：

这是一段 含有波浪下划线的文字，像涟漪一样。

虚点下划线

在 <ins> 标签上加 class="dot" 实现虚点线：

这是一段 含有虚点下划线的文字，精致细腻。

彩色下划线

<ins> 支持多种颜色变体，通过 class 控制：

主要色下划线　 成功绿下划线　 警告黄下划线　 危险红下划线　 信息蓝下划线

荧光高亮

使用 ==高亮文字== 包裹产生荧光笔效果：

这是一段 荧光高亮 的文字，在亮色模式下为黄色，暗黑模式下为深琥珀色，护眼醒目。

上标与下标

使用 ^上标^ 和 ~下标~ 语法：

水的化学式是 H2O，地球表面积约为 510百万平方公里。

键盘键

使用 <kbd> 标签模拟键盘按键的 3D 视觉效果：

使用快捷键 Ctrl + C 复制，Ctrl + V 粘贴。

黑幕（Spoiler）

使用 <span class="spoiler"> 隐藏敏感内容，鼠标悬停才显示：

下面这句话包含 这是隐藏的黑幕内容，鼠标滑过即可查看 黑幕效果。

模糊黑幕

加 blur 类实现模糊效果，鼠标悬停变清晰：

这段文字默认模糊处理，悬停后变清晰可见

彩色文字

使用 <span class="c-颜色名"> 快速变换字体颜色：

类名效果
c-red红色文字
c-pink粉色文字
c-orange橙色文字
c-yellow黄色文字
c-green绿色文字
c-aqua青色文字
c-blue蓝色文字
c-purple紫色文字
c-grey灰色文字

组合使用示例：

红色、蓝色 与 紫色 搭配使用，突出重点信息。

七彩渐变文字

使用 <span class="rainbow"> 让文字流动变色：

这是一段七彩渐变的动态文字，流光溢彩。

内联标签块

使用 <span class="label"> 配合颜色变体生成内联标签：

default　 primary　 success　 info　 warning　 danger

也可以与彩色文字组合：

主要操作　 ✓ 已完成　 ✗ 已失败

KaTeX 数学公式

主题通过 remark-math + rehype-katex 支持 LaTeX 数学公式渲染。

行内公式

用单个 $ 包裹：质能方程 E=mc2E = mc^2 是物理学中最著名的公式。

块级公式

用双 $$ 包裹：

∫−∞∞e−x2 dx=π\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}

多行对齐公式：

∇⋅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}

矩阵公式

(abcd)(xy)=(ef)\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} e \\ f \end{pmatrix}

KaTeX 支持大部分 LaTeX 数学环境，包括 \begin{aligned}、\begin{pmatrix}、\sum、\int 等。如果公式不渲染，请检查 LaTeX 语法是否正确。

代码块进阶

代码语言

在代码块开头指定语言即可激活语法高亮：

const greeting: string = 'Hello, Gyoza!'
console.log(greeting)

行高亮

使用花括号标记需要高亮的行：

```typescript {2,4-5}
function fibonacci(n: number): number {
  if (n <= 1) return n // 高亮行
  let a = 0,
    b = 1
  for (let i = 2; i <= n; i++) {
    // 高亮区域
    const c = a + b
    a = b
    b = c
  }
  return b
}
```

文件标题

使用 title 参数添加文件标签：

```typescript title="src/utils/math.ts"
export const add = (a: number, b: number): number => a + b
```

行号

代码块默认显示行号，方便引用：

// 第 1 行
const a = 1
// 第 2 行
const b = 2
// 第 3 行
console.log(a + b)

表格增强

主题通过 rehypeTableBlock 插件对表格进行美化：

功能语法说明
加粗**文字**强调文本
斜体*文字*次要强调
代码`code`行内代码
删除线~~文字~~标记删除
链接[文本](url)超链接
图片![alt](src)插入图片

表格支持左右对齐：

左对齐居中对齐右对齐
内容内容内容
很长很长的内容居中靠右

脚注

用于添加注释或参考资料：

这是一个带脚注的句子。1 这是另一个脚注引用。2

图片画廊

Gyoza 主题内置了相册系统。在 src/content/galleries/ 下创建目录并放置图片即可。

在文章中引用图片：

![图片描述](image-name.webp)

图片会自动包裹在 <figure> 标签中，支持懒加载和点击放大预览（lightbox）。

MDX 组件

使用 .mdx 扩展名即可在文章中直接导入 Astro 或 React 组件。

LinkCard

在 .mdx 文件顶部导入 LinkCard 生成友链风格的链接卡片：

import LinkCard from '@/components/LinkCard.astro'

<LinkCard
  title="GitHub"
  url="https://github.com"
  desc="全球最大的代码托管平台"
  image="https://github.githubassets.com/favicons/favicon.svg"
/>

<LinkCard title="Astro" url="https://astro.build" desc="现代化的 Web 框架" />

Highlight

用于强调关键文字的 Astro 组件：

<Highlight>这段文字会被高亮标记</Highlight>

AnimatedSignature

在文章末尾添加个性签名动画：

import { AnimatedSignature } from '@/components/AnimatedSignature.tsx'

<AnimatedSignature />

科技感文字特效

主题内置一批科技感排版特效，配合既有特效使用：

霓虹辉光文字

使用 <span class="neon"> 生成霓虹灯管效果，支持 4 种颜色变体：

CYAN 青色霓虹　 PINK 粉色霓虹　 BLUE 蓝色霓虹　 GREEN 绿色霓虹

故障抖动文字

使用 <span class="glitch" data-text="原文"> 生成赛博故障效果（data-text 必须与内容一致）：

SYSTEM BREACH

打字机光标

在文本后追加闪烁光标：

正在初始化系统…

扫描线

CRT 扫描高亮，适合强调关键词：

扫描中…

科技渐变文字

流动渐变 + 辉光，随主题强调色变化：

TECH GRADIENT 科技渐变

既有特效增强

总结

所有功能一览：

功能语法说明
下划线++文字++红色下划线
波浪线<ins class="wavy">文字</ins>波浪装饰下划线
虚点线<ins class="dot">文字</ins>虚点装饰下划线
彩色下划线<ins class="primary">文字</ins>5 种颜色
荧光高亮==文字==荧光笔效果
上标^文字^上角标
下标~文字~下角标
彩色文字<span class="c-red">文字</span>9 种颜色可选
七彩文字<span class="rainbow">文字</span>动态渐变色
键盘键<kbd>Ctrl</kbd>3D 按键效果
黑幕<span class="spoiler">文字</span>悬停显示
模糊黑幕<span class="spoiler blur">文字</span>悬停变清晰
内联标签<span class="label primary">文字</span>6 种颜色变体
KaTeX 公式$公式$ / $$公式$$LaTeX 数学公式
代码行高亮```ts {1,3-5}标记指定行
代码文件标题```ts title="file.ts"显示文件名
表格增强标准 Markdown 表格自动美化样式
脚注[^1] / [^1]: 内容页面底部注释
链接卡片<LinkCard>仅 .mdx 文章可用

Fancybox 图片灯箱

主题集成了 Fancybox 作为全站唯一图片预览组件，文章图片和相册图片统一使用 Fancybox 灯箱。

自动生效

所有文章中的图片 自动启用 灯箱功能，无需额外配置。点击图片会弹出全屏预览，支持：

图片分组逻辑

图片描述文字

使用 Markdown 图片语法时，alt 文字会显示在图片下方居中：

![这是一张示例图片的描述文字](image.webp)

效果：图片下方会显示「这是一张示例图片的描述文字」作为图注。

相册页使用

相册页 <a> 标签会自动添加 data-fancybox="gallery" 属性，点击图片弹出灯箱而非跳转直链：

<a href="原图.webp" data-fancybox="gallery" data-caption="图片描述">
  <img src="缩略图.webp" loading="lazy" alt="图片描述" />
</a>

LivePhoto 实况照片

主题集成了 HeoLivePhoto，支持在文章中嵌入实况照片（Live Photo）。

使用方式

1. 单文件 .pvt 格式（推荐）

将 .pvt 文件放在 public/ 目录下，然后在文章中使用普通 img 标签：

![实况照片](/photo.pvt)

脚本会自动：

2. 封面 + 视频分离

如果封面图和视频是分开的文件：

<img src="cover.jpg" data-live-video="motion.mp4" alt="实况照片" />

3. Apple 官方写法（LivePhotosKit 风格）

<div
  data-live-photo
  data-photo-src="cover.jpg"
  data-video-src="motion.mp4"
  style="width: 320px; height: 320px"
></div>

参数说明

属性说明默认值
src.pvt 文件路径或封面图路径-
data-live-video视频文件路径（MP4/MOV）-
data-live-loop是否循环播放false
data-live-badge左上徽标文字，false 隐藏自动（中文「实况」/英文「LIVE」）
data-live-pvt.pvt 文件路径（替代 src）-

生成 .pvt 文件

访问 洪绘Live图 在线合成：

注意事项

双评论系统（Twikoo + Waline）

主题同时集成了 Twikoo 与 Waline 两套评论系统，文章页评论区右上角提供胶囊分段切换器，两套系统共享同一个评论区块，一次只显示一个。

视觉效果

评论区块是一整块毛玻璃卡片：

记忆用户选择

切换结果写入 localStorage（键名 mcy-comment-driver）。下次打开任意文章页时，自动使用上次选择的评论系统，无需重复切换。未选择过则默认 Twikoo。

懒加载

两套系统都按需加载，只有真的切到对应系统才下载，首页与无评论区页面零成本：

引擎来源体积（gzip）
TwikoojsDelivr CDN（unpkg 备源）约 206 KB
Waline/waline/（本地）约 90 KB

加载过程中评论区内显示 loading 圈与文字；脚本加载失败（例如被浏览器跟踪防护拦截）时给出可读提示，不会白屏。

来源策略：Twikoo 走官方 CDN（jsDelivr 主源 + unpkg 备源），加载失败自动切换下一个源，两个源都失败才提示用户；Waline 仍本地化到 public/waline/，同源直连。

为什么 Twikoo 改用 CDN：之前本地那份是被 Prettier 重排过的（官方包 772 KB 被格式化膨胀到 1.63 MB），而且本地副本与云端云函数的版本容易漂移；CDN 上锁死 twikoo@1.7.19，与云函数版本完全一致。代价是它属于第三方资源，可能被浏览器跟踪防护拦截，所以保留了二级回退源 + 失败提示。

Swup 无刷新切页

Swup 只替换 <main>、不重建 <body>，因此评论初始化逻辑统一放在 Layout.astro 的 body 级常驻脚本（单例），而不是写在评论组件的 inline 脚本里：

Waline 配置要点

Twikoo 评论视觉：两行评论头 + 流光身份标签

Twikoo 的默认样式是 Element UI 那一套（灰底细边框、蓝色按钮、标签贴着昵称挤在一行）。本站在 src/components/comment/Twikoo.astro 里做了一层作用域覆盖，改造成暗黑液态玻璃风格。

两行评论头

行内容
第一行头像 + 昵称 + 身份标签 + 发布时间
第二行点赞 / 踩 / 回复 按钮（与第一行用细线隔开）

靠 flex-wrap + flex-basis: 100% 实现，不改任何 Twikoo 的渲染逻辑；子回复嵌套复用同一套规则，自动也是两行，左侧缩进从 1rem 收窄到 0.55rem 并保留 accent 竖线。

昵称：强调色 + 波浪下划线

身份标签：实心渐变药丸 + 探出的徽标

标签不是描边小字，而是实心渐变药丸 + 深色文字，并有一枚 SVG 徽标从药丸上沿探出来：

标签触发条件配色徽标
站长MASTER_TAG跟随随机强调色的流光渐变星形
置顶COMMENT_TOP_TAG固定红橙渐变图钉
待审核COMMENT_REVIEWING_TAG固定琥珀渐变时钟
邻居/备用tk-tag-blue固定蓝紫渐变皇冠

流光做法：两层背景叠在一起——上层是斜向白色高光条（background-size: 220% 100%），下层是纯色渐变（100% 100%），共用一条 keyframe 只移动 background-position。下层尺寸是 100%，位置移动对它不可见，于是只有高光在扫，颜色本身不漂移：

.tag {
  background:
    linear-gradient(115deg, transparent 35%, rgba(255, 255, 255, 0.35) 50%, transparent 65%),
    linear-gradient(115deg, #5ab8ff, #2f86ff 55%, #6d5efc);
  background-size:
    220% 100%,
    100% 100%;
  animation: sweep 3.4s linear infinite;
}
@keyframes sweep {
  0% {
    background-position: 200% 0;
  }
  100% {
    background-position: -200% 0;
  }
}

徽标是 CSS ::before 画的 data-URI SVG（top: -0.85em + overflow: visible），Twikoo 官方包里没有这些图标。SVG 路径写成逗号分隔的无空格形式（坐标、viewBox='0,0,24,24'），避免被压缩器改写编码。

点赞 / 踩 / 回复：强调色药丸

为什么样式写在 [data-engine='twikoo'] 而不是 #twikoo

Twikoo 用 Vue 2 的 $mount('#twikoo') 初始化，而Vue 2 的 $mount(el) 会把目标节点整个替换掉——替换后 #twikoo 这个 id 连同 class 一起消失，所以：

  1. 容器多包一层永不替换的壳 <div data-engine="twikoo"><div id="twikoo"></div></div>
  2. 显隐控制与幂等标记（data-ready）都打在外壳上
  3. CSS 选择器一律以 [data-engine='twikoo'] 作用域

另外 Twikoo 的 CSS 不是文件，是脚本运行时注入 <body> 的，会排在本站样式后面，因此覆盖时必须带 !important。

评论区内适配

Footnotes

  1. 这是脚注的内容，会显示在页面底部。 ↩

  2. 多个脚注会自动编号，底部按顺序排列。 ↩

Share
Previous
开源某克自动签到领取免费空间项目
Next
利用AI从Hexo迁移到Astro
}