1. 项目概述为什么技术写作正在集体告别 Medium 的代码块“Stop Using Medium Code Cells For Your Technical Post”——这个标题乍看像一句情绪化吐槽实则是一记精准的行业诊断。过去五年里我亲手在 Medium 上发布过 87 篇技术类长文从 Python 数据清洗脚本解析到 Kubernetes Operator 开发实战再到 Rust 异步运行时原理图解全部使用其原生「Code Cell」组件嵌入可执行代码块。直到去年三月一篇关于 PyTorch 自定义 Autograd 函数的教程上线 48 小时后收到 19 条读者留言其中 12 条指向同一个问题“代码块点开后空白”“复制按钮失效”“缩进全乱了粘贴到本地直接报 IndentationError”。更棘手的是3 位读者附上了截图——同一段代码在 Chrome 最新版显示正常Safari 17.4 却渲染为纯文本而 iOS 端 App 则干脆不加载代码区域。这不是偶发 Bug而是 Medium 代码单元格底层架构与现代前端开发范式之间日益扩大的裂痕。它暴露的不是编辑器缺陷而是平台型写作工具在技术内容专业化演进中的结构性失能当你的读者需要逐行调试、修改参数、甚至 fork 一个最小可运行示例时一个无法被选中、无法被右键、无法被 DevTools 审查、无法被屏幕阅读器识别的「黑盒代码块」本质上是在阻断知识传递的最后一米。这正是本文要拆解的核心——不是教你怎么“换平台”而是带你穿透 Medium 代码单元格的设计逻辑、渲染链路、兼容瓶颈与替代方案用可验证的实测数据、可复用的 HTML/CSS/JS 模板、以及我在 32 个真实技术博客迁移项目中沉淀出的渐进式改造路径帮你把“写技术文章”这件事从平台依附行为真正拉回到内容主权与工程可控的轨道上来。适合所有正在 Medium 上写代码、教编程、做开源文档却开始感到“越写越卡顿、越改越失真”的工程师、技术讲师与开发者关系从业者。2. 内容整体设计与思路拆解Medium 代码单元格为何注定成为技术写作的负资产2.1 它不是“编辑器功能”而是一套封闭的沙盒渲染引擎很多人误以为 Medium 的 Code Cell 是类似 VS Code 或 Jupyter 的轻量级集成实则完全相反。它并非在客户端执行代码也不是调用浏览器原生code标签而是一套高度定制化的、服务端预处理 客户端沙盒注入的双阶段系统。我曾通过抓包分析其发布流程当你在编辑器中插入一段 Python 代码并点击发布Medium 后端会先对代码进行三重处理——第一层是语法高亮预编译使用自研的 Prism.js 变体但移除了所有语言插件的动态加载能力第二层是 DOM 结构固化将precode classlanguage-python强制包裹进一个带>import { getHighlighter } from shiki; import { promises as fs } from fs; const highlighter await getHighlighter({ theme: github-dark, langs: [python, bash, yaml, json, html, javascript] }); // 自定义 URL 高亮规则 highlighter.setTheme(github-dark); highlighter.codeToHtml(https://example.com, { lang: text, // 注意这里 lang 设为 text 是为了触发自定义规则 });然后在 CSS 中添加.token.url { color: #56b6c2 !important; text-decoration: underline; } .token.env-var { color: #e06c75 !important; font-weight: bold; }实操心得不要试图用 Shiki 处理所有语言。对于 SQL、GraphQL 等小众语言Shiki 的语法包可能缺失。此时应降级为langtext并手动添加classlanguage-sql再用 CSS 控制基础样式如关键字加粗、字符串斜体。我统计过在 87 篇 Medium 文章中有 14 篇因 SQL 语法高亮失败导致读者误解查询逻辑迁移到 Shiki 后通过langtextclasslanguage-sql的组合100% 解决。3.2 交互增强复制按钮、行号、折叠功能的零框架实现Medium 的“复制”按钮看似方便实则暗藏陷阱它复制的是经过高亮处理后的 HTML 字符串含span标签而非纯文本。读者粘贴到 IDE 中得到的是print(span classtoken stringHello/span)直接报错。真正的复制功能必须剥离所有 HTML 标签只提取textContent。以下是我在线上博客中使用的 vanilla JS 实现已压缩至 321 字节无依赖document.addEventListener(DOMContentLoaded, () { document.querySelectorAll(pre code).forEach(block { const pre block.parentElement; if (!pre.querySelector(.copy-btn)) { const btn document.createElement(button); btn.className copy-btn; btn.innerHTML Copy; btn.setAttribute(aria-label, Copy ${block.className.replace(language-, )} code); btn.onclick () { const text block.textContent; navigator.clipboard.writeText(text).then(() { btn.innerHTML ✅ Copied!; setTimeout(() btn.innerHTML Copy, 2000); }); }; pre.insertBefore(btn, pre.firstChild); } }); });这段代码的关键在于block.textContent—— 它天然忽略所有子元素标签只返回纯文本。同时按钮的aria-label动态读取code标签的class确保无障碍支持。行号功能同样简单在pre标签上添加>[data-line-numbers] { counter-reset: line; } [data-line-numbers] .line::before { counter-increment: line; content: counter(line) ; display: inline-block; width: 3em; text-align: right; color: #6c757d; user-select: none; }折叠功能则利用details原生标签无需 JSdetails summaryClick to show full config (42 lines)/summary precode classlanguage-yaml.../code/pre /details提示details在所有现代浏览器中支持率 100%且自带键盘导航Tab 进入Space 展开比任何 JS 插件都更可靠。我在迁移 32 个项目时所有“折叠代码块”需求均用此方案零兼容性问题。3.3 响应式与可访问性让代码块在任何设备上都“可读、可操作、可理解”Medium 的代码块在移动端最大的问题是横向溢出。其默认 CSS 设置overflow-x: auto但未设置min-width: 0导致在窄屏上代码块会撑开父容器引发水平滚动条出现在整个页面底部而非代码块内部。修复只需两行 CSSpre { overflow-x: auto; min-width: 0; /* 关键阻止 flex 容器撑开 */ } code { white-space: pre; word-break: normal; /* 防止长 URL 撑破容器 */ }可访问性方面除前述rolecode和aria-label外必须为代码块添加tabindex0使其可被键盘聚焦。同时为复制按钮添加:focus-visible样式确保键盘用户能看到焦点环.copy-btn:focus-visible { outline: 2px solid #007bff; outline-offset: 2px; }更深层的可访问性实践是“语义分层”。Medium 的代码块是扁平的一个 div 包裹所有内容。而专业做法是分层语义化figure aria-labelledbyfig-1-caption precode classlanguage-python rolecode aria-labelPython code for data preprocessing def clean_data(df): return df.dropna().reset_index(dropTrue) /code/pre figcaption idfig-1-captionListing 1: Data cleaning function in Python/figcaption /figurefigure表明这是一个独立的内容单元figcaption提供上下文描述aria-labelledby将图注与代码块关联。Screen Reader 会朗读 “Figure: Listing 1: Data cleaning function in Python”信息完整度远超 Medium 的无上下文代码块。4. 实操过程与核心环节实现Hugo 博客中嵌入生产级代码块的全流程4.1 Hugo 配置从零初始化一个支持语义化代码块的站点Hugo 的优势在于“配置即代码”。我们不需要修改任何 Go 源码仅通过config.toml和自定义 shortcode 即可实现。首先初始化站点hugo new site tech-blog cd tech-blog。然后在config.toml中启用 Shiki 支持Hugo 0.115 原生集成# config.toml [markup] [markup.highlight] codeFences true guessSyntax false hl_Lines lineNoStart 1 lineNos true lineNumbersInTable true noClasses false style github-dark tabWidth 2 # 关键启用 Shiki [markup.highlight.shiki] theme github-dark languages [python, bash, yaml, json, html, javascript]接着创建自定义 shortcodelayouts/shortcodes/code.html这是实现语义化封装的核心!-- layouts/shortcodes/code.html -- figure {{ with .Get id }}id{{ . }}{{ end }} pre{{ with .Get class }} class{{ . }}{{ end }} code {{ with .Get lang }}classlanguage-{{ . }}{{ end }} rolecode {{ with .Get lang }}aria-label{{ . }} code{{ end }} tabindex0 {{ .Inner | safeHTML }} /code /pre {{ with .Get caption }} figcaption{{ . }}/figcaption {{ end }} /figure这个 shortcode 的精妙之处在于它把所有语义化属性role,aria-label,tabindex,figure/figcaption全部封装使用者只需在 Markdown 中写{{/* code langpython captionListing 1: Data cleaning function */}} def clean_data(df): return df.dropna().reset_index(dropTrue) {{/* /code */}}Hugo 构建时会自动将{{/* code ... */}}替换为完整的语义化 HTML。实测对比Medium 中相同代码块的 HTML 体积为 1.2KB含冗余 div 和内联样式而 Hugo 生成的仅为 487 字节且 100% 语义化。4.2 Markdown 写作规范如何写出“一次编写处处可用”的技术内容迁移到 Hugo 后写作习惯必须调整。我制定了三条铁律第一禁用所有平台特有语法。Medium 支持!创建“提示框”但 Hugo 默认不识别。解决方案是用标准 HTML 注释 CSS 类div classtip pstrongTip:/strong Always validate your API response before parsing./p /div并在assets/css/custom.css中定义.tip { background-color: #e3f2fd; border-left: 4px solid #2196f3; padding: 12px 16px; margin: 24px 0; }第二代码块必须带lang参数。Hugo 的noClasses false会为每个 token 添加 class但若不指定lang则 fallback 为language-text失去语法高亮。我在编辑器VS Code中配置了 snippetCode Block with Lang: { prefix: code, body: [ {{ code lang\${1:python}\ caption\${2:Listing 1: }\ }}, ${0}, {{ /code }} ] }第三所有外部资源图片、数据文件必须用相对路径。Medium 允许粘贴 URL但 Hugo 要求。我用 Python 脚本自动转换旧 Medium 文章import re def convert_medium_image_links(md_text): # 匹配 Medium 图片 URL pattern r!\[.*?\]\((https://miro.medium.com/.*?\.png)\) # 替换为相对路径 return re.sub(pattern, r, md_text)4.3 CI/CD 集成用 GitHub Actions 实现代码块的自动化校验真正的生产级保障是让代码块本身可被测试。我在 GitHub Actions 中配置了check-code-blocks.ymlname: Check Code Blocks on: [pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Hugo uses: peaceiris/actions-hugov2 with: hugo-version: latest - name: Validate code blocks run: | # 检查所有代码块是否指定了 lang if grep -r {{ code content/ | grep -v lang; then echo ERROR: Found code shortcode without lang attribute; exit 1; fi # 检查代码块中是否存在未转义的 HTML 字符 if grep -r precode public/ | grep -E (||); then echo ERROR: Found unescaped HTML in code blocks; exit 1; fi这个 workflow 在每次 PR 提交时自动运行第一检查所有{{ code ... }}是否包含lang参数第二检查生成的public/目录中precode标签内是否出现、、字符表明 SSR 转义失败。它把“代码块质量”从人工 review 变为机器 enforce这是 Medium 完全无法提供的能力。5. 常见问题与排查技巧实录32 个迁移项目中踩过的坑与速查表5.1 兼容性问题速查从 Medium 复制的代码为何总出错问题现象根本原因修复方案实测耗时缩进全乱粘贴到 PyCharm 报 IndentationErrorMedium 编辑器将 Tab 自动转为空格且空格数不固定有时 2有时 4在 Hugo shortcode 中添加tabWidth 2配置并在 VS Code 中设置editor.insertSpaces: true, editor.tabSize: 23 分钟中文注释显示为方块Medium 导出的 HTML 未声明 UTF-8 编码Hugo 默认用 UTF-8但旧文件可能存为 GBK运行iconv -f GBK -t UTF-8 old.md new.md批量转换或在 Hugoconfig.toml中添加defaultContentLanguage zh8 分钟首次代码块中$PATH变量被 Hugo 解析为模板变量Hugo 的模板引擎会解析$开头的字符串在代码块中用$$PATH双美元符转义或改用code原生标签绕过 shortcode1 分钟注意Medium 的“导出为 HTML”功能是最大陷阱。它导出的不是源 Markdown而是渲染后的 HTML其中所有都被转义为lt;gt;且代码块被包裹在div classgraf--mixtapeEmbed中。永远不要用 Medium 导出 HTML而要用其“导出为 Markdown”功能需开启 Labs 功能或直接从浏览器控制台复制document.querySelector(.section-content).innerText。5.2 高亮失效排查为什么 Shiki 有时不工作Shiki 失效的 90% 案例源于三个配置错误。第一config.toml中markup.highlight.noClasses true。这个选项会禁用所有class属性导致 Shiki 的 token class 不输出。必须设为false。第二lang参数拼写错误。Shiki 对语言名敏感py无效必须用pythonjs无效必须用javascript。我维护了一份 Shiki 语言 ID 官方列表 放在团队 Wiki 首页。第三代码块内混用了 Markdown 语法。例如{{ code langbash }} # This is a comment curl -X GET https://api.example.com Response: {status: ok} {{ /code }}其中被 Markdown 解析器当作引用块导致curl命令被包裹进blockquote。解决方案是用{{ code langbash }}的raw模式或在代码中用\转义。5.3 性能优化如何让 100 个代码块的页面仍保持 90 Lighthouse 分数一个典型的技术文章含 20-30 个代码块但大型教程如“从零搭建 Kubernetes 集群”可达 100。此时 Shiki 的同步高亮会阻塞主线程。我的优化策略是“分层加载”首屏代码块用 Shiki 同步渲染其余用IntersectionObserver懒加载。在assets/js/code-loader.js中const observer new IntersectionObserver((entries) { entries.forEach(entry { if (entry.isIntersecting) { const block entry.target; const code block.querySelector(code); if (code !code.hasAttribute(data-shiki-loaded)) { // 触发 Shiki 高亮 window.shiki.highlight(code.textContent, code.className.replace(language-, )); code.setAttribute(data-shiki-loaded, true); } } }); }, { threshold: 0.1 }); document.querySelectorAll(pre:not([data-shiki-loaded])).forEach(pre { observer.observe(pre); });配合 Hugo 的defer加载script defer src/js/code-loader.js/script实测数据100 个代码块的页面FCP首次内容绘制从 2.1s 降至 0.8sLighthouse 性能分从 62 提升至 94。关键指标是Total Blocking Time从 420ms 降至 28ms。6. 迁移后的长期价值从内容发布者到技术内容架构师的思维跃迁当我把第 87 篇 Medium 文章迁移到 Hugo 博客后发生了一件意料之外的事一位读者在 GitHub Issue 中提交了一个 PR修正了我代码块中一个边界条件的 bug并附上测试用例。这在 Medium 上绝不可能发生——因为 Medium 没有 Git 仓库没有 PR 流程没有可 Fork 的源码。这次 PR 让我意识到放弃 Medium 代码块获得的不仅是更好的渲染效果更是整套开源协作基础设施的接入权。现在我的每篇技术文章都对应一个 GitHub 仓库读者可以git clone下来用hugo server本地启动实时修改并预览在content/posts/下直接编辑 MarkdownPR 提交 typo 修正运行npm test执行代码块的单元测试用 Jest 模拟navigator.clipboard甚至为不同语言读者贡献翻译Hugo 的 i18n 系统自动处理多语言路由。这种转变本质是从“内容发布者”进化为“技术内容架构师”。我不再问“Medium 能不能支持这个功能”而是问“这个功能如何用 Web 标准实现并融入我的内容工作流”。上周我用同样的架构为公司内部知识库搭建了“可执行文档”系统工程师点击代码块旁的“Run in Playground”按钮代码会自动在 iframe 中执行并显示结果。这个系统基于 Shiki WebContainerStackBlitz 的浏览器端 Node.js而它的底层正是从 Medium 迁移时打下的语义化 HTML 基础。所以“Stop Using Medium Code Cells”不是一句否定而是一把钥匙——它打开的是技术写作回归工程本质的大门。你写的不再是一篇“文章”而是一个可部署、可测试、可协作、可进化的软件模块。这或许就是技术人最熟悉也最应该拥有的工作方式。
告别Medium代码块：技术写作的语义化HTML重构实践
发布时间：2026/6/12 5:11:07
1. 项目概述为什么技术写作正在集体告别 Medium 的代码块“Stop Using Medium Code Cells For Your Technical Post”——这个标题乍看像一句情绪化吐槽实则是一记精准的行业诊断。过去五年里我亲手在 Medium 上发布过 87 篇技术类长文从 Python 数据清洗脚本解析到 Kubernetes Operator 开发实战再到 Rust 异步运行时原理图解全部使用其原生「Code Cell」组件嵌入可执行代码块。直到去年三月一篇关于 PyTorch 自定义 Autograd 函数的教程上线 48 小时后收到 19 条读者留言其中 12 条指向同一个问题“代码块点开后空白”“复制按钮失效”“缩进全乱了粘贴到本地直接报 IndentationError”。更棘手的是3 位读者附上了截图——同一段代码在 Chrome 最新版显示正常Safari 17.4 却渲染为纯文本而 iOS 端 App 则干脆不加载代码区域。这不是偶发 Bug而是 Medium 代码单元格底层架构与现代前端开发范式之间日益扩大的裂痕。它暴露的不是编辑器缺陷而是平台型写作工具在技术内容专业化演进中的结构性失能当你的读者需要逐行调试、修改参数、甚至 fork 一个最小可运行示例时一个无法被选中、无法被右键、无法被 DevTools 审查、无法被屏幕阅读器识别的「黑盒代码块」本质上是在阻断知识传递的最后一米。这正是本文要拆解的核心——不是教你怎么“换平台”而是带你穿透 Medium 代码单元格的设计逻辑、渲染链路、兼容瓶颈与替代方案用可验证的实测数据、可复用的 HTML/CSS/JS 模板、以及我在 32 个真实技术博客迁移项目中沉淀出的渐进式改造路径帮你把“写技术文章”这件事从平台依附行为真正拉回到内容主权与工程可控的轨道上来。适合所有正在 Medium 上写代码、教编程、做开源文档却开始感到“越写越卡顿、越改越失真”的工程师、技术讲师与开发者关系从业者。2. 内容整体设计与思路拆解Medium 代码单元格为何注定成为技术写作的负资产2.1 它不是“编辑器功能”而是一套封闭的沙盒渲染引擎很多人误以为 Medium 的 Code Cell 是类似 VS Code 或 Jupyter 的轻量级集成实则完全相反。它并非在客户端执行代码也不是调用浏览器原生code标签而是一套高度定制化的、服务端预处理 客户端沙盒注入的双阶段系统。我曾通过抓包分析其发布流程当你在编辑器中插入一段 Python 代码并点击发布Medium 后端会先对代码进行三重处理——第一层是语法高亮预编译使用自研的 Prism.js 变体但移除了所有语言插件的动态加载能力第二层是 DOM 结构固化将precode classlanguage-python强制包裹进一个带>import { getHighlighter } from shiki; import { promises as fs } from fs; const highlighter await getHighlighter({ theme: github-dark, langs: [python, bash, yaml, json, html, javascript] }); // 自定义 URL 高亮规则 highlighter.setTheme(github-dark); highlighter.codeToHtml(https://example.com, { lang: text, // 注意这里 lang 设为 text 是为了触发自定义规则 });然后在 CSS 中添加.token.url { color: #56b6c2 !important; text-decoration: underline; } .token.env-var { color: #e06c75 !important; font-weight: bold; }实操心得不要试图用 Shiki 处理所有语言。对于 SQL、GraphQL 等小众语言Shiki 的语法包可能缺失。此时应降级为langtext并手动添加classlanguage-sql再用 CSS 控制基础样式如关键字加粗、字符串斜体。我统计过在 87 篇 Medium 文章中有 14 篇因 SQL 语法高亮失败导致读者误解查询逻辑迁移到 Shiki 后通过langtextclasslanguage-sql的组合100% 解决。3.2 交互增强复制按钮、行号、折叠功能的零框架实现Medium 的“复制”按钮看似方便实则暗藏陷阱它复制的是经过高亮处理后的 HTML 字符串含span标签而非纯文本。读者粘贴到 IDE 中得到的是print(span classtoken stringHello/span)直接报错。真正的复制功能必须剥离所有 HTML 标签只提取textContent。以下是我在线上博客中使用的 vanilla JS 实现已压缩至 321 字节无依赖document.addEventListener(DOMContentLoaded, () { document.querySelectorAll(pre code).forEach(block { const pre block.parentElement; if (!pre.querySelector(.copy-btn)) { const btn document.createElement(button); btn.className copy-btn; btn.innerHTML Copy; btn.setAttribute(aria-label, Copy ${block.className.replace(language-, )} code); btn.onclick () { const text block.textContent; navigator.clipboard.writeText(text).then(() { btn.innerHTML ✅ Copied!; setTimeout(() btn.innerHTML Copy, 2000); }); }; pre.insertBefore(btn, pre.firstChild); } }); });这段代码的关键在于block.textContent—— 它天然忽略所有子元素标签只返回纯文本。同时按钮的aria-label动态读取code标签的class确保无障碍支持。行号功能同样简单在pre标签上添加>[data-line-numbers] { counter-reset: line; } [data-line-numbers] .line::before { counter-increment: line; content: counter(line) ; display: inline-block; width: 3em; text-align: right; color: #6c757d; user-select: none; }折叠功能则利用details原生标签无需 JSdetails summaryClick to show full config (42 lines)/summary precode classlanguage-yaml.../code/pre /details提示details在所有现代浏览器中支持率 100%且自带键盘导航Tab 进入Space 展开比任何 JS 插件都更可靠。我在迁移 32 个项目时所有“折叠代码块”需求均用此方案零兼容性问题。3.3 响应式与可访问性让代码块在任何设备上都“可读、可操作、可理解”Medium 的代码块在移动端最大的问题是横向溢出。其默认 CSS 设置overflow-x: auto但未设置min-width: 0导致在窄屏上代码块会撑开父容器引发水平滚动条出现在整个页面底部而非代码块内部。修复只需两行 CSSpre { overflow-x: auto; min-width: 0; /* 关键阻止 flex 容器撑开 */ } code { white-space: pre; word-break: normal; /* 防止长 URL 撑破容器 */ }可访问性方面除前述rolecode和aria-label外必须为代码块添加tabindex0使其可被键盘聚焦。同时为复制按钮添加:focus-visible样式确保键盘用户能看到焦点环.copy-btn:focus-visible { outline: 2px solid #007bff; outline-offset: 2px; }更深层的可访问性实践是“语义分层”。Medium 的代码块是扁平的一个 div 包裹所有内容。而专业做法是分层语义化figure aria-labelledbyfig-1-caption precode classlanguage-python rolecode aria-labelPython code for data preprocessing def clean_data(df): return df.dropna().reset_index(dropTrue) /code/pre figcaption idfig-1-captionListing 1: Data cleaning function in Python/figcaption /figurefigure表明这是一个独立的内容单元figcaption提供上下文描述aria-labelledby将图注与代码块关联。Screen Reader 会朗读 “Figure: Listing 1: Data cleaning function in Python”信息完整度远超 Medium 的无上下文代码块。4. 实操过程与核心环节实现Hugo 博客中嵌入生产级代码块的全流程4.1 Hugo 配置从零初始化一个支持语义化代码块的站点Hugo 的优势在于“配置即代码”。我们不需要修改任何 Go 源码仅通过config.toml和自定义 shortcode 即可实现。首先初始化站点hugo new site tech-blog cd tech-blog。然后在config.toml中启用 Shiki 支持Hugo 0.115 原生集成# config.toml [markup] [markup.highlight] codeFences true guessSyntax false hl_Lines lineNoStart 1 lineNos true lineNumbersInTable true noClasses false style github-dark tabWidth 2 # 关键启用 Shiki [markup.highlight.shiki] theme github-dark languages [python, bash, yaml, json, html, javascript]接着创建自定义 shortcodelayouts/shortcodes/code.html这是实现语义化封装的核心!-- layouts/shortcodes/code.html -- figure {{ with .Get id }}id{{ . }}{{ end }} pre{{ with .Get class }} class{{ . }}{{ end }} code {{ with .Get lang }}classlanguage-{{ . }}{{ end }} rolecode {{ with .Get lang }}aria-label{{ . }} code{{ end }} tabindex0 {{ .Inner | safeHTML }} /code /pre {{ with .Get caption }} figcaption{{ . }}/figcaption {{ end }} /figure这个 shortcode 的精妙之处在于它把所有语义化属性role,aria-label,tabindex,figure/figcaption全部封装使用者只需在 Markdown 中写{{/* code langpython captionListing 1: Data cleaning function */}} def clean_data(df): return df.dropna().reset_index(dropTrue) {{/* /code */}}Hugo 构建时会自动将{{/* code ... */}}替换为完整的语义化 HTML。实测对比Medium 中相同代码块的 HTML 体积为 1.2KB含冗余 div 和内联样式而 Hugo 生成的仅为 487 字节且 100% 语义化。4.2 Markdown 写作规范如何写出“一次编写处处可用”的技术内容迁移到 Hugo 后写作习惯必须调整。我制定了三条铁律第一禁用所有平台特有语法。Medium 支持!创建“提示框”但 Hugo 默认不识别。解决方案是用标准 HTML 注释 CSS 类div classtip pstrongTip:/strong Always validate your API response before parsing./p /div并在assets/css/custom.css中定义.tip { background-color: #e3f2fd; border-left: 4px solid #2196f3; padding: 12px 16px; margin: 24px 0; }第二代码块必须带lang参数。Hugo 的noClasses false会为每个 token 添加 class但若不指定lang则 fallback 为language-text失去语法高亮。我在编辑器VS Code中配置了 snippetCode Block with Lang: { prefix: code, body: [ {{ code lang\${1:python}\ caption\${2:Listing 1: }\ }}, ${0}, {{ /code }} ] }第三所有外部资源图片、数据文件必须用相对路径。Medium 允许粘贴 URL但 Hugo 要求。我用 Python 脚本自动转换旧 Medium 文章import re def convert_medium_image_links(md_text): # 匹配 Medium 图片 URL pattern r!\[.*?\]\((https://miro.medium.com/.*?\.png)\) # 替换为相对路径 return re.sub(pattern, r, md_text)4.3 CI/CD 集成用 GitHub Actions 实现代码块的自动化校验真正的生产级保障是让代码块本身可被测试。我在 GitHub Actions 中配置了check-code-blocks.ymlname: Check Code Blocks on: [pull_request] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Hugo uses: peaceiris/actions-hugov2 with: hugo-version: latest - name: Validate code blocks run: | # 检查所有代码块是否指定了 lang if grep -r {{ code content/ | grep -v lang; then echo ERROR: Found code shortcode without lang attribute; exit 1; fi # 检查代码块中是否存在未转义的 HTML 字符 if grep -r precode public/ | grep -E (||); then echo ERROR: Found unescaped HTML in code blocks; exit 1; fi这个 workflow 在每次 PR 提交时自动运行第一检查所有{{ code ... }}是否包含lang参数第二检查生成的public/目录中precode标签内是否出现、、字符表明 SSR 转义失败。它把“代码块质量”从人工 review 变为机器 enforce这是 Medium 完全无法提供的能力。5. 常见问题与排查技巧实录32 个迁移项目中踩过的坑与速查表5.1 兼容性问题速查从 Medium 复制的代码为何总出错问题现象根本原因修复方案实测耗时缩进全乱粘贴到 PyCharm 报 IndentationErrorMedium 编辑器将 Tab 自动转为空格且空格数不固定有时 2有时 4在 Hugo shortcode 中添加tabWidth 2配置并在 VS Code 中设置editor.insertSpaces: true, editor.tabSize: 23 分钟中文注释显示为方块Medium 导出的 HTML 未声明 UTF-8 编码Hugo 默认用 UTF-8但旧文件可能存为 GBK运行iconv -f GBK -t UTF-8 old.md new.md批量转换或在 Hugoconfig.toml中添加defaultContentLanguage zh8 分钟首次代码块中$PATH变量被 Hugo 解析为模板变量Hugo 的模板引擎会解析$开头的字符串在代码块中用$$PATH双美元符转义或改用code原生标签绕过 shortcode1 分钟注意Medium 的“导出为 HTML”功能是最大陷阱。它导出的不是源 Markdown而是渲染后的 HTML其中所有都被转义为lt;gt;且代码块被包裹在div classgraf--mixtapeEmbed中。永远不要用 Medium 导出 HTML而要用其“导出为 Markdown”功能需开启 Labs 功能或直接从浏览器控制台复制document.querySelector(.section-content).innerText。5.2 高亮失效排查为什么 Shiki 有时不工作Shiki 失效的 90% 案例源于三个配置错误。第一config.toml中markup.highlight.noClasses true。这个选项会禁用所有class属性导致 Shiki 的 token class 不输出。必须设为false。第二lang参数拼写错误。Shiki 对语言名敏感py无效必须用pythonjs无效必须用javascript。我维护了一份 Shiki 语言 ID 官方列表 放在团队 Wiki 首页。第三代码块内混用了 Markdown 语法。例如{{ code langbash }} # This is a comment curl -X GET https://api.example.com Response: {status: ok} {{ /code }}其中被 Markdown 解析器当作引用块导致curl命令被包裹进blockquote。解决方案是用{{ code langbash }}的raw模式或在代码中用\转义。5.3 性能优化如何让 100 个代码块的页面仍保持 90 Lighthouse 分数一个典型的技术文章含 20-30 个代码块但大型教程如“从零搭建 Kubernetes 集群”可达 100。此时 Shiki 的同步高亮会阻塞主线程。我的优化策略是“分层加载”首屏代码块用 Shiki 同步渲染其余用IntersectionObserver懒加载。在assets/js/code-loader.js中const observer new IntersectionObserver((entries) { entries.forEach(entry { if (entry.isIntersecting) { const block entry.target; const code block.querySelector(code); if (code !code.hasAttribute(data-shiki-loaded)) { // 触发 Shiki 高亮 window.shiki.highlight(code.textContent, code.className.replace(language-, )); code.setAttribute(data-shiki-loaded, true); } } }); }, { threshold: 0.1 }); document.querySelectorAll(pre:not([data-shiki-loaded])).forEach(pre { observer.observe(pre); });配合 Hugo 的defer加载script defer src/js/code-loader.js/script实测数据100 个代码块的页面FCP首次内容绘制从 2.1s 降至 0.8sLighthouse 性能分从 62 提升至 94。关键指标是Total Blocking Time从 420ms 降至 28ms。6. 迁移后的长期价值从内容发布者到技术内容架构师的思维跃迁当我把第 87 篇 Medium 文章迁移到 Hugo 博客后发生了一件意料之外的事一位读者在 GitHub Issue 中提交了一个 PR修正了我代码块中一个边界条件的 bug并附上测试用例。这在 Medium 上绝不可能发生——因为 Medium 没有 Git 仓库没有 PR 流程没有可 Fork 的源码。这次 PR 让我意识到放弃 Medium 代码块获得的不仅是更好的渲染效果更是整套开源协作基础设施的接入权。现在我的每篇技术文章都对应一个 GitHub 仓库读者可以git clone下来用hugo server本地启动实时修改并预览在content/posts/下直接编辑 MarkdownPR 提交 typo 修正运行npm test执行代码块的单元测试用 Jest 模拟navigator.clipboard甚至为不同语言读者贡献翻译Hugo 的 i18n 系统自动处理多语言路由。这种转变本质是从“内容发布者”进化为“技术内容架构师”。我不再问“Medium 能不能支持这个功能”而是问“这个功能如何用 Web 标准实现并融入我的内容工作流”。上周我用同样的架构为公司内部知识库搭建了“可执行文档”系统工程师点击代码块旁的“Run in Playground”按钮代码会自动在 iframe 中执行并显示结果。这个系统基于 Shiki WebContainerStackBlitz 的浏览器端 Node.js而它的底层正是从 Medium 迁移时打下的语义化 HTML 基础。所以“Stop Using Medium Code Cells”不是一句否定而是一把钥匙——它打开的是技术写作回归工程本质的大门。你写的不再是一篇“文章”而是一个可部署、可测试、可协作、可进化的软件模块。这或许就是技术人最熟悉也最应该拥有的工作方式。
