用了 Typora 写技术文档这么多年我最怕的不是长篇大论而是十几行代码在编辑器里乱成一团。缩进对不齐、高亮识别错、复制出去变成一坨纯文本、导出 PDF 后深色背景消失……这些问题单看都不致命但架不住一天出现十几次。标题里提到的“30 招”我按自己真实写作场景重新梳理了一遍不堆功能、不讲概念全部是能直接上手的操作习惯和配置技巧。不管你是刚把 Typora 当记事本用的新手还是整天输出技术方案、接口文档、教程笔记的老手这 30 招里总有几个能让你今天的效率肉眼可见地变高。1. 插入与编写先把代码块“立”起来1.1 三个插入习惯把低效操作扼杀在源头第1招把“快捷键插入代码块”练成肌肉记忆。Windows/Linux 下是CtrlShiftKmacOS 下是OptionCommandC。这个快捷键值得专门花两天时间刻意记忆因为我见过太多人还在手动打三个反引号再换行。反引号输入本身不难难的是你很容易打反、打成单引号或者输入法自动转成了全角符号等渲染出来才发现代码块根本没生效。快捷键插入的好处是 Typora 会直接生成一个带光标定位的空代码块你做完插入动作后手指不用离开键盘直接输入语言名整个流程一气呵成。第2招先建空块再粘贴内容顺序不能反过来。这是个非常反直觉的细节。很多人习惯先在普通段落里复制代码再插入代码块结果 Typora 在普通段落里接收连续缩进文本时偶尔会把内容识别成引用或列表粘贴进去之后格式已经“脏”了。实际操作里我是先按快捷键生成一个空代码块确认输入光标在块内再执行粘贴。这样做的好处是 Typora 会按照代码块语义原样保留缩进不会多做一次 Markdown 解析粘贴多行 shell 脚本或缩进敏感的 Python 代码时能少踩不少坑。第3招插入后立刻输入语言名而不是先写代码再回头补。语言标记的位置在第一组反引号之后如果你先粘贴代码再去补标记光标要从代码尾部一路移到块首长代码块里这一步非常烦。反过来插入空代码块后顺手打上python、javascript或bash回车进入代码区接下来写的每一行都能立即享受对应的语法高亮写错了还会实时标色很大程度上相当于一个轻量级 IDE 提示。1.2 块内编辑的三个细节影响的是手感第4招代码块内的 Tab 和 ShiftTab 只负责缩进不负责跳转。在普通段落里按 TabTypora 会缩进当前行在代码块里按 Tab很多人发现似乎没有反应或者光标直接跳出了代码块。实际情况是代码块内 Tab 默认插入一个制表符或按配置转为空格ShiftTab 则做反缩进。选中多行再按 Tab可以一次性把整块代码向右推进选中后按 ShiftTab 则统一收复。想调整某个代码块的层级结构不需要一行一行敲空格框选缩进是最快的。第5招用多行光标改代码把“重复劳动”降为零。Typora 虽然不像 VSCode 那样有完整 IDE 功能但代码块内支持基础的Ctrl点击macOS 是Cmd点击添加多个光标。碰到需要给几十行代码统一加前缀、统一去后缀、或修改某几列缩进时这个功能比逐行改高效得多。我常用它把一段日志格式的文本批量改成 Markdown 引用格式或者把每行代码末尾的注释符号对齐。实测下来几十行的规模内多行光标比正则替换更直观、可控性更强。第6招别纠结原生“折叠代码块”用标题折叠替代它。很多从其他 Markdown 编辑器转过来的朋友会找代码块折叠功能但 Typora 原生并不提供“收起代码块内容”的按钮。与其硬等这个功能不如换个思路把一篇文章里的大段代码拆分成若干块分别放进带标题的小节里然后利用 Typora 的标题折叠点击标题左侧的三角箭头实现整块收起。这样文档结构还更清晰读者按标题跳转时一下子就能看到代码的位置比折叠塞进一个巨型代码块更友好。2. 语言高亮代码块颜值与准确率的根本2.1 语言标记一个字符决定高亮成败第7招语言名要写对但不必追求官方全称。Typora 的语法高亮基于 CodeMirror支持很多常见语言的别名。比如js和javascript都能触发 JavaScript 高亮py和python都可以cpp和c也都行。我通常记住一套最短别名能少打字就少打字。但有两个容易踩的坑一是不要用c来写 C 代码高亮结果会差很多二是html和htm表现不一样写网页片段时建议直接html。拿不准时最稳妥的办法是把语言名写完整高亮引擎识别率极高。第8招不需要高亮的场景大大方方用text或plain。日志输出、错误堆栈、终端交互记录这类内容强行套用某种语言高亮反而是灾难。比如把一段 PostgreSQL 日志标记成sql里面的时间和错误级别会被拆得花里胡哨关键信息反而看不清。我现在的习惯是只有真正能运行、需要让人阅读语法的内容才标语言其余统一标记为text。这能让读者把注意力集中在内容上而不是被不准确的配色干扰。2.2 高亮出错时的排查思路第9招高亮“完全变了”时先检查代码块左下角的语言标签。Typora 渲染后的代码块左上角会显示当前语言名部分主题在左下角。如果发现颜色错乱优先看这个标签是不是与你预期一致。常见问题有两种一是语言名拼错比如javascirpt少个 p直接失去高亮二是语言名有空格或特殊字符引擎认不出来。定位到问题后把光标移到块内重新修改第一行的标记即可不需要重建代码块。第10招代码块里的英文单词被红色波浪线标记大概率是拼写检查在捣乱。Typora 默认开启拼写检查代码里的变量名、函数名、缩写很容易被判定为“拼写错误”。看着满屏红波浪线代码块的美观度会大打折扣。解决方案有两个一个是在偏好设置的“通用”里关闭拼写检查适合以快速写作、代码记录为主的人另一个是保留拼写检查但手动忽略代码块区域适合写长篇文章的人。我个人更推荐直接关闭因为 Typora 的强项是 Markdown 编辑不是英文写作留着红波浪线的收益很低。2.3 让高亮为写作服务第11招用代码块存放配置文件写作阶段就暴露格式问题。JSON、YAML、TOML 这类配置格式最适合放进 Typora 代码块里检视。缩进多了少了、逗号漏了、引号不配对高亮颜色会直接给出暗示。我写部署文档时经常一边写说明一边把.env或docker-compose.yml的关键片段贴进代码块渲染出来的颜色和编辑器里高度一致等于提前做了一遍语法预检。这比写完再开 IDE 验证要快得多。第12招别忘记 Mermaid 也是代码块的一种“语言”。Typora 支持用mermaid语言标记绘制流程图、时序图、类图。这意味着你不只可以在代码块里放普通代码还能直接画架构图。我写系统设计文档时通常用两个代码块一个放核心代码片段一个放 Mermaid 时序图两者前后呼应。需要注意Mermaid 代码块里的缩进和语法要求比较严格画完如果发现图形没有正常渲染先检查是否漏了节点的形状符号或箭头标记。3. 主题与显示把代码块调教成顺眼的样子3.1 主题与字体选择的几个决策点第13招写作默认用浅色主题代码块配色跟着主题走。Typora 的代码高亮外观由当前主题决定。GitHub 主题的代码配色和 GitHub 网页端几乎一致适合写技术文档、给开源项目写 README 的场景而 Newsprint 这类偏写作的主题代码块配色会更淡雅适合读书笔记类的非技术文本。我的建议是如果文章主要展示代码优先选 GitHub 风格主题如果代码只是点缀选你阅读最舒适的主题即可。不要因为看到别人晒的深色主题好看就盲目切换深色主题在日光下长期写作眼睛疲劳感会明显加重。第14招代码字体选择带连字的等宽字体观感提升立竿见影。Typora 允许在“偏好设置 → 外观 → 字体”里分别配置正文和代码字体。如果默认的等宽字体看起来太普通我推荐试一下 Fira Code、Cascadia Code、JetBrains Mono。这些字体支持 ligature连字、-、会显示成视觉上合并后的符号连读性强很多代码密度高的时候不容易看串行。字体大小建议比正文字号小 1~2 号行高控制在 1.4 左右这样长代码不会显得臃肿。第15招谨慎处理代码块的自动换行。在“偏好设置 → 通用 → 自动软换行”里你可能会看到与代码相关的选项。代码块若是开启自动软换行很长的行会被折成多行表面上方便阅读可一旦把代码复制出去换行符也被带走了代码逻辑可能被破坏。我的做法是正文开启软换行代码块关闭软换行让长代码横向滚动。虽然多了一步滚动操作但保证了代码的原样性。3.2 用 CSS 定制只属于自己的代码块样式第16招用base.user.css修改代码块背景、圆角、边框。Typora 支持通过主题目录下的base.user.css做全局样式覆盖。找到“偏好设置 → 外观 → 打开主题文件夹”新建或编辑base.user.css写入类似下面的内容#write .md-fences { background-color: #f6f8fa; border-radius: 8px; border: 1px solid #d0d7de; padding: 12px; margin: 16px 0; }保存后重启 Typora代码块的背景色、圆角、边框就按你的偏好来了。这个能力很适合想把代码块做得和博客样式统一的人。注意不同主题中代码块的选择器可能略有差异如果改完没生效先在原主题的 CSS 里搜索.md-fences或code再对照着覆盖。第17招用 CSS 调节代码字号与行高改善长代码的阅读压力。如果觉得代码块默认字号太大或太小可以在base.user.css里加一条#write .md-fences code { font-size: 14px; line-height: 1.5; }调整省下来的空间能让一屏里容纳的行数多出三分之一。我经常用这一招同时处理“代码行数很多”和“旁边还要放说明”的版面问题。字号也不用一味追求大14~15px 在普通屏幕上是舒适区再大就很容易频繁横向滚动。第18招弱化代码块顶部的语言标签让视觉更干净。部分主题会在代码块左上角用明显的色块显示语言名有辨识度但看久了会很吵。你可以在base.user.css中把语言标签的显示调整成细体、浅色或者干脆隐藏。我用的是#write .code-tooltip { opacity: 0.6; font-size: 12px; }这样代码块整体的观感更接近“正文的延续”而不是一张张贴在文章里的截图。这个细节对于输出对外技术文档尤其重要可以减少读者被装饰性元素打断的频率。4. 复制、导出与外部工作流代码块的最后一公里4.1 复制代码时不再漏行断行第19招代码块内用CtrlAmacOS 用CmdA全选该块内容而不是从开头拖拽到结尾。代码块是 Typora 渲染层的特殊容器鼠标拖拽选择时容易在块的首尾多选中空白行或漏掉结尾几个字符。把光标放在代码块内一次性全选然后复制得到的字节和源代码模式里看到的内容完全一致。这是我踩过很多次坑之后形成的习惯尤其是复制脚本、正则这类对换行敏感的内容一旦多出一个空行或少了一个换行执行结果就会完全变味。第20招粘贴到 IDE 前先统一 Tab 与空格风格。Typora 代码块内实际保存的缩进字符取决于你粘贴进来时源内容是什么。如果从 VSCode 里复制过来用的是四个空格从某网页复制过来用的是 Tab混在一个块里后续复制到 IDE 时会换来换去。推荐的检查方法是在代码块内全选后用 Typora 的“查找与替换”功能把\t统一替换成四个空格或者反过来。操作路径是编辑 → 查找 → 替换勾选正则选项后就可以精确处理制表符了。第21招给常用代码块加“头部注释”让复制的代码自带上下文。我看到很多文档里的代码块只有代码没有任何说明。读者复制后拿去用还得自己猜使用条件。改善成本很低在代码块第一行用注释写清楚文件路径或适用场景。比如# scripts/deploy.sh —— 仅适用于 Linux/macOS这不是 Typora 功能层面的技巧但对提升代码块整体价值有奇效。你之后回看自己的笔记时能瞬间想起来这块代码是干什么的、该放到哪里省去大量回忆时间。4.2 导出 PDF/HTML 时保留高亮与样式第22招导出 PDF 时务必勾选“背景图形”。Typora 导出 PDF 默认会保留文本颜色但深色代码块的背景色不一定保留。很多系统 PDF 阅读器为了省墨默认不打印背景图形结果导出的 PDF 里代码块变成了白底彩字部分浅色字体在白底上几乎看不见。解决方法是导出 PDF 时在打印设置里勾选“背景图形”或在 Typora 的导出设置里确认保留背景色选项。这一步不做你再好的代码配色都会被 PDF 磨平。第23招导出 HTML 时选择嵌入样式保证高亮不散架。Typora 的“导出为 HTML”会带上当前主题的样式。如果你选择一个带外部 CSS 链接的导出方式换台设备打开时样式可能加载失败。我的习惯是导出时选择“嵌入样式”或“内联样式”让高亮配色写死在 HTML 文件里。这样无论发给谁、放到哪台无网络电脑上代码块外观都不会变形。第24招把代码发布到公众号或知乎前用“导出 HTML 再粘贴”代替直接复制。直接在 Typora 里复制代码块粘贴到公众号、知乎、语雀这类富文本编辑器时经常丢失背景色和高亮。更可靠的做法是先导出 HTML再从浏览器里复制渲染后的代码块粘贴到目标编辑器。虽然多一步但能保住代码块底纹和关键字颜色。我写博客的流程基本都是这样Typora 写完 → 导出 HTML → 浏览器打开 → 复制内容 → 粘贴发布。5. 组合技代码块与文档结构一起飞5.1 写作结构上的三个习惯第25招用大标题折叠收纳多个代码块大纲视图秒变索引。一篇教程往往有安装命令、配置示例、启动脚本、验码逻辑四五个代码块散在长文里读者想找某一段很难。我推荐的写法是每个大的步骤小节用一个 H2 或 H3 标题代码块放在该标题下。Typora 的大纲视图里可以直接看到这几个标题点击即跳转配合标题折叠长文档浏览体验会接近一本小型手册。这其实就是很多人想要的“折叠代码块”只是实现思路换成了结构拆分。第26招先给一句话引用块再放代码块别让代码裸奔。代码块之前加一行引用说明能把“这段代码解决什么问题”提前交代清楚。比如下面这段脚本用来清理 30 天前的构建日志建议放在 crontab 中每周执行。find /var/log/myapp -type f -mtime 30 -delete这个组合看着简单但做不做效果差异很大。原因在于代码块本身是“视觉重音”如果每个代码块前面都有明确目的读者扫视文章时就能根据引用文字快速决定是细看还是跳过。第27招在代码块内部用长注释分割多个子片段减少文档碎裂。如果几个代码片段紧密相关我不建议把它们拆成三四个代码块那样会在文章里形成重复的边框和留白。更好的做法是放进同一个代码块用行内注释做分隔。比如# ---- 数据读取 ---- data load_data() # ---- 数据清洗 ---- data data.dropna() # ---- 结果输出 ---- print(data.head())这样视觉上只有一个区块逻辑上却是清晰的三个阶段复制时也能一次带走全部。需要注意不同语言的行内注释符号不同忘改符号会造成高亮异常。5.2 跨场景联动与排版细节第28招把部署配置做成笔记模板一键复制就能用。我自己的笔记里长期存着几个“代码块模板”.env字段说明、Dockerfile常用写法、docker-compose.yml标准结构、Nginx 简化配置。每次写新项目的部署文档直接从笔记里把对应代码块复制出来改几个变量名就完事。把配置类代码块当作可复用零件来维护比每次从零敲高效得多。第29招代码块和效果图混排时图片宽度用 Typora 扩展语法控制。写前端或脚本示例时一个代码块加一张运行效果图是最有说服力的展示方式。Typora 支持在图片路径后直接追加尺寸参数例如等号后的数字分别控制宽度和高度只写一个参数会按比例缩放。这样一个页面内代码和效果图对齐读者不用来回滚动对照。图片紧跟在对应代码块的下方比统一堆在文末更直观。第30招把 Typora 当作轻量代码整理中转站。我在日常工作中经常要向同事发送一段从邮件、PDF、聊天记录里复制来的杂乱代码。以前我会直接粘贴进 IDE 再整理后来发现更轻的路径是粘贴到 Typora 的代码块里用第4招的 Tab/ShiftTab 统一缩进再全选复制出来。Typora 启动快、渲染即时处理这种不跨项目的零碎代码整理比打开 IDE 更顺手。某种程度上这也是代码块功能被很多人低估的用法。上面这 30 招大部分是我在写接口文档、部署手册和项目周报的过程中一个一个磨出来的。代码块在 Typora 里并不是孤立的“放代码的框”它和快捷键、主题、导出机制、文档结构都连着组合在一起才能发挥出这台编辑器的真实效率。如果你也有自己私藏的代码块用法欢迎按同样的思路继续往这 30 招里加把工具用到手顺为止。