本文既是 matery 主题交互视觉功能的完整使用教程,也是 自动化测试靶场。覆盖:代码块增强、图片灯箱、打字机、页面特效、繁简转换、进度条、回顶、打赏、打印。
1. 代码块增强
用途
代码块显示语言标签、提供复制/展开/折叠/全屏操作,超长代码自动限高。
配置(主题 _config.yml 的 code 块)
code:
# 代码语言标签
language: { enable: true }
# 复制按钮
copy_btn: true
# 展开/折叠按钮(超长代码)
show_full: true
# 代码块最大高度(超过则折叠)
height_limit: 450用法
标准 Markdown 代码块即可(自动增强):
```bash
# Bash 示例
echo "Hello Matery"
```示例(多语言)
# Bash:系统操作
sudo apt update
docker compose up -d
systemctl status nginx# Python:数据处理
def process(data):
"""处理数据并返回结果"""
result = [x * 2 for x in data if x > 0]
return result
print(process([1, -2, 3, 4]))// JavaScript:异步请求
async function fetchData(url) {
const response = await fetch(url);
const data = await response.json();
console.log("数据:", data);
}# YAML:配置文件
server:
host: 0.0.0.0
port: 8080
workers: 4# Python:超长代码示例(超过 450px 高度阈值,触发"展开"按钮)
# 模拟一个简单的博客文章处理流水线
import hashlib
import json
import re
from collections import Counter
from datetime import datetime
from pathlib import Path
def read_posts(directory):
"""读取目录下所有 Markdown 文章"""
posts = []
for path in Path(directory).glob("*.md"):
posts.append(path.read_text(encoding="utf-8"))
return posts
def extract_front_matter(content):
"""提取 Front-Matter 元数据"""
match = re.match(r"^---\n(.*?)\n---\n", content, re.DOTALL)
if not match:
return {}
meta = {}
for line in match.group(1).splitlines():
if ":" in line:
key, value = line.split(":", 1)
meta[key.strip()] = value.strip()
return meta
def analyze_posts(directory):
"""主分析流程:统计词频、生成摘要、计算字数"""
all_words = Counter()
for content in read_posts(directory):
meta = extract_front_matter(content)
body = re.sub(r"^---\n.*?\n---\n", "", content, flags=re.DOTALL)
text = re.sub(r"[#*`>\[\]()]", "", body)
words = re.findall(r"[\u4e00-\u9fa5]|[a-zA-Z]+", text)
all_words.update(words)
word_count = len(words)
summary = " ".join(words[:20])
checksum = hashlib.md5(content.encode()).hexdigest()[:8]
print(f"{meta.get('title', 'untitled')} | {word_count}字 | {checksum}")
print(f" 摘要: {summary}...")
print(f"\n共分析 {len(all_words)} 个词汇")
return all_words
if __name__ == "__main__":
result = analyze_posts("content/posts")
top_words = result.most_common(10)
print("Top 10 高频词:")
for word, count in top_words:
print(f" {word}: {count}")实现效果
- 右上角语言标签(bash/python/js/yaml)
- 复制按钮(点击复制代码)
- 超长代码显示"展开"按钮
- 全屏按钮(代码大屏查看)
测试断言:页面含
code-area标记(≥4 个代码块)。
2. 图片灯箱 lightGallery
用途
文章图片点击放大浏览,支持缩放/翻页/下载。
配置(主题 _config.yml)
# 文章图片自动被 articleInit 包装为 .img-item
image_zoom:
enable: true用法
普通 Markdown 图片即可(自动增强):
示例


实现效果
- 图片 hover 阴影 + 边框
- 点击弹出灯箱(全屏 + 缩放 + 翻页)
- 支持字幕(alt/title 显示)
测试断言:图片被包装为
.img-item,点击弹出.lg-outer。
3. 打字机 Typed
用途
Banner 副标题/文章标题逐字打字动画。
配置(主题 _config.yml)
subtitle:
enable: true
typed:
enable: true # 启用打字机
loop: true # 循环轮播
showCursor: true # 显示光标
cursorChar: "_" # 光标字符
startDelay: 100 # 启动延迟(ms)
typeSpeed: 80 # 打字速度(ms/字)
backSpeed: 50 # 删除速度(ms/字)
post:
typed:
enable: true # 文章标题打字机实现效果
- Banner 副标题逐字打出
- 文章页标题打字效果
- 光标闪烁 + 循环轮播
测试断言:页面含
#typed或.typed-cursor标记。
4. 页面特效
用途
10 种装饰特效(樱花/水波/落叶/雪花/飘带等)。
配置(主题 _config.yml)
sakura: { enable: false } # 樱花飘落
ripples: { enable: false } # 水波荡漾
leaf: { enable: false } # 落叶
snowflake: { enable: false } # 雪花
snowdown: { enable: false } # 落雪
ribbon: { enable: false } # 静态飘带
ribbon_dynamic: { enable: false } # 动态飘带
fireworks: { enable: false } # 点击烟花
clicklove: { enable: false } # 点击爱心
mouseStar: { enable: false } # 鼠标星星
popupText: { enable: false } # 点击文字
buble: { enable: false } # 气泡启用条件
- 桌面宽 >
1400px(BP.fun) - localStorage 访问计数 > 2
实现效果
页面装饰动画,桌面端体验增强,移动端自动关闭(性能)。
测试断言:特效脚本按门控加载(
windowWidth > BP.fun)。
5. 繁简转换
用途
页面繁体/简体一键切换。
配置(主题 _config.yml)
# 默认编码:1=简体 2=繁体
zh_default: 1
footer:
translate:
enable: true实现效果
- 页脚"繁/简"切换按钮
- 点击全局转换文字
- localStorage 记忆用户选择
测试断言:页面含
#translateLink或切换按钮。
6. 阅读进度条 / 返回顶部
用途
阅读进度指示 + 一键回到顶部。
配置(主题 _config.yml)
fun_features:
progressbar:
enable: true
height_px: 3
color: "#29d"
# 返回顶部按钮
backTop:
enable: true实现效果
- 顶部进度条随滚动增长
- 右下角返回顶部按钮(带平滑滚动)
- 移动端按钮尺寸自适应
测试断言:页面含
.progress-bar或#backTop。
7. 打赏弹窗
用途
文章打赏按钮 + 微信/支付宝二维码弹窗。
配置(主题 _config.yml 的 post.reward)
post:
reward:
enable: true
title: 码字辛苦,打赏作者!
wechat: /medias_webp/reward/wechat.webp
alipay: /medias_webp/reward/alipay.webp文章 front-matter 控制
reward: true # 开启本文打赏(可选,默认按全局)实现效果
- 文章底部"赏"按钮
- 点击弹出二维码 dialog(支付宝/微信 tabs)
- 关闭按钮 + 点击遮罩关闭
测试断言:页面含
#reward+ 打赏按钮。
8. 打印样式
用途
打印文章时的排版优化。
配置(主题 _config.yml)
print:
enable: true实现效果
- 打印时隐藏导航/侧栏/页脚
- 正文居中 + 优化留白
- 链接显示 URL
测试断言:CSS 含
@media print规则。
9. 音乐播放器 APlayer
用途
文章/侧边栏嵌入音乐播放器(MetingJS 解析 + APlayer 播放)。
配置(主题 _config.yml)
music:
enable: true
server: netease # netease/tencent/kugou/xiami/baidu
type: playlist # song/playlist/album/search/artist
id: 190133732 # 网易云歌单/歌曲 ID
fixed: false # true = 吸底模式
autoplay: false
theme: '#42b983'实现效果
- 音乐卡片(封面 + 播放控制 + 进度条)
- 吸底模式(fixed)固定页面底部
- 暗色模式适配
测试断言:页面含
aplayer容器标记。
10. 视频播放器 DPlayer
用途
文章内嵌视频播放器(支持 HLS/直播等)。
配置(主题 _config.yml)
dplayer:
enable: true示例(本地视频)
{% dplayer url=/medias_webp/video/demo.mp4 %}实现效果
- 视频播放器(播放/暂停/进度/音量)
- 支持弹幕(danmaku)
测试断言:页面含
dplayer容器标记。
11. Bilibili 视频卡片
用途
嵌入 Bilibili 视频(iframe 或卡片)。
配置(主题 _config.yml)
bilibili:
enable: true
# iframeUrl: //player.bilibili.com/player.html?aid=xxx&bvid=xxx示例
{% bilibili BV1oa4y1L7mw %}实现效果
Bilibili 播放器嵌入,可调整尺寸。
测试断言:页面含 bilibili 相关容器标记。
12. ECharts 图表
用途
文章内嵌 ECharts 交互图表。
配置(主题 _config.yml)
echarts:
enable: true示例
{% echarts %}
{
"title": {"text": "示例图表"},
"xAxis": {"data": ["A", "B", "C"]},
"series": [{"data": [10, 20, 30], "type": "bar"}]
}
{% endecharts %}实现效果
ECharts 交互图表(柱状图/折线图/饼图等)。
测试断言:页面含 echarts 容器标记。
附:交互视觉功能速查表
| 功能 | 配置键 | 参数要点 | 自动化断言标记 |
|---|---|---|---|
| 代码块 | code | language/copy_btn/show_full | code-area |
| 灯箱 | image_zoom + libs.js.lightgallery | enable | .img-item / .lg-outer |
| 打字机 | subtitle.typed / post.typed | loop/showCursor/速度 | #typed |
| 特效 | sakura 等 10+ 开关 | 桌面+访问>2 门控 | windowWidth > BP.fun |
| 繁简 | zh_default + translate | 1/2 编码 | #translateLink |
| 进度条 | progressbar | height/color | .progress-bar |
| 回顶 | backTop | enable | #backTop |
| 打赏 | post.reward | wechat/alipay 图 | #reward |
| 打印 | print | enable | @media print |
| APlayer | music | server/type/id | aplayer |
| DPlayer | dplayer | url | dplayer |
| Bilibili | bilibili | iframeUrl | bilibili |
| ECharts | echarts | JSON 配置 | echarts |

