【Obsidian 插件】CodeblockCustomizer 中文手册

CodeblockCustomizer 中文手册

Obsidian 代码块自定义插件完整使用指南。原文档：GitHub - mugiwara85/CodeblockCustomizer

[toc]

概述

CodeblockCustomizer 是一款 Obsidian 插件，用于自定义代码块的外观和行为。主要功能包括：

• 🎨 多主题：内置 Obsidian、Solarized、Dracula、Gruvbox、Nord、Tokyo Night 等主题，也支持自定义
• 📌 行高亮：按行号、范围或关键词高亮代码行，支持多种自定义颜色
• 🔤 文本高亮：在代码块中高亮指定文本片段
• 📁 文件名/标题头：为代码块添加带样式的文件名或标题头
• 📑 折叠/半折叠：点击标题头折叠代码块，支持半折叠渐隐效果
• 🔢 行号：可选行号显示，支持起始偏移和行号跳转
• 🖥️ 终端提示符：模拟 bash、zsh、PowerShell、Kali 等终端提示符
• 📊 分组标签页：将连续代码块合并为标签页界面
• 💬 注解：将代码注释转换为样式化标注（note、warn、error 等）
• 🎯 内联代码高亮：对行内代码应用语法高亮
• 🧩 PrismJS 语法高亮：编辑模式下统一使用 PrismJS，使编辑/阅读模式高亮一致
• 📋 复制为图片：将代码块快照为图片
• 👁️ 隐藏行：使用 hide 参数隐藏指定行/范围

---

参数速查表

参数在代码块开头（三个反引号后的第一行）定义，使用 : 或 = 分隔。

参数	值	说明
fold	—	文档打开时该代码块默认折叠
unfold	—	反向折叠模式下默认展开（需启用 Inverse fold）
exclude	—	将该代码块排除出插件处理
hl	多值	高亮指定行，支持行号、范围、关键词及其组合
hlt	多值	高亮指定文本片段
lsep	字符	行分隔符（默认 |），用于文本高亮中指定行
tsep	字符	文本分隔符（默认 :），用于文本高亮中指定起止
file	字符串	设置标题头显示的文件名
title	字符串	file 的别名
ln	多值	true/false/数字/数字:数字，控制行号
parse	parse:promptName	解析代码块中的原始 CLI 输出，为提示符着色
hide	hide:行或范围	隐藏指定行/范围，插入展开/折叠按钮
prompt	prompt:名称	使用指定终端提示符
noprompt	—	禁用当前代码块的提示符
user	字符串	覆盖提示符的默认用户名
host	字符串	覆盖提示符的默认主机名
path	字符串	覆盖提示符的默认路径
db	字符串	覆盖提示符的默认数据库名（postgres）
branch	字符串	覆盖提示符的默认 Git 分支（zshgit）
module	字符串	覆盖提示符的默认模块名（metasploit）
group	字符串	将代码块分配到分组，连续同组块渲染为标签页
tab	字符串	设置分组标签页的自定义显示名

---

1. 行高亮（hl）

在代码块首行使用 hl: 参数高亮指定行。

语法格式：

格式	示例	说明
hl:{行号}	hl:5	高亮第 5 行
hl:{范围}	hl:5-7	高亮第 5~7 行
hl:{关键词}	hl:test	高亮所有包含 “test” 的行
hl:{行号}|{关键词}	hl:5|test	第 5 行中包含 “test” 时高亮
hl:{范围}|{关键词}	hl:5-7|test	第 5~7 行中包含 “test” 时高亮

组合示例：

text

hl:1,3,4-6,test,5|test,7-9|test3

多色高亮

可定义多个高亮颜色（如 info、warn、error），在设置页配置后即可在代码块中使用：

text

info:2 warn:4-6 error:8

所有 hl 的语法规则同样适用于自定义高亮颜色。

---

2. 文本高亮（hlt）

使用 hlt: 参数高亮代码块中的文本片段（而非整行）。

格式	说明
hlt:{字符串}	高亮所有行中出现的该字符串
hlt:{行号}	高亮该行的所有文本
hlt:{行号}|{字符串}	仅在该行中高亮指定字符串
hlt:{范围}|{字符串}	仅在指定范围内高亮
hlt:{起始}:{结束}	高亮从”起始”到”结束”之间的文本
hlt::{结束}	从行首高亮到”结束”
hlt:{起始}:	从”起始”高亮到行尾

出现次数控制：

hlt:5[2,5-8]|test — 在第 5 行中，高亮第 2 次和第 5~8 次出现的 “test”。

💡 如果要高亮的文本中包含 \| 或 :，可用 lsep 和 tsep 重新定义分隔符。

---

3. 文件名/标题头（file / title）

markdown

```cpp file:test.cpp

markdown

```cpp title:test.py

markdown

```cpp file:"long filename.cpp"

• title 是 file 的别名，两者同时出现时以 file 为准
• 文件名含空格需用 "" 包裹
• 文件名含 " 或 ' 需用 \ 转义

---

4. 标题头显示规则

标题头在以下情况显示：

1. 指定了 file: 或 title:
2. 指定了 fold（无 file/title 时显示 “Collapsed code”）
3. 启用了”始终显示语言”或”始终显示语言图标”设置

启用”语言图标”后，约 170 种语言会显示对应图标。

---

5. 折叠与半折叠

基本折叠

markdown

```cpp fold

点击标题头即可切换折叠/展开。

半折叠（Semi-fold）

在设置页启用后，较长的代码块不会完全折叠，而是显示前 N 行（默认 5 行），后续行渐隐。

• 可配置可见行数
• 可选附加展开按钮
• 渐隐行数固定为 4 行（不可改）

默认全折叠

启用”打开文档时默认折叠所有代码块”选项后，所有代码块自动折叠。此时可用 unfold 参数让特定块默认展开。

---

6. 行号（ln）

在设置页启用”Enable line numbers”后全局显示行号。可用 ln 参数针对单个代码块控制：

值	说明
ln:true	该块显示行号（即使全局关闭）
ln:false	该块不显示行号（即使全局开启）
ln:5	行号从 5 开始
ln:10:20	行号跳转：第 10 行开始编号变为 20

---

7. PrismJS 语法高亮

背景：Obsidian 编辑模式使用 CodeMirror 6，阅读模式使用 PrismJS，两者高亮不一致且 CodeMirror 支持语言更少。

启用”Use PrismJS for syntax highlighting in editor mode”后：

• ✅ 编辑模式与阅读模式高亮一致
• ✅ CodeMirror 不支持的语言（如 GraphQL、Makefile、HLSL）也能高亮
• ⚠️ 实验性功能，如遇问题可关闭

---

8. 主题

内置主题：Obsidian（默认）、Solarized、Dracula、Gruvbox、Nord、Tokyo Night。

• 每个颜色都保存在主题中，可修改默认主题（可恢复）
• 每个主题有独立的亮色/暗色配色
• 切换 Obsidian 亮/暗模式可分别配置
• 新建主题以当前主题为模板

---

9. 语法主题（Syntax Themes）

语法主题控制代码语法高亮的 token 颜色（关键字、字符串、注释等）。

• 内置主题：Obsidian、Dracula、Gruvbox、Nord、Solarized、Tokyo Night、VS Code Modern、Monokai、GitHub、Catppuccin
• 可全局设置，也可按语言覆盖
• 完整 token 列表参见 PrismJS Tokens

建议启用 PrismJS 编辑模式高亮以获得最佳效果。

---

10. 语言特定颜色

在设置页 “Language Specific Color Overrides” 中可按语言定义颜色，可配置项包括：

• 代码块背景/边框/文本/活跃行颜色
• 括号匹配/不匹配颜色
• 标题头背景/文本/语言标签颜色
• 行号背景/文本/活跃行号颜色

设置边框颜色后别忘了配置 “Codeblock border styling position”，否则边框不显示。

---

11. 分组代码块（Tabs）

markdown

```python group:example tab:main.py
```python group:example tab:utils.py

连续使用相同 group 名称的代码块会合并为标签页界面。

⚠️ 分组名需在同一文档内唯一；导出 PDF 时分组会失效。

---

12. 终端提示符（Prompts）

使用 prompt:<名称> 创建仿真终端提示符。

内置提示符

提示符 ID	说明
bash	Bash 提示符
bashalt	替代 Bash 样式
cmd	Windows CMD
cstrike	Cobalt Strike
docker	Docker
fish	Fish Shell
kali	Kali Linux
msf	Metasploit
postgres	PostgreSQL
ps	PowerShell
zsh	ZSH
zshgit	ZSH + Git

