嵌入式开发日常里最容易被忽视的其实是“文档查看”这件事写代码时翻数据手册、看原理图截图、记录调试结论通常要在 PDF 阅读器、图片查看器、记事本之间来回切换。这次我们来看一个更顺手的组合方案把 PDF 阅读、PNG 图片预览、Markdown 笔记、Mermaid 流程图和 LaTeX 公式渲染全部放进嵌入式 IDE 的工作区里减少窗口切换让硬件资料和代码保持同一套组织逻辑。这个方案不是某个独立的大软件而是基于 VS Code 这类嵌入式开发常用 IDE 的插件组合。它最核心的价值在于把“文档阅读”和“代码开发”放到同一个工作区数据手册、寄存器截图、设备树说明、调试笔记、协议流程图、硬件计算公式都能在同一界面里打开和预览。对做单片机开发、驱动调试、硬件验证、嵌入式 Linux 的人来说最大的收益是少切窗口、少找文件笔记和源码可以放在同一个目录里一起走版本管理。文章会按“环境准备 - 插件安装 - 功能测试 - 性能观察 - 问题排查”的顺序展开。整个过程不涉及模型部署不依赖 GPU门槛主要在 IDE 版本和插件市场访问是否正常。你可以照着一套流程验证下来再判断这套方案值不值得长期使用。1. 核心能力速览能力项说明方案类型IDE 工作区增强组合由编辑器加插件实现实现载体VS Code 等嵌入式开发常用 IDE配合插件PDF 阅读在 IDE 内直接打开 PDF 数据手册支持翻页、缩放、文本搜索PNG 图片预览直接点击图片文件预览也可以从 Markdown 中以相对路径引用Markdown 预览侧边实时预览支持标题、表格、任务列表、代码块、目录Mermaid 渲染在 Markdown 预览中渲染流程图、时序图、类图、状态图等常用图表LaTeX 渲染通过 KaTeX 或 MathJax 渲染行内公式与块级公式导出能力可将 Markdown 导出为 HTML、PDF、PNG 等常见格式硬件门槛无 GPU 要求普通办公电脑即可适合场景嵌入式开发笔记、驱动文档、协议分析、硬件调试记录、技术博客素材整理2. 适用场景与使用边界这套方案适合大多数嵌入式开发者尤其是这几类场景。第一类是 MCU 和嵌入式 Linux 驱动开发开发过程中需要频繁查阅芯片数据手册和寄存器描述把 PDF 直接拖进 IDE 里打开旁边就是源码窗口查某个寄存器时不用反复切换应用。第二类是硬件调试记录调试过程中常常要保存逻辑分析仪截图、示波器截图把这些 PNG 统一放到项目目录的 assets 下再在 Markdown 里写一段调试结论截图和结论放在一起比散落在桌面强很多。第三类是协议分析与文档沉淀比如 I2C、SPI、UART、CAN 这类通信协议用 Mermaid 画时序图或者状态机直接写进 README 或开发文档里后续维护时一眼就能看懂。它和专门的文档工具有明显边界。如果你需要复杂排版、多人协同编辑、严格的批量模板套用使用 Word 或在线文档平台会更合适。IDE 内预览更适合“看代码的同时快速看资料”这种场景不适合做最终交付文件的精细排版。另外IDE 内打开超大型 PDF 时内存占用和翻页流畅度通常不如专门的 PDF 阅读器所以一套工作流里不一定只有一种工具IDE 内预览负责快速查阅正式阅读或批注仍然可以用专业工具。使用边界上要注意资料授权。数据手册、原理图、客户文档、第三方库文档如果涉及保密或版权约定不要随意放进公开仓库或外部文档系统。团队内部使用时要确认资料使用范围对外发布或交付前要做脱敏和授权确认。3. 环境准备与前置条件在动手之前先确认基础环境。操作系统Windows、Linux、macOS 都可以嵌入式开发中 Windows 和 Linux 最常见。IDE 版本建议使用 VS Code 1.70 以上版本版本太老可能无法安装部分插件。如果是 Eclipse、STM32CubeIDE、Keil 等 IDE原理类似但插件生态和安装方式不完全相同需要按实际情况调整。网络条件插件市场访问正常或者可以离线下载 vsix 文件安装。磁盘空间插件占用很小留出几百 MB 空间即可。如果还要用导出 PDF 功能需要本机装有 Chrome 浏览器。常用插件Markdown Preview Enhanced、vscode-pdf、Markdown All in One。如果使用 VS Code 内置 Markdown 预览可以补装 Markdown Preview Mermaid Support。先检查 IDE 版本命令行输入code --version确保能正常输出版本号。然后检查现有插件列表code --list-extensions这一步是为了确认哪些插件已经存在避免重复安装。4. 安装部署与启动方式插件的安装方式很简单。直接打开 VS Code 扩展面板搜索插件名点击安装即可。也可以用命令行安装适合多台机器批量配置。# Markdown Preview Enhanced核心预览增强扩展 code --install-extension shd101wyy.markdown-preview-enhanced # PDF 查看扩展例如 tomoki1207.pdf code --install-extension tomoki1207.pdf # Markdown 编辑效率工具提供快捷键、列表补全、表格格式化 code --install-extension yzhang.markdown-all-in-one # VS Code 内置 Markdown 预览的 Mermaid 支持扩展可选 code --install-extension bierner.markdown-mermaid安装完成后建议把几个常用的 Markdown 预览设置写进用户设置。这里给一份可以直接参考的 settings.json 片段{ markdown-preview-enhanced.previewTheme: github-light.css, markdown-preview-enhanced.codeBlockTheme: github.css, markdown-preview-enhanced.mathRenderingOption: KaTeX, markdown.preview.fontSize: 14, markdown.math.enabled: true }markdown-preview-enhanced.previewTheme控制预览主题github-light 适合代码阅读习惯。markdown-preview-enhanced.codeBlockTheme控制代码块主题。markdown-preview-enhanced.mathRenderingOption指定用 KaTeX 渲染 LaTeX 公式渲染速度比 MathJax 更快。markdown.math.enabled是 VS Code 内置预览对数学公式的支持开关。启动方式分两种。Markdown 文件打开后如果点右上角的拆分预览图标或按Ctrl K V可以打开左侧编辑、右侧预览的分屏模式。如果直接用内置 Markdown 预览按Ctrl Shift V打开独立预览页。PDF 文件直接在资源管理器中点击如果是刚才安装的 PDF 扩展通常会在编辑器标签页里直接打开而不是弹出外部程序。PNG 图片也是一样点击后会在编辑器内打开图片预览。如果用的是 Eclipse、STM32CubeIDE 这类不能直接装 VS Code 插件的 IDE可以有两种替代思路。一种是把文档编辑工作放到 VS Code代码工程仍然留在原来的 IDE 里二者用同一个 Git 仓库管理。另一种是查找对应 IDE 的插件市场有些基于 Eclipse 的 IDE 支持安装 Eclipse Markdown 插件但体验通常不如 VS Code 组合完整。5. 功能测试与效果验证环境配置好后建议按下面几个步骤逐项验证确认每个功能真正可用。5.1 PDF 阅读测试先找一个实际项目中使用的 PDF 数据手册比如芯片参考手册或数据表。把它拖到 VS Code 工作区里点击打开。测试目的确认 IDE 内能直接打开 PDF而不是弹出外部阅读器。操作步骤在资源管理器中展开目录点击 PDF 文件。查看编辑器区域是否能显示 PDF 内容。尝试翻页、缩放选中 PDF 中的文本看能否复制。预期结果PDF 在编辑器标签页中打开可以正常翻页英文文本通常可以选中复制。如果点击后没有反应检查 PDF 扩展是否安装或者文件本身是否损坏。这里要特别注意IDE 内 PDF 查看适合快速查阅不适合大量批注。如果你习惯在 PDF 上画重点可以继续用专业 PDF 阅读器。这个功能解决的核心问题是“查手册不用切窗口”。5.2 PNG 图片预览测试把逻辑分析仪截图、示波器截图、原理图截图、PCB 截图放入项目的 assets 目录在资源管理器中点击 PNG 文件。测试目的确认 IDE 能打开图片并能在 Markdown 中通过相对路径引用图片。操作步骤在项目目录建一个assets文件夹放入一张图片例如uart_timing.png。点击图片预览确认能正常显示。新建一个 Markdown 文件用相对路径插入图片打开 Markdown 预览确认图片能显示。图片预览本身是 VS Code 的基础能力一般不需要额外插件。问题通常出现在 Markdown 相对路径引用上。判断标准很简单预览里图片不显示先去检查文件路径是否正确再看图片名是否包含中文或空格建议全部改成英文小写加下划线。5.3 Markdown 笔记与任务清单测试Markdown 是这套方案的主线PDF 和 PNG 都是围绕它组织的。测试时重点看任务清单、表格、目录这几项。新建test.md写入# 调试任务 ## 任务进度 - [x] 完成时钟初始化 - [ ] 排查 UART DMA 中断 - [ ] 验证低功耗模式 ## 寄存器记录 | 寄存器 | 地址 | 用途 | | --- | --- | --- | | RCC-CR | 0x40023800 | 时钟控制 | | USART1-BRR | 0x40011008 | 波特率配置 | ## 待确认 - [ ] CAN 过滤器配置打开预览后任务列表应该显示为可勾选的复选框表格正常显示。这一步主要验证 Markdown Preview Enhanced 或内置预览的基本渲染是否正常。如果表格列宽不整齐可以在 VS Code 中安装 Markdown All in One 后用快捷键格式化表格。常用的快捷键是Shift Alt F格式化整个文件也可以选中表格后右键格式化。5.4 Mermaid 流程图渲染测试这是整套组合里最能提升文档可读性的功能之一。把下面内容追加到test.md## UART 发送流程 mermaid flowchart TD A[初始化 UART] -- B[配置波特率] B -- C{检查 TX 空闲} C -- 是 -- D[写入发送寄存器] C -- 否 -- C D -- E[等待发送完成] E -- F[清除中断标志] 保存后打开 Markdown 预览。预期结果是把flowchart TD渲染成一张从上到下的流程图。如果用的是 VS Code 内置 Markdown 预览需要确保bierner.markdown-mermaid扩展已安装。如果用的是 Markdown Preview EnhancedMermaid 代码块通常会被自动渲染。如果图表没有渲染优先检查三点。第一代码块语言标签是否严格写成mermaid。第二Mermaid 语法是否正确比如节点名称不能用中文括号。第三是否在同一文档里存在多个 Markdown 预览扩展扩展之间可能相互冲突。再测一个时序图协议分析里很常用## I2C 读操作时序 mermaid sequenceDiagram participant Master participant Slave Master-Slave: START Slave Address R/W1 Slave--Master: ACK Master-Slave: Register Address Slave--Master: ACK Slave-Master: Data Master--Slave: NACK Master-Slave: STOP 时序图能渲染出来说明 Mermaid 支持的常用图表类型基本正常。后续画状态机图、类图、甘特图思路是一样的。5.5 LaTeX 公式渲染测试嵌入式开发里用到公式的场景不少比如串口波特率计算、ADC 采样值换算、PID 参数调整、电机运动学计算。在test.md里写入公式## 串口波特率计算 $$BaudRate \frac{f_{PCLK}}{16 \times (USARTDIV)}$$ 内联公式示例$USARTDIV 546.875$ ## ADC 电压换算 $$V_{ADC} \frac{ADC\_Value}{4095} \times V_{REF}$$打开预览后块级公式应该居中显示内联公式嵌在文字中。如果公式没有渲染最常见的坑是$和$$的位置写错LaTeX 命令拼写错误或者预览引擎没有启用数学渲染。Markdown Preview Enhanced 通过mathRenderingOption设置渲染引擎KaTeX 速度快MathJax 兼容性广。如果某个公式在 KaTeX 下报错先检查命令是否为常见 LaTeX 命令复杂度很高的公式建议直接改用 MathJax 渲染。5.6 导出效果测试Markdown 写完后最终可能需要交付 HTML 或 PDF。Markdown Preview Enhanced 提供导出功能。操作步骤打开要导出的 Markdown 文件。按Ctrl Shift P输入Markdown Preview Enhanced: Export。选择导出格式常用的是 HTML、PDF、PNG。导出 PDF 时扩展通常会调用本机 Chrome 或 Chromium 完成打印。如果导出失败检查是否安装 Chrome以及扩展是否识别到浏览器路径。如果暂时没有 Chrome可以先导出 HTML再用浏览器打开 HTML 直接打印成 PDF。6. 接口 API 与批量任务6.1 为什么没有 API这套方案是 IDE 内的工作流组织不是独立服务所以没有 HTTP API也没有批量任务队列。这里的“能力”更多体现在导出和文档生成的自动化上。6.2 批量导出与文档自动化如果你有多份 Markdown 文档需要统一交付最轻量的方式是逐个导出也可以把导出动作固化成脚本。比如用 Pandoc 做批量转换把某个目录下所有 Markdown 转成 HTMLfor f in *.md; do pandoc $f -o ${f%.md}.html done如果希望保留 Mermaid 图和 LaTeX 公式更稳妥的方案是先用 Markdown Preview Enhanced 导出而不是直接依赖 Pandoc。Pandoc 对 Mermaid 代码块的处理不如 IDE 扩展直接批量导出时要注意图表是否被正确渲染。如果你的团队有文档站比如 VuePress、docsify、SphinxMarkdown 文件本身就可以作为文档源文件。嵌入式项目里常见的做法是代码仓库里维护docs目录所有 Markdown 都按统一规范编写提交后由 CI 自动构建成 HTML 文档站。6.3 建议的发布链路嵌入式项目文档可以分成三层。第一层是仓库内 README记录项目怎么编译、怎么烧录、怎么验证。第二层是模块文档每个外设驱动或独立模块维护一个 Markdown 说明包含寄存器配置、状态机、时序图。第三层是调试记录记录实际遇到的现象、排查过程和分析结论。这三层都可以用同一套 Markdown Mermaid LaTeX 方案维护。区别只在于发布粒度README 直接放在仓库根目录模块文档放在模块目录下调试记录可以作为独立文件归档。对外交付需要正式格式时再从 Markdown 导出 HTML 或 PDF。7. 资源占用与性能观察这套方案不涉及 GPU资源占用主要体现在内存和 CPU 上。不需要特别强的电脑但如果同时打开很多大型文件仍然会出现卡顿。7.1 观察方式在 Windows 下打开任务管理器在 macOS 下打开活动监视器在 Linux 下可以用命令观察top -o %MEM重点观察两个进程VS Code 主进程和渲染进程。预览面板开得越多渲染进程的内存占用越高。7.2 主要资源消耗点PDF 文件几十 MB 的大手册打开后内存占用会比较明显翻页时会有短暂加载。图片预览高分辨率 PNG 在编辑器内滚动时可能会有轻微延迟图片尺寸过大时更明显。Markdown 预览预览面板是一个独立渲染页面打开以后会持续占用内存。Mermaid 图复杂流程图或时序图在编辑时如果频繁刷新字体引擎和布局计算会造成 CPU 短暂升高。LaTeX 公式大量块级公式同时渲染时KaTeX 和 MathJax 都有一定的计算成本KaTeX 通常会快一些。7.3 降低占用的技巧不同时打开多个大型 PDF。IDE 内 PDF 查看适合临时查阅长时间精读还是放到专业阅读器。截图先用工具压缩。嵌入式开发里截图往往很大比如 4K 屏幕下的逻辑分析仪截图可能有几 MB拖进 IDE 后影响滚动流畅度。统一用截图工具或批处理压缩到合适尺寸。预览用后即关。不要一直挂着多个 Markdown 预览面板不写文档时把预览关掉。Mermaid 图不要过分复杂。一张图几十个节点、几十条边预览和后续维护都会费劲。复杂逻辑拆成多张小图。减少无用插件。VS Code 装得越重编辑器启动和文件响应越慢。只保留高频使用的扩展。8. 常见问题与排查方法问题现象可能原因排查方式解决方案Mermaid 图不渲染未安装 Mermaid 支持扩展、语法错误、多个预览扩展冲突查看预览控制台报错检查代码块语言标签安装bierner.markdown-mermaid或改用 Markdown Preview Enhanced 预览修正语法LaTeX 公式不显示数学渲染未开启、公式符号错误、预览引擎不支持检查markdown.math.enabled设置检查$和$$分隔符启用数学渲染改用 Markdown Preview Enhanced修正 LaTeX 命令PDF 打开空白PDF 扩展未安装、插件视图异常、文件损坏重启 VS Code用外部阅读器打开同一文件验证安装 vscode-pdf 扩展重新打开文件确认文件未损坏PNG 点击无反应图片过大、文件类型异常、插件冲突在系统资源管理器中打开同一图片压缩图片用浏览器打开检查文件扩展名图片在 Markdown 预览里不显示相对路径错误、图片名中文或空格、文件被移动在 Markdown 源码中点击路径确认文件存在统一将图片放assets目录使用./assets/文件名.png格式CtrlK V 快捷键无效快捷键被占用或未生效在命令面板执行“打开侧边预览”验证功能打开快捷键设置重新绑定markdown.showPreviewToSide导出 PDF 失败本机未安装 Chrome、浏览器路径未识别查看导出日志确认 Chrome 是否存在安装 Chrome或先导出 HTML再从浏览器打印为 PDFMarkdown 中文乱码文件编码不是 UTF-8检查编辑器右下角编码提示统一保存为 UTF-8同目录下打开多个 Markdown 预览卡顿预览面板过多、文件过大关闭多余预览面板一次只打开一个预览拆分成多个小文件嵌入式 IDE 无法安装插件IDE 未开放插件市场、网络受限确认 IDE 插件来源下载 vsix 文件离线安装9. 最佳实践与使用建议9.1 目录结构规范嵌入式项目建议把文档和代码放在同一个仓库里目录结构可以是project_root/ ├── README.md ├── docs/ │ ├── datasheet/ │ ├── protocol/ │ └── debug_notes/ ├── assets/ │ ├── uart_timing.png │ ├── adc_circuit.png │ └── logic_analyzer.png ├── src/ ├── inc/ └── test/要点是图片统一放assetsPDF 资料统一放docs/datasheet调试记录放docs/debug_notes。这样时间久了文件名不会乱换人接手时也能快速找到资料。9.2 写作与协作建议每个驱动模块或硬件模块维护一个独立 Markdown 文件文件名用英文小写加下划线。Markdown 里第一行写模块名第二行写维护人和日期方便追溯。Mermaid 图只画关键流程不要画满屏节点。图是给人看的不是炫技。LaTeX 公式先在本地预览确认渲染正常再提交到仓库。文档跟着代码一起走 Git提交信息写清楚改了什么。硬件资料如果体积大可以考虑用 Git LFS 管理。团队协作时约定一套 Markdown 模板要求每个 README 都包含“功能说明、引脚配置、使用示例、注意事项”这几个小节。如果团队用飞书或其他平台协作把这些 Markdown 内容同步到在线文档时通常需要手动转换格式。飞书对mermaid代码块的解析依赖第三方插件跨平台发布前先确认目标平台支持。9.3 版权与安全边界这套工作流里的资料大多数是芯片数据手册、自己的原理图截图、调试记录。数据手册一般有版权声明可以内部查阅但不能随意重新发布到公开博客或公开仓库。原理图、PCB 截图可能涉及公司核心技术不要放进公开仓库。涉及客户资料、保密协议的文档更不能混入开源工程。另外如果你把调试过程写成博客文章注意隐藏敏感信息比如工程路径、内部 IP、序列号、未公开的芯片信息。截图里的芯片丝印、Board ID、调试串口日志等都可能泄露信息发布前要统一检查。10. 总结与下一步这套方案最值得尝试的点不是单个功能有多强而是它把嵌入式开发中最常用的四种文档操作合并到了一个 IDE 环境里PDF 数据手册阅读、PNG 截图查看、Markdown 笔记、Mermaid 和 LaTeX 渲染。实际使用时最大的收益是注意力不用频繁切换代码和资料在同一套目录里管理长期下来比“桌面一堆 PDF 和截图”好维护得多。建议先按上面第 5 章的步骤做一遍验证特别是test.md里的 Mermaid 图和 LaTeX 公式这两项是整套方案是否能跑通的关键。最容易踩的坑有两个一个是 Mermaid 不渲染大概率是扩展没装齐或者预览引擎不对另一个是导出 PDF 失败大概率是本机没有 Chrome。把这两个问题提前解决后面的使用就很顺畅。后续可以继续扩展的方向包括把 docs 目录接进 docsify 或 VuePress做成团队内部文档站把 Markdown 检查加入 CI统一格式配合 Doxygen 生成代码注释文档再把 Doxygen 输出和 Markdown 文档链接起来。先从一个模块的调试记录开始用用顺了再逐步把整个工程资料搬进来。
