写 Markdown 文档最扫兴的时刻是什么？不是写不出来，而是配图问题。截图方向偏了，得打开图片编辑器转一下再存回资源目录；截图上带着敏感信息，又得掏马赛克工具涂半天；想统一整套文档的封面风格，就得一张张调灰度再导出。如果你用的是 Typora，并且愿意折腾一点增强插件，这些痛点其实可以全部摊平在编辑界面里解决——这就是 VLOOK™ 的“图片魔法”能力。这个系列我打算分几篇来写，第一篇聚焦最常用的旋转、反转、滤镜三组玩法，把原理、语法、实战和踩坑一次讲清楚，适合 Typora 重度写作用户、技术文档维护者和教程编辑。
1. 为什么偏要在 Markdown 里“声明式”改图
1.1 传统改图流程的隐性成本
大多数人的配图流程是这样的：截图保存到 assets 目录，然后打开看图工具或在线编辑器，旋转、裁剪、调色、打码，再另存为一个新文件，最后回到 Markdown 里改图片路径。这套流程看起来不复杂，但累计成本很高。
首先是时间成本。单张图还好，一次写文档贴十几张截图的时候，每张都过一遍外部工具，少说也要二十分钟。其次是路径管理成本。改图后会生成一个新文件，要么覆盖原图，要么在旁边多出一个_edited版本。覆盖原图意味着原信息丢失，下次想换一种处理风格就得重新找原始素材；保留多版本又会污染资源目录，时间一长根本分不清哪个是最终用的图。
还有一个经常被忽略的问题：团队协作时，图片是被外部工具处理过的“结果文件”，其他成员在 review 文档时看不到处理参数。比如这张图被旋转了 90 度，是拍摄方向问题还是有意为之？那张截图被加了灰度，是风格需要还是原图本来就长这样？这些信息在传统流程里是断裂的。
1.2 Typora 原生能力的边界
Typora 本身的图片能力并不弱。它支持本地图片拖拽、相对路径引用、点击图片预览，还能通过 Typora 特有的图片大小语法调整显示尺寸，比如在图片路径后追加#w=300这样的参数来控制宽度。配合 HTML 块或者自定义 CSS，也可以实现一定的居中、边框效果。
但原生能力的边界很明显：你不具备旋转、翻转、加滤镜这些“像素级”操作。Typora 不是一个图像处理软件，它不会去改变图片本身，也没有暴露 CSStransform或filter的配置入口。
所以当文档里需要一张“被旋转过的图”时，常规做法就只能是预先在外界处理好再贴进来。这也是很多人没意识到的一个痛点：Markdown 的目标是让作者专注于内容，图片展示效果属于“表现层”，本不应该由作者手动用外部工具去完成。
1.3 VLOOK 图片魔法的本质：渲染层滤镜
VLOOK™ 的图片魔法（Image Magic）思路，是把图片处理从“原图编辑”变成“标记声明”。你不需要修改任何像素，只需要在图片标记的某个位置写上一小段魔法指令，VLOOK 在 Typora 预览和导出 HTML 时，会把这些指令翻译成对应的 CSS 效果。
比如rotate:180最终映射为 CSS 的transform: rotate(180deg)，grayscale映射为filter: grayscale(100%)，blur:8映射为filter: blur(8px)。图片文件本身不会被写入任何数据，效果层完全建立在渲染阶段。
这带来了几个非常大的好处：原图始终保真，随时可以调整参数重新渲染；文档可以通过指令看出每张图片的处理意图；同类处理可以批量保持一致的参数，观感天然统一。这就是我说的“声明式改图”，更像是在 Markdown 里写样式，而不是在图像软件里点按钮。
2. 环境准备：让 VLOOK 在 Typora 里跑起来
2.1 获取与解压：注意路径选择
开始之前，先把 VLOOK 的增强包下载下来。这个项目以“主题 + 插件”的一体化方式分发，解压之后你会看到 themes、docs、samples 之类的基础目录。建议解压到一个路径中不含中文和空格的目录，比如D:\tools\vlook。这虽然看起来是个小事，但后续导出静态资源、引用本地文件时，干净的路径能省掉很多编码相关的麻烦。
解压后建议先打开 docs 目录里的离线文档。VLOOK 的语法和参数在不同版本之间会有微调，离线文档相当于随包说明书，后面遇到任何“为什么跟网上教程不一样”的问题，先回来翻它。
2.2 主题安装与启用
把 VLOOK 的主题文件夹内容复制到 Typora 的主题目录。具体入口是 Typora 的“偏好设置 -> 外观 -> 打开主题文件夹”，这个操作会打开系统文件管理器，里面就是 Typora 存放主题 CSS 的位置。
将 VLOOK 提供的 css 文件（不止一个，通常会有光明、暗黑、暖色等多个配色变体）复制进去，重启 Typora，在“主题”菜单里切换到 VLOOK 系列中的任意一款。切换成功后，编辑区整体观感会立刻变化，标题、引用块、表格样式都会更精致。这时候才说明主题文件被正确加载了。
这里有一点值得注意：不要只复制一个 css 文件，最好把主题目录里 VLOOK 相关的文件都复制过去，因为部分效果依赖额外的字体资源和脚本文件，缺了会导致细节样式对不上。
2.3 一个最小的魔法验证
安装完成后的第一件事，是跑一个最小验证用例。随便准备一张本地图片，放到素材目录，然后在 Typora 里写这一行 Markdown：
如果图片在预览区原地旋转了 180 度，说明图片魔法已经生效。如果没有任何变化，先不要往下看教程，回头检查主题是否切换成功、魔法指令的位置是否正确。我见过太多人直接复制大段语法，结果因为一个小括号没配套，半天都没找到问题所在。
2.4 导出 HTML 时的静态资源处理
VLOOK 的魔法效果在 Typora 预览和导出 HTML 时是两套不同的加载机制。预览时依赖 Typora 内的主题样式；导出为 HTML 时，则依赖 HTML 文件同目录下的静态资源。
所以在导出前，要把 VLOOK 的资源目录（通常是主题 css、脚本和字体）复制到 HTML 输出目录下。多数版本在导出时会自动处理，或者给你一个手动拷贝的提示。我的习惯是导出一份之后，用浏览器打开 HTML，按 F12 看网络请求里的 CSS 和 JS 是否都返回 200，如果出现 404，就去把缺失的资源目录补齐。
3. 旋转与反转：把方向不对的图片“扳正”
3.1 旋转语法与方向参数
旋转是图片魔法里最直接的功能。它的语法形式是在魔法区写rotate，后面可以带方向参数。按照我当前的版本，支持下面几种写法：
| 魔法写法 | 效果 | 适用场景 |
|---|---|---|
rotate | 顺时针旋转 90 度 | 默认旋转量，适合绝大多数横向截图转竖向的场景 |
rotate:90 | 顺时针旋转 90 度 | 显式表达旋转方向，推荐在文档中使用 |
rotate:-90 | 逆时针旋转 90 度 | 适合需要向左扳正的图片 |
rotate:180 | 旋转 180 度 | 倒置的图片、需要翻转上下展示的场景 |
rotate:270 | 顺时针旋转 270 度 | 等价于逆时针 90 度，便于统一顺时针语义 |
我的建议是：不要写裸的rotate，一定要带上显式参数rotate:90这种格式。原因很简单，裸rotate的行为在早期版本中默认值是顺时针 90 度，但如果你或同事升级了版本，万一默认值发生变化，整篇文档的图片方向就全乱了。显式参数能让文档的语义不受版本升级影响。
3.2 反转的两种姿态
反转分为水平反转和垂直反转。VLOOK 用flip:h和flip:v来区分。
| 魔法写法 | 效果 | 生活化理解 |
|---|---|---|
flip:h | 水平反转，左右镜像 | 像站在镜子前，左右互换 |
flip:v | 垂直反转，上下颠倒 | 像把图片倒扣过来，上下互换 |
水平反转最常见的需求是把一张带方向性的示意图“镜像”一下。比如你有一个朝右的箭头示意图，但文章语境里希望它朝左，不用重新画图，直接flip:h即可。垂直反转的场景少一些，但也存在，比如某些对称结构的俯视图，或需要把人物视线方向调整到另一侧。
3.3 旋转与反转的数学关系
旋转和反转换算起来是有一套数学规律的。最典型的一条：先旋转 180 度再水平反转，等价于垂直反转。写成魔法指令就是：
这个组合的最终效果和单纯flip:v一样。理解这条等价规律非常有用，因为它能帮你判断“组合魔法”写多了之后图片到底变成了什么样子，不至于在文档里出现意料之外的方向。
还有一条容易被忽略的规律：先翻转后旋转，与先旋转后翻转，最终结果往往不同。比如一张图片先flip:h再rotate:90，与先rotate:90再flip:h，得到的方向是不同的。这是因为旋转操作在翻转后的坐标系里含义发生了变化。遇到复杂的组合时，我的建议是先在预览区放一张带文字或方向标识的测试图，肉眼确认过再写进正式文档。
3.4 什么场景下我会搬出这两组魔法
实际写作中，旋转和反转最常被我用在三个场景里。
第一个是手机截图方向修正。手机竖屏截图直接贴进横屏文档时经常显得突兀，旋转 90 度换成横版布局更协调。这种需求用rotate:90一个参数就解决了，不用重新导出图片。
第二个是演示文稿截图。从演讲 PPT 里截的图，经常因为原页面比例问题想要镜像展示，直接用flip:h。
第三个是带方向语义的示意图。某些流程图、路线图在原文语境中是 A 到 B，但我的文章需要表达 B 到 A，加一个flip:h就能让所有箭头反向，比重新画一张图快得多。
4. 滤镜与风格化：截图秒变“设计稿”
4.1 grayscale：统一报告风格的利器
灰度滤镜在文档写作里出现频率比想象中高。写技术报告时，如果配图是五颜六色的截图，整篇文档会显得很“花”。统一处理成灰度之后，读者注意力会更集中在内容本身，排版上也更好看。
VLOOK 的灰度语法是grayscale，不需要参数，直接作为魔法指令的一部分使用：
实际效果是全图饱和度为 0，等价于 CSS 的filter: grayscale(1)。我通常搭配圆角一起用，先把截图变灰，再统一圆角，看起来就像一组经过设计的黑白插图，而不是随手贴上去的屏幕截图。
4.2 invert 与 blur：脱敏这件事可以更优雅
反色语法是invert，效果等同 CSS 的filter: invert(1)，会让图片颜色反转。这个功能在正常文档中不算高频，但在做深色主题文档、或者想突出某张图的特殊视觉冲击力时很好用。
真正高频的是模糊：blur:12这样带参数的滤镜，等价于filter: blur(12px)。模糊的一个核心应用场景是脱敏。以前处理带个人信息的截图，我会用马赛克工具在图上打格子，但马赛克在放大后能被猜出原始轮廓，而且马赛克区域是硬编码在图片里的，不可逆。
用 VLOOK 的模糊，直接在魔法区写：
整张图会被均匀高斯模糊，敏感信息完全不可读。比马赛克好看，而且你可以在源文档里控制模糊强度，后期要恢复清晰度只需把参数调回blur:0。
需要郑重提醒一点：魔法只是渲染层的模糊，源图文件依然是清晰的。这意味着你导出的 HTML 里虽然看起来是模糊的，但如果有人拿源图片文件，依然能看到原始信息。所以“对外发布”和“源文件管理”必须分开对待，不要因为魔法模糊就忽略源文件的安全。
4.3 radius 与 shadow：圆角卡片与投影
radius和shadow是本组魔法里最有“设计感”的两个参数。
radius:12或者radius:12px给图片添加圆角，等效于 CSS 的border-radius: 12px。圆角会让截图从“一块硬邦邦的矩形”变成“一张精致的卡片”。写教程文档时，UI 截图加圆角几乎是标配，观感会提升一大截。
shadow加外阴影，等效于 CSS 的box-shadow: 0 8px 24px rgba(0,0,0,0.15)之类的一组默认值。阴影能让图片在浅色背景下有浮起感，尤其适合封面图、配图，以及需要强调层次关系的页面。
两者组合使用时，写法上没有任何冲突：
我自己的经验是：文档里所有截图统一带radius:8或radius:12，不用太大，8 到 12 像素是比较自然的观感；阴影在深色主题下可以不开，浅色主题下开起来比较高级。
4.4 滤镜顺序影响效果
组合滤镜时，参数顺序不是随便排的。虽然大多数滤镜组合顺序变化后的差异肉眼不易察觉，但有几个组合是例外。
比如grayscale invert和invert grayscale，前者是先把图变灰再反色，结果仍然是灰度；后者是先把彩色图反色再变灰，因为必须先彩色才能反出彩色效果。如果不注意顺序，最终视觉上可能出现完全不同的明暗关系。
再比如blur:8 grayscale是先模糊后灰度，模糊计算的是彩色图像的像素邻域；grayscale blur:8是先灰度后模糊，此时模糊处理的已经是灰度图像，边界过渡的细节更顺滑。某些边缘场景下，先灰度后模糊的反而不容易出现彩色边缘残留。
我的建议是给组合魔法规定一个书写顺序：先处理色彩类（灰度、反色），再处理几何类（旋转、反转、圆角），最后处理光影类（阴影、模糊）。这样写出来的参数可读性好，效果也最容易控制。
5. 三个从我工作中沉淀的组合玩法
5.1 案例一：手机截图批量统一为教程配图
写移动端教程时，经常会遇到截图尺寸不一、方向混乱、背景颜色五花八门的情况。以前我的做法是把所有截图拖进图像处理工具批量处理，处理完再导出。现在直接在 Markdown 里解决。
在文档中统一使用这组魔法参数：
 每张截图都带灰度、圆角、阴影。整套教程的配图风格立刻统一，而且源图一张都没动。后期如果我想换成彩色风格，只需要删掉所有魔法参数里的grayscale，批量替换一次即可，这种可逆性是外部图片处理工具完全做不到的。
5.2 案例二：用翻转构造镜像对比
写作时有一种常见的对比需求：展示“优化前”和“优化后”的镜像效果，或者左右手、正反面、方向相对的两张示意。以前需要找两张图，现在一张图就够了。
原始图片朝右，我需要展示朝左的版本，直接写：
这样文档里左右两个版本自然形成“镜像对比”，语义上也更容易被读者理解。尤其在一些物理、操作演示类内容里，用同一张原图构造对称展示，比硬找两张风格不一致的图强太多。
5.3 案例三：敏感信息的模糊脱敏
处理涉及内部信息的截图时，我的习惯是准备两套文档：一套内部完整版，一套对外发布版。对外版不需要在图像工具里重新打码，直接依靠魔法区控制。
blur:15的强度已经足够让文本完全不可辨识。要注意的是，对外发布前，我必须确认发布的内容不包含源图片文件本身，只导出最终的 HTML 或 PDF。否则别人拿到资源目录里的原始图片，脱敏依然形同虚设。
5.4 案例四：会议纪要与汇报稿的排版统一
会议纪要类文档通常图片不多，但一旦有，就很容易因为格式不统一而显得草率。VLOOK 的价值在于让所有图片以相同的“规格”出现。
我的习惯是给所有正文配图统一加radius:8和居中处理。这里说一句题外话：VLOOK 的图片居中不需要额外魔法参数，它本身就支持通过特定标记居中图片，配合圆角会让整篇纪要从视觉上更整饬。汇报文档的观感在很多时候直接影响专业度，这种几秒钟就能完成的统一处理，性价比极高。
6. 踩坑实录：魔法失效的 4 种排查路径
6.1 坑一：指令写错了位置
图片魔法最常见的失效原因，是指令写错了位置。不同版本的 VLOOK 对魔法区的位置要求不同，我目前使用的版本是支持在图片 alt 文本括号内以(@magic ...)形式声明的。
插件解析时，会精确匹配括号位置和开头标记。如果你写成：
少了括号，VLOOK 不会把它当作魔法指令，只当作普通说明文字。反过来，如果你把指令放在 Markdown 图片标记的外部，比如：
@magic rotate:180 那就完全不会被解析。这类问题排查起来很快：检查魔法区是否完整包含在图片语法的方括号内，@magic关键字是否原样保留。
6.2 坑二：中英文标点与参数格式
图片魔法的参数格式对标点极其敏感。冒号必须是半角英文冒号，空格必须是半角空格，括号必须是半角括号。中文输入法状态下经常会把rotate:90写成rotate：90，全角冒号会让整个参数失效。
这类错误在预览区不会报错，只是看起来“什么都没发生”。我的排查顺序是：先确认魔法区括号是半角，再确认参数之间的空格是半角，最后确认冒号是半角。三步检查完，九成以上的失效问题都能解决。
另外注意参数之间要有空格分隔，rotate:90flip:h这种连写是无效的，会被当成一个未知参数整个忽略。
6.3 坑三：预览生效、导出却失效
有一种非常让人抓狂的情况：Typora 预览区里图片魔法效果一切正常，但导出 HTML 之后，图片变回了原样，或者说样式明显缺失。
这个问题的根源几乎总是静态资源没拷贝全。VLOOK 的魔法效果依赖导出的 HTML 同目录下的 CSS 和 JS 资源，如果这些资源没有跟随 HTML 一起被复制或发布，浏览器加载不到对应样式，魔法自然就失效了。
排查路径是：打开导出的 HTML，按 F12 进入浏览器开发者工具，查看 Network 面板里有没有 CSS 文件 404。如果有，就手动复制缺失的资源目录到 HTML 同目录下。如果发布到了服务器，要确认静态资源路径是否被正确上传到对应的相对路径位置。
6.4 坑四：版本差异导致语法不同
最后这个坑最隐蔽，也最让人头疼：VLOOK 版本升级后，部分魔法语法可能发生变化。
我遇到过的情况是，旧版本支持用某个缩写参数，升级后这个缩写就不被识别了，但旧版本文档里也没写清楚。处理方式只有一个：不要迷信网上的教程，包括这一篇，所有语法都以你下载版本的随包离线文档为准。
升级前我会做一次完整的验证，把项目里的 demo 文档打开，逐项测试核心魔法是否仍然生效。如果项目工期紧张，宁可保持旧版本不动，也不要贸然升级后临时踩坑。这个习惯救了我很多次。
最后分享一个我的工作习惯：装了 VLOOK 之后，我几乎不再为了“文档展示”专门去外部工具改图了，需要什么效果，就在 Markdown 里声明什么效果。图片魔法只动渲染不动源文件，文档的可读性和可维护性都上了一个档次。系列第一篇就先到这里，后面我会继续把 VLOOK 的排版增强、图表能力和导出技巧一个个拆开聊。如果你在配置或语法上遇到什么奇怪问题，不妨先按上面四条排查路径走一遍，大概率能自己找到原因。