支持的命令

命令	说明
cd / cd ~ / cd folder / cd .. / cd -	目录跳转
cd /absolute / cd ~/folder / cd "some dir"	绝对/家目录/带空格路径
su / su <user>	切换用户
whoami	显示当前用户
exit	切回上一用户
pwd	显示当前目录
\c	切换 PostgreSQL 数据库
git checkout/switch <branch>	切换分支
use	切换 Metasploit 模块

自定义提示符

在设置页创建自定义提示符，需配置三项：

• basePrompt：提示符模板，如 "{user}@{host}:{path}$"
• parsePromptRegex：正则表达式，用命名捕获组提取信息
• highlightGroups：JSON 映射，将捕获组名映射到样式类

即时提示符（On-the-fly）

在代码块中直接定义：prompt:"{user} at {host} in {path}" user:mugiwara host:PC1 path:/var/www/html

⚠️ 即时提示符无法自定义颜色。

解析原始 CLI 输出

使用 parse:bash 可自动为粘贴的原始 CLI 输出中的提示符着色。

---

13. 注解（Annotations）

在代码注释中使用 [!type] 语法将注释转为样式化标注。

支持类型：note、warn、error、todo、question、see

可附加标题：[!warn|注意]

---

14. 隐藏行（hide）

markdown

```text hide:3,5,7-10

隐藏指定行/范围，插入分隔符供展开/折叠。展开后出现眼睛按钮可重新隐藏。

---

15. 隐藏围栏线

启用”Hide Fence Lines”后，三反引号围栏线默认隐藏，光标进入代码块时才显示。

---

16. 内联代码高亮

基本着色

启用后可为行内代码设置背景色和文本色。

语法高亮内联代码

启用后使用 {语言} 代码 语法：

markdown

{cpp} printf("Hello World!")

---

17. 命令面板命令

命令	说明
Fold all code blocks	折叠当前文档所有代码块
Unfold all code blocks	展开所有代码块
Restore original state	恢复代码块初始状态
Indent code block	代码块缩进一级
Unindent code block	代码块取消一级缩进

---

18. 其他功能

换行/取消换行按钮

编辑模式下显示换行切换按钮。

复制为图片

将代码块快照为 PNG 图片。

修饰键

可为按钮和内联代码配置修饰键（如 Ctrl+Click 触发复制）。

模糊效果

半折叠状态可启用模糊渐隐效果。

Frontmatter 着色

编辑模式下自定义 frontmatter 语法高亮颜色。

自定义语言语法规则

可为自定义语言定义 PrismJS 语法高亮规则。

括号高亮

匹配/不匹配括号的颜色高亮，及背景色配置。

选择匹配

选中文本时高亮所有匹配项。

插件兼容性

与 Execute Code 插件兼容。

导出 PDF 注意事项

• 分组代码块导出 PDF 时会取消分组
• 其他功能正常导出

---

安装方法

方法一：社区插件市场

1. 打开 Obsidian → Settings → Community plugins
2. 关闭 Safe Mode（如需要）
3. 点击 Browse，搜索 “Codeblock Customizer”
4. 点击 Install，然后 Enable

方法二：手动安装

1. 从 Releases 页面 下载 main.js、manifest.json、styles.css
2. 在 Obsidian vault 的 .obsidian/plugins/codeblock-customizer/ 目录下放入这三个文件
3. Settings → Community plugins → 启用 Codeblock Customizer

---

快速上手示例

markdown

```cpp file:hello.cpp ln:true hl:2,4-6
#include <iostream>
 
int main() {
    std::cout << "Hello, World!" << std::endl;
    return 0;
}
```

markdown

```python fold file:utils.py
def greet(name):
    return f"Hello, {name}!"
```

markdown

```bash prompt:kali
msf6 > use exploit/multi/handler
msf6 > set PAYLOAD windows/x64/meterpreter/reverse_tcp
```

markdown

```python group:demo tab:main.py
print("Tab 1")
```
```python group:demo tab:utils.py
print("Tab 2")
```

---

📎 参考链接

• GitHub 仓库：https://github.com/mugiwara85/CodeblockCustomizer
• 更新日志：Changelog.txt
• PrismJS Token 列表：https://prismjs.com/tokens.html