Markdown笔记写多了之后我遇到一个很实际的问题本地编辑器里看着挺舒服一旦需要分享出去或者长期归档纯文本的阅读体验就明显不够了尤其是有大量图片、表格和技术代码块的时候。后来我开始把笔记转成HTML网页用浏览器打开不仅排版稳定、图片不丢还能加上目录导航和代码折叠整份笔记就像一个小型技术站点。这篇文章就围绕这个目标完整梳理我自己在“Markdown笔记 → 优雅HTML网页”这条路上沉淀下来的方案从工具选型、图片嵌入到目录生成和代码折叠全部用可复现的步骤展开。1. 转换之前先把需求理清静态页面要解决的三个老问题1.1 为什么Markdown适合写作但不适合直接分享Markdown在设计之初就是为“写作”服务的语法极简、聚焦内容这套语法放在写作场景几乎完美。但它的短板也很明显样式单一、图片依赖外部路径、长文档缺乏导航。你写一篇两万字的技术笔记里面有几十个二级标题和三级标题别人拿到.md文件后要么用支持预览的编辑器打开要么放到代码托管平台渲染否则根本看不下去。拿我自己的例子来说我习惯用Markdown记录调试笔记一篇完整的排查记录往往有两三千行涉及多个代码片段和多张截图。每次发同事或者发到工作群对方打开后都会问“有没有网页版”。被问了几次之后我就认真折腾了一次Markdown转HTML的完整方案做完的网页可以直接双击打开也可以部署到任意静态托管平台上彻底告别“编辑器依赖”。1.2 静态HTML方案的优势与技术边界这里说的“静态HTML”指的是转换后不依赖后端服务、不依赖数据库一个文件夹扔到任何地方都能通过浏览器访问。这个方案的好处非常明显跨平台Windows、macOS、Linux甚至手机浏览器都能直接打开。生命周期长只要浏览器还在HTML文件就可以始终正常显示不像某些笔记软件哪天停止服务就全完了。易分享生成的是一个完整目录结构可以打包发邮件也可以推送到GitHub Pages、Gitee Pages、云服务器Nginx目录里。可定制所有样式都通过CSS控制想改字体、改间距、改颜色比在笔记软件里调整灵活太多。技术边界也要说清楚静态HTML页面没有用户交互和数据存储能力评论区、搜索功能除非接入第三方服务、登录权限这些都做不了。如果只是笔记展示和知识沉淀完全够用但如果你想做成一个带后台的博客系统那要另选方案。1.3 转换器的选型观点Pandoc vs. 在线工具 vs. 自研脚本我在调研阶段试过三类转换方式分别是Pandoc这类本地转换器、在线一键转换工具、以及自己写脚本调用Markdown解析库。Pandoc是我用得最顺手的一个它被称为“文档转换界的瑞士军刀”名副其实。将Markdown转成HTML只是它众多能力中的一项但它处理复杂表格、代码块和数学公式时的稳定性非常高。更重要的是Pandoc允许你自定义HTML模板生成的页面骨架是可控的这点对于后面要加目录、加代码折叠非常重要。在线工具比如各种“Markdown转HTML”网页适合突发需求但我不建议作为主力方案。一来每次都要手动复制粘贴效率太低二来很多在线工具会在生成的HTML中夹带额外的样式代码或脚本你不知道它干了什么也不方便统一管理自己的样式主题。自研脚本听起来高级但实际上就是调用markdown-it、marked这类JavaScript解析库二次封装成自己的导出工具。这条路适合需要深度定制的场景比如你希望同一份Markdown文件既能生成完整网页也能生成一个标题列表用于归档自研脚本最灵活。我现在的方案就是Pandoc为主、自研脚本为辅两条线并行。1.4 决定页面形态单文件还是目录结构动手之前必须做一个选择你需要的最终产物是一个独立的HTML文件还是一个包含HTML、CSS、图片资源的目录两种形态各有应用场景。单文件适合分发拿着U盘拷给别人也能打开图片通过base64内嵌或外链加载目录结构适合部署网站图片、样式、脚本分开存放方便维护和增量更新。我的建议是如果不是特殊分发需求优先使用目录结构。原因很简单图片放在外部目录里可以压缩、可以单独更新HTML页面体积也小得多。真到了需要单文件的场合再做一个“打包”脚本把图片转base64也不难。2. 基础转换实操用Pandoc快速生成干净的HTML结构2.1 环境准备与Pandoc安装Pandoc的安装不复杂但不同平台略有差异。macOSbrew install pandocUbuntu/Debiansudo apt install pandocWindows直接下载安装包或者用choco install pandoc如果你装了Chocolatey包管理器装完之后终端运行pandoc --version能看到版本信息就说明装好了。我目前用的版本是3.x和2.x在基础转换命令上差异不大但3.x的模板机制更新了一些如果你是老用户升级后建议重新检查自定义模板的兼容性。2.2 第一次转换从md到html最简单的一步进入Markdown文件所在目录执行pandoc note.md -o note.html --standalone--standalone参数可缩写为-s是关键它让Pandoc生成一个完整的HTML文档而不是一个没有html和body标签的片段。生成之后就能用浏览器打开。不过这时的页面样式是Pandoc自带的基础样式可用但谈不上“优雅”。真正决定颜值和阅读体验的部分是后续的CSS定制。2.3 自定义CSS的接入方式Pandoc支持通过-c参数关联外部CSS文件pandoc note.md -o note.html --standalone -c style.css-c只是建立链接关系CSS文件需要和HTML文件放在一起或使用相对路径。我习惯在项目目录下建一个assets/css/文件夹所有样式文件统一管理。另外还有一个值得尝试的参数是--metadata title我的笔记标题它可以覆盖Markdown文档中title块里的内容进而影响HTML页面标题的生成对后面目录和页面信息展示都有影响。2.4 定制Pandoc模板固定网页骨架Pandoc的默认HTML模板大致合理但如果你想加入更多自定义内容——比如页脚、侧边栏容器、用于挂载目录的div就需要复制一个模板文件来修改pandoc -D html my-template.html这一行命令会把Pandoc内置的HTML模板内容输出到my-template.html你可以在body标签内、内容区域前后加入自己的HTML结构。比如我就在模板中增加了一个div idsidebar/div专门用来放目录让目录不会干扰正文的阅读。涉及模板修改时要格外小心因为Pandoc模板使用的是$xxx$这种变量占位符。我的经验是在完全没摸清变量机制前不要轻易删除模板中的$body$、$title$、$css$这些占位符否则生成的HTML可能不完整。每改一步就生成一次页面并检查浏览器结果这是最稳妥的做法。2.5 与自建脚本结合批量和自动化Pandoc命令本身只能处理单个文件当你有几十篇笔记需要批量转换时就会想写个脚本统一处理。我使用Node.js写了一个简单的批处理脚本核心逻辑就是遍历某个目录下的所有.md文件逐个执行Pandoc命令并把CSS路径和输出目录统一处理好。const { execSync } require(child_process); const fs require(fs); const path require(path); const srcDir ./notes; const distDir ./dist; const cssPath assets/css/style.css; if (!fs.existsSync(distDir)) { fs.mkdirSync(distDir, { recursive: true }); } const files fs.readdirSync(srcDir).filter(f f.endsWith(.md)); files.forEach(file { const src path.join(srcDir, file); const out path.join(distDir, file.replace(.md, .html)); const cmd pandoc ${src} -o ${out} --standalone -c ${cssPath} --metadata title${file.replace(.md, )}; console.log(转换中${file}); execSync(cmd, { stdio: inherit }); }); console.log(全部转换完成);跑一次所有笔记就都生成好HTML了。如果你的笔记有层级目录脚本里还需要加子目录递归遍历这里只展示最核心的逻辑。3. 图片嵌入从路径迁移到base64内嵌的完整方案图片处理是Markdown转HTML里最容易被低估的环节。Markdown里的一句话在本地编辑器里看着没问题但把HTML分享出去时如果图片路径对不上就直接变成裂图。下面我会分几种情况说透。3.1 路径迁移保持目录结构不变最理想的情况是尽量维持原有目录结构。比如笔记文件在notes/xxx.md图片在notes/images/那么转换时输出HTML到与图片同级的目录相对路径就不会失效。notes/ ├── 001.md ├── images/ │ ├── a.png │ └── b.pngPandoc转换后HTML仍然引用images/a.png只要把整个notes目录复制出去图片就不会丢。这种方式最省事也最不容易出错。3.2 统一迁移把图片集中到一个目录如果你的Markdown笔记分布在不同目录图片也分布在不同地方那转换时就需要统一规划。我一般会在输出目录比如dist/下建立一个assets/img/目录然后在Pandoc转换前用脚本处理Markdown中的图片路径。这里提供一个小技巧用正则表达式匹配Markdown中的图片语法替换成目标路径。const mdContent fs.readFileSync(note.md, utf8); const updated mdContent.replace(/!\[([^\]]*)\]\(([^)])\)/g, (match, alt, src) { const filename path.basename(src); return ; }); fs.writeFileSync(note_processed.md, updated);处理完成后再把所有图片文件复制到目标目录。使用这种方式时前提是文件名不能冲突否则后复制的文件可能覆盖先前的。3.3 单文件方案base64图片内嵌如果你需要把整个HTML页面打包成单个文件发出去base64内嵌几乎是最可靠的选择。原理是把图片文件内容转换为Base64编码字符串直接写入HTML的src属性中。用Pandoc自带的能力很难直接完成这一步所以我通常写一个后处理脚本先生成HTML再扫描img标签的src地址读取图片文件并替换为Base64编码。const htmlContent fs.readFileSync(note.html, utf8); const updatedHtml htmlContent.replace(/src([^]*\.(png|jpg|jpeg|gif|svg))/gi, (match, src) { const data fs.readFileSync(src); const ext path.extname(src).slice(1).toLowerCase(); const mime ext svg ? svgxml : ext jpg ? jpeg : ext; const base64 data.toString(base64); return srcdata:image/${mime};base64,${base64}; }); fs.writeFileSync(note_single.html, updatedHtml);这里有个实测后的提醒大图片不要盲目转base64否则HTML文件会迅速膨胀。一张3MB的图片转成Base64编码后大约变成4MB十张图就是40MB浏览器加载会很慢。建议只对压缩后的截图使用此方案原始拍照图片事先压到合适分辨率。3.4 图片路径排查的完整流程转换后发现页面图片裂了不要急按下面的链路排查打开浏览器的开发者工具F12切换到Network面板刷新页面查看img请求的状态码。如果是404查看当前请求的完整URL用这个URL对比HTML文件中src的值找出路径差异。如果是200但图片不显示检查img标签是不是被CSS隐藏了或者图片本身损坏。如果是在GitHub Pages这类平台上显示异常注意路径大小写问题Linux环境下的文件名是区分大小写的。检查HTML文件和图片目录之间的相对关系常见错误是少算了当前HTML文件所在层级。把以上几步走完90%的图片问题都能定位。4. 目录生成让长笔记变成有导航的资料库一篇长文如果没有目录阅读者往往看到一半就想退出因为不知道文章还有多少内容、结构是什么样。目录的意义不仅在于跳转更是给读者一种“掌控感”——知道自己看到哪里、后面还有什么。4.1 目录生成的核心原理Markdown里的标题有层级结构#是一级标题##是二级标题###是三级标题。HTML中的h1、h2、h3标签天然对应这些层级。目录的本质就是把标题提取出来建立锚点链接。在HTML中实现目录需要两个环节一是给每个标题加一个id属性作为锚点二是在页面顶部或侧边生成一个列表列表项链接到对应锚点。aside idtoc nav ul lia href#section-1第1节XXX/a/li lia href#section-2第2节XXX/a ul lia href#section-2-12.1 小节/a/li /ul /li /ul /nav /aside4.2 Pandoc自动目录一行命令搞定基础版Pandoc本身支持自动生成目录pandoc note.md -o note.html --standalone --toc --toc-depth3--toc是生成目录的开关--toc-depth3控制目录层级显示到三级标题。生成的目录默认放置在文档开头并且会自动给每个标题添加锚点无需额外写JavaScript。但Pandoc默认目录的样式只是一份普通列表想要做侧边悬浮、滚动高亮还需要自定义CSS和JavaScript。所以我通常只用Pandoc生成锚点真正的目录容器和交互逻辑由自己控制。4.3 自建侧边目录滚动监听与滚动恢复为了实现更灵活的布局我采用“手动提取标题 构建目录 动态定位”的方案。在HTML模板中加入目录占位符利用JavaScript在页面加载完成后动态生成document.addEventListener(DOMContentLoaded, function () { const tocContainer document.getElementById(toc); const headings document.querySelectorAll(.content h1, .content h2, .content h3); const list document.createElement(ul); headings.forEach(function (heading) { if (!heading.id) { heading.id heading.textContent.trim().replace(/\s/g, -).toLowerCase(); } const li document.createElement(li); const link document.createElement(a); link.href # heading.id; link.textContent heading.textContent; li.appendChild(link); list.appendChild(li); }); tocContainer.appendChild(list); });这版代码的思路很直接找出正文区域的所有标题把标题文本转成适合作为id的字符串逐项生成目录链接。对原始标题中没有id的情况脚本会自动补上逻辑上就不会出现“点了没反应”的情况。在此基础上想加滚动高亮就监听scroll事件判断当前哪个标题出现在视口附近给对应的目录项加一个active类名通过CSS控制高亮样式。4.4 目录在移动端与打印场景下的处理手机屏幕宽度有限侧边目录不能一直展开。我的做法是利用CSS媒体查询在窄屏下把目录收进一个可展开的按钮中。media (max-width: 768px) { #toc { display: none; } #toc-toggle { display: block; } }配合一个简单的按钮交互点击时切换目录的显示与隐藏移动端体验就基本可用了。打印方面如果整篇笔记需要导出PDF目录放在页面上会占用大量空间打印时最好隐藏侧边栏media print { #toc, #toc-toggle { display: none; } }我测试下来这个思路对Chrome的“打印为PDF”功能很有效隐藏目录后正文排版会干净很多。5. 代码块处理高亮、折叠、复制一步到位技术笔记里最重要的元素就是代码块。如果代码块的颜值不行整个页面的技术含量直接掉一档。本文标题里特别提到代码折叠我在这里把代码高亮和折叠一起讲了因为它们通常是配套出现的。5.1 代码高亮方案的选择目前主流的代码高亮方案有两类一类是服务器端或构建时生成高亮样式比如Pandoc配合--highlight-style参数另一类是客户端JavaScript动态高亮比如Highlight.js、Prism.js、Shiki。Pandoc内置高亮的方案最省事pandoc note.md -o note.html --standalone --highlight-style tango它会把代码包在带颜色class的标签里输出最终样式。缺点是如果你后期更换主题色需要重新转换文档不够灵活。Prism.js / Highlight.js的方案更主流。以Prism.js为例在HTML模板中加载Prism的CSS和JS文件再引入你要用的语言组件代码块会自动高亮。它的好处是语言类型标签可以动态选择主题样式改一个CSS变量就能生效。5.2 代码折叠的实现从原生标签到JavaScript方案代码折叠的需求很典型代码太长时默认只展示前几行点击“展开”按钮后再完整显示。实现方式有两种我分别说明。方案一使用details和summary标签这是HTML原生支持的折叠交互不需要任何JavaScript结构也非常清晰details summary查看完整代码/summary precode classlanguage-python # 这里是完整代码 /code/pre /details浏览器会渲染出一个默认的折叠区域用户点击summary即可展开。它是纯原生组件兼容性好缺点是展开动画和样式比较朴素需要自己写CSS来美化。方案二自定义JavaScript折叠按钮如果你希望代码块默认只显示有限的几行让页面的信息密度更可控那就要用JavaScript精确控制。我通常给需要折叠的pre代码块添加一个collapsed类然后通过按钮切换类名function toggleCode(button) { const pre button.previousElementSibling; pre.classList.toggle(collapsed); button.textContent pre.classList.contains(collapsed) ? 展开代码 : 收起代码; }配合CSSpre.collapsed { max-height: 180px; overflow: hidden; }这个方法非常灵活能控制具体折叠多少行、有没有阴影遮罩、变换动画等。实测下来max-height方案比height动画方案更性能友好尤其是在页面中有大量代码块的场景下滚动流畅度更好。5.3 折叠状态记忆与多代码块管理长笔记里可能有十几个代码块用户展开其中一个滚动到别处再回来发现它又合上了体验会有点割裂。我加了状态记忆当用户点击折叠按钮时把这个代码块的唯一标识存到localStorage页面重新加载后根据存储状态决定默认是展开还是折叠。document.querySelectorAll(.code-block button).forEach(btn { const id btn.dataset.id; btn.addEventListener(click, () { const expanded btn.classList.contains(expanded); localStorage.setItem(code- id, expanded ? 1 : 0); }); });多代码块管理的关键就是给每个块一个>document.querySelectorAll(.code-block).forEach(block { const btn document.createElement(button); btn.textContent 复制; block.appendChild(btn); btn.addEventListener(click, () { const codeText block.querySelector(code).innerText; navigator.clipboard.writeText(codeText).then(() { btn.textContent 已复制; setTimeout(() btn.textContent 复制, 2000); }); }); });这里要提醒一个浏览器限制navigator.clipboard只有在HTTPS或localhost环境下才可用如果你的HTML文件是通过file://协议直接打开的部分浏览器会拒绝调用。稳妥的降级方案是使用document.execCommand(copy)配合临时文本框或者提示用户手动选择复制。6. 颜值与阅读体验真正让它“优雅”起来的CSS细节6.1 内容宽度与行高阅读节奏的底层逻辑一个页面是否阅读舒适最先起作用的就是正文区域宽度和行高。过宽的行眼睛扫不过来过窄的行频繁换行打断思路。我的经验是把正文区域宽度控制在680px到800px之间代码块可以略宽一点。.content { max-width: 760px; margin: 0 auto; line-height: 1.75; font-size: 16px; } pre { max-width: 860px; margin: 1.5em auto; overflow-x: auto; line-height: 1.5; }行高用1.75是比较稳妥的中文阅读设置英文和代码的行高可以稍低因为代码行本身没有中文字符密集。6.2 正文标题的视觉层级与间距节奏标题层级如果不清晰读者很难快速扫描文档结构。我用一組CSS变量来统一标题颜色和间距后期要换主题就只改变量:root { --h1-size: 2.2rem; --h2-size: 1.7rem; --h3-size: 1.3rem; --heading-color: #24292f; --text-color: #24292f; --border-color: #d0d7de; } h1, h2, h3 { color: var(--heading-color); margin-top: 1.6em; margin-bottom: 0.8em; } h1 { font-size: var(--h1-size); border-bottom: 1px solid var(--border-color); padding-bottom: 0.3em; } h2 { font-size: var(--h2-size); padding-left: 0.5em; border-left: 4px solid #0969da; }其中h2加左侧竖线的做法是我在多次改版后保留的它能显著强化层级感同时不像下划线那样破坏标题区域的干净背景。6.3 暗色模式用CSS变量实现快速适配技术读者对暗色模式的需求普遍很高。在学习通宵场景下亮色页面确实很刺眼。我用纯CSS方式实现media (prefers-color-scheme: dark) { :root { --text-color: #e6edf3; --bg-color: #0d1117; --border-color: #30363d; --heading-color: #f0f6fc; } body { background-color: var(--bg-color); color: var(--text-color); } }这种方式完全依赖操作系统的主题设置用户不需要在页面内做任何操作无感适配。如果希望页面上加一个手动切换按钮那再写一小段JavaScript切换>blockquote { margin: 1em 0; padding: 0.5em 1em; border-left: 4px solid #0969da; background-color: #f6f8fa; border-radius: 0 6px 6px 0; }表格方面给头部加背景色、行间加细分隔线table { border-collapse: collapse; width: 100%; margin: 1.5em 0; } th, td { border: 1px solid var(--border-color); padding: 0.6em 1em; text-align: left; } th { background-color: #f6f8fa; font-weight: 600; }6.5 部署与本地预览的高效工作流每次改完CSS或者重新转换完笔记不必打开文件管理器去双击HTML。如果你在本地用了VS Code可以装一个Live Server插件在项目目录里启动一个本地服务地址类似http://127.0.0.1:5500保存文件后浏览器自动刷新整个预览和调样式的时间会大幅缩短。如果要发布到外网我的优先级是这样GitHub Pages Gitee Pages 自己的云服务器Nginx 内网穿透工具。GitHub Pages支持自定义域名和HTTPS免费且稳定很适合个人笔记库。有一个发布细节值得留意如果你使用相对路径比如assets/css/style.css部署到GitHub Pages的子路径https://用户名.github.io/仓库名/时只要目录结构正确一般不需要额外配置。但如果你在网页中使用了JavaScript请求外部数据接口就必须把接口地址配置成可访问的绝对地址。7. 完整示例一个可直接套用的项目结构聊到这里已经覆盖了几大核心模块下面给出一份我在实际使用中维护的项目结构你可以直接参考按自己的需要增删。markdown-notes/ ├── md/ │ ├── 001-markdown转html实战.md │ ├── 002-docker部署踩坑记录.md │ └── ... ├── dist/ │ ├── 001-markdown转html实战.html │ ├── 002-docker部署踩坑记录.html │ └── assets/ │ ├── css/ │ │ └── style.css │ ├── js/ │ │ ├── toc.js │ │ └── code-fold.js │ └── img/ │ ├── screenshot-01.png │ └── ... ├── scripts/ │ ├── build.js │ ├── copy-images.js │ └── pack-single.js ├── templates/ │ └── custom-template.html └── package.json这个结构的要点是md/目录存放原始Markdown笔记dist/是构建结果也就是最终可直接发布的文件scripts/存放构建和后期处理脚本templates/存放Pandoc的自定义模板。构建一次的主要流程运行build.js遍历md/下所有Markdown文件逐篇调用Pandoc生成HTML。运行copy-images.js把Markdown中引用的图片统一复制到dist/assets/img/。手动或脚本化地把style.css、toc.js、code-fold.js复制到dist/assets/。在本地启动Live Server预览检查目录、代码折叠、图片显示。用Git push触发GitHub Pages自动部署或者把dist/整个目录上传到服务器。我把这些步骤封装成一个脚本后每次新增或修改笔记只需要把Markdown丢进md/目录然后跑一次npm run build几分钟后线上页面就已经更新好了基本彻底告别“导出HTML再手动调整”的琐碎流程。我个人的体会是Markdown转HTML这件事难点从来不是“转出来”而是“转得好看、转得完整、转得好用”。图片路径、目录结构、代码交互这些点只要有耐心逐个击破一次后面的所有笔记都能享受同样的成果。希望这篇文章里沉淀的方法能让你的笔记库也变成一个真正能看、能分享、能沉淀的知识站点。 
长河君 · 2026/9/20 2:24:34 · 阅读 1.2k 从Markdown到优雅HTML网页：完整转换方案与实战技巧
Markdown笔记写多了之后我遇到一个很实际的问题本地编辑器里看着挺舒服一旦需要分享出去或者长期归档纯文本的阅读体验就明显不够了尤其是有大量图片、表格和技术代码块的时候。后来我开始把笔记转成HTML网页用浏览器打开不仅排版稳定、图片不丢还能加上目录导航和代码折叠整份笔记就像一个小型技术站点。这篇文章就围绕这个目标完整梳理我自己在“Markdown笔记 → 优雅HTML网页”这条路上沉淀下来的方案从工具选型、图片嵌入到目录生成和代码折叠全部用可复现的步骤展开。1. 转换之前先把需求理清静态页面要解决的三个老问题1.1 为什么Markdown适合写作但不适合直接分享Markdown在设计之初就是为“写作”服务的语法极简、聚焦内容这套语法放在写作场景几乎完美。但它的短板也很明显样式单一、图片依赖外部路径、长文档缺乏导航。你写一篇两万字的技术笔记里面有几十个二级标题和三级标题别人拿到.md文件后要么用支持预览的编辑器打开要么放到代码托管平台渲染否则根本看不下去。拿我自己的例子来说我习惯用Markdown记录调试笔记一篇完整的排查记录往往有两三千行涉及多个代码片段和多张截图。每次发同事或者发到工作群对方打开后都会问“有没有网页版”。被问了几次之后我就认真折腾了一次Markdown转HTML的完整方案做完的网页可以直接双击打开也可以部署到任意静态托管平台上彻底告别“编辑器依赖”。1.2 静态HTML方案的优势与技术边界这里说的“静态HTML”指的是转换后不依赖后端服务、不依赖数据库一个文件夹扔到任何地方都能通过浏览器访问。这个方案的好处非常明显跨平台Windows、macOS、Linux甚至手机浏览器都能直接打开。生命周期长只要浏览器还在HTML文件就可以始终正常显示不像某些笔记软件哪天停止服务就全完了。易分享生成的是一个完整目录结构可以打包发邮件也可以推送到GitHub Pages、Gitee Pages、云服务器Nginx目录里。可定制所有样式都通过CSS控制想改字体、改间距、改颜色比在笔记软件里调整灵活太多。技术边界也要说清楚静态HTML页面没有用户交互和数据存储能力评论区、搜索功能除非接入第三方服务、登录权限这些都做不了。如果只是笔记展示和知识沉淀完全够用但如果你想做成一个带后台的博客系统那要另选方案。1.3 转换器的选型观点Pandoc vs. 在线工具 vs. 自研脚本我在调研阶段试过三类转换方式分别是Pandoc这类本地转换器、在线一键转换工具、以及自己写脚本调用Markdown解析库。Pandoc是我用得最顺手的一个它被称为“文档转换界的瑞士军刀”名副其实。将Markdown转成HTML只是它众多能力中的一项但它处理复杂表格、代码块和数学公式时的稳定性非常高。更重要的是Pandoc允许你自定义HTML模板生成的页面骨架是可控的这点对于后面要加目录、加代码折叠非常重要。在线工具比如各种“Markdown转HTML”网页适合突发需求但我不建议作为主力方案。一来每次都要手动复制粘贴效率太低二来很多在线工具会在生成的HTML中夹带额外的样式代码或脚本你不知道它干了什么也不方便统一管理自己的样式主题。自研脚本听起来高级但实际上就是调用markdown-it、marked这类JavaScript解析库二次封装成自己的导出工具。这条路适合需要深度定制的场景比如你希望同一份Markdown文件既能生成完整网页也能生成一个标题列表用于归档自研脚本最灵活。我现在的方案就是Pandoc为主、自研脚本为辅两条线并行。1.4 决定页面形态单文件还是目录结构动手之前必须做一个选择你需要的最终产物是一个独立的HTML文件还是一个包含HTML、CSS、图片资源的目录两种形态各有应用场景。单文件适合分发拿着U盘拷给别人也能打开图片通过base64内嵌或外链加载目录结构适合部署网站图片、样式、脚本分开存放方便维护和增量更新。我的建议是如果不是特殊分发需求优先使用目录结构。原因很简单图片放在外部目录里可以压缩、可以单独更新HTML页面体积也小得多。真到了需要单文件的场合再做一个“打包”脚本把图片转base64也不难。2. 基础转换实操用Pandoc快速生成干净的HTML结构2.1 环境准备与Pandoc安装Pandoc的安装不复杂但不同平台略有差异。macOSbrew install pandocUbuntu/Debiansudo apt install pandocWindows直接下载安装包或者用choco install pandoc如果你装了Chocolatey包管理器装完之后终端运行pandoc --version能看到版本信息就说明装好了。我目前用的版本是3.x和2.x在基础转换命令上差异不大但3.x的模板机制更新了一些如果你是老用户升级后建议重新检查自定义模板的兼容性。2.2 第一次转换从md到html最简单的一步进入Markdown文件所在目录执行pandoc note.md -o note.html --standalone--standalone参数可缩写为-s是关键它让Pandoc生成一个完整的HTML文档而不是一个没有html和body标签的片段。生成之后就能用浏览器打开。不过这时的页面样式是Pandoc自带的基础样式可用但谈不上“优雅”。真正决定颜值和阅读体验的部分是后续的CSS定制。2.3 自定义CSS的接入方式Pandoc支持通过-c参数关联外部CSS文件pandoc note.md -o note.html --standalone -c style.css-c只是建立链接关系CSS文件需要和HTML文件放在一起或使用相对路径。我习惯在项目目录下建一个assets/css/文件夹所有样式文件统一管理。另外还有一个值得尝试的参数是--metadata title我的笔记标题它可以覆盖Markdown文档中title块里的内容进而影响HTML页面标题的生成对后面目录和页面信息展示都有影响。2.4 定制Pandoc模板固定网页骨架Pandoc的默认HTML模板大致合理但如果你想加入更多自定义内容——比如页脚、侧边栏容器、用于挂载目录的div就需要复制一个模板文件来修改pandoc -D html my-template.html这一行命令会把Pandoc内置的HTML模板内容输出到my-template.html你可以在body标签内、内容区域前后加入自己的HTML结构。比如我就在模板中增加了一个div idsidebar/div专门用来放目录让目录不会干扰正文的阅读。涉及模板修改时要格外小心因为Pandoc模板使用的是$xxx$这种变量占位符。我的经验是在完全没摸清变量机制前不要轻易删除模板中的$body$、$title$、$css$这些占位符否则生成的HTML可能不完整。每改一步就生成一次页面并检查浏览器结果这是最稳妥的做法。2.5 与自建脚本结合批量和自动化Pandoc命令本身只能处理单个文件当你有几十篇笔记需要批量转换时就会想写个脚本统一处理。我使用Node.js写了一个简单的批处理脚本核心逻辑就是遍历某个目录下的所有.md文件逐个执行Pandoc命令并把CSS路径和输出目录统一处理好。const { execSync } require(child_process); const fs require(fs); const path require(path); const srcDir ./notes; const distDir ./dist; const cssPath assets/css/style.css; if (!fs.existsSync(distDir)) { fs.mkdirSync(distDir, { recursive: true }); } const files fs.readdirSync(srcDir).filter(f f.endsWith(.md)); files.forEach(file { const src path.join(srcDir, file); const out path.join(distDir, file.replace(.md, .html)); const cmd pandoc ${src} -o ${out} --standalone -c ${cssPath} --metadata title${file.replace(.md, )}; console.log(转换中${file}); execSync(cmd, { stdio: inherit }); }); console.log(全部转换完成);跑一次所有笔记就都生成好HTML了。如果你的笔记有层级目录脚本里还需要加子目录递归遍历这里只展示最核心的逻辑。3. 图片嵌入从路径迁移到base64内嵌的完整方案图片处理是Markdown转HTML里最容易被低估的环节。Markdown里的一句话在本地编辑器里看着没问题但把HTML分享出去时如果图片路径对不上就直接变成裂图。下面我会分几种情况说透。3.1 路径迁移保持目录结构不变最理想的情况是尽量维持原有目录结构。比如笔记文件在notes/xxx.md图片在notes/images/那么转换时输出HTML到与图片同级的目录相对路径就不会失效。notes/ ├── 001.md ├── images/ │ ├── a.png │ └── b.pngPandoc转换后HTML仍然引用images/a.png只要把整个notes目录复制出去图片就不会丢。这种方式最省事也最不容易出错。3.2 统一迁移把图片集中到一个目录如果你的Markdown笔记分布在不同目录图片也分布在不同地方那转换时就需要统一规划。我一般会在输出目录比如dist/下建立一个assets/img/目录然后在Pandoc转换前用脚本处理Markdown中的图片路径。这里提供一个小技巧用正则表达式匹配Markdown中的图片语法替换成目标路径。const mdContent fs.readFileSync(note.md, utf8); const updated mdContent.replace(/!\[([^\]]*)\]\(([^)])\)/g, (match, alt, src) { const filename path.basename(src); return ; }); fs.writeFileSync(note_processed.md, updated);处理完成后再把所有图片文件复制到目标目录。使用这种方式时前提是文件名不能冲突否则后复制的文件可能覆盖先前的。3.3 单文件方案base64图片内嵌如果你需要把整个HTML页面打包成单个文件发出去base64内嵌几乎是最可靠的选择。原理是把图片文件内容转换为Base64编码字符串直接写入HTML的src属性中。用Pandoc自带的能力很难直接完成这一步所以我通常写一个后处理脚本先生成HTML再扫描img标签的src地址读取图片文件并替换为Base64编码。const htmlContent fs.readFileSync(note.html, utf8); const updatedHtml htmlContent.replace(/src([^]*\.(png|jpg|jpeg|gif|svg))/gi, (match, src) { const data fs.readFileSync(src); const ext path.extname(src).slice(1).toLowerCase(); const mime ext svg ? svgxml : ext jpg ? jpeg : ext; const base64 data.toString(base64); return srcdata:image/${mime};base64,${base64}; }); fs.writeFileSync(note_single.html, updatedHtml);这里有个实测后的提醒大图片不要盲目转base64否则HTML文件会迅速膨胀。一张3MB的图片转成Base64编码后大约变成4MB十张图就是40MB浏览器加载会很慢。建议只对压缩后的截图使用此方案原始拍照图片事先压到合适分辨率。3.4 图片路径排查的完整流程转换后发现页面图片裂了不要急按下面的链路排查打开浏览器的开发者工具F12切换到Network面板刷新页面查看img请求的状态码。如果是404查看当前请求的完整URL用这个URL对比HTML文件中src的值找出路径差异。如果是200但图片不显示检查img标签是不是被CSS隐藏了或者图片本身损坏。如果是在GitHub Pages这类平台上显示异常注意路径大小写问题Linux环境下的文件名是区分大小写的。检查HTML文件和图片目录之间的相对关系常见错误是少算了当前HTML文件所在层级。把以上几步走完90%的图片问题都能定位。4. 目录生成让长笔记变成有导航的资料库一篇长文如果没有目录阅读者往往看到一半就想退出因为不知道文章还有多少内容、结构是什么样。目录的意义不仅在于跳转更是给读者一种“掌控感”——知道自己看到哪里、后面还有什么。4.1 目录生成的核心原理Markdown里的标题有层级结构#是一级标题##是二级标题###是三级标题。HTML中的h1、h2、h3标签天然对应这些层级。目录的本质就是把标题提取出来建立锚点链接。在HTML中实现目录需要两个环节一是给每个标题加一个id属性作为锚点二是在页面顶部或侧边生成一个列表列表项链接到对应锚点。aside idtoc nav ul lia href#section-1第1节XXX/a/li lia href#section-2第2节XXX/a ul lia href#section-2-12.1 小节/a/li /ul /li /ul /nav /aside4.2 Pandoc自动目录一行命令搞定基础版Pandoc本身支持自动生成目录pandoc note.md -o note.html --standalone --toc --toc-depth3--toc是生成目录的开关--toc-depth3控制目录层级显示到三级标题。生成的目录默认放置在文档开头并且会自动给每个标题添加锚点无需额外写JavaScript。但Pandoc默认目录的样式只是一份普通列表想要做侧边悬浮、滚动高亮还需要自定义CSS和JavaScript。所以我通常只用Pandoc生成锚点真正的目录容器和交互逻辑由自己控制。4.3 自建侧边目录滚动监听与滚动恢复为了实现更灵活的布局我采用“手动提取标题 构建目录 动态定位”的方案。在HTML模板中加入目录占位符利用JavaScript在页面加载完成后动态生成document.addEventListener(DOMContentLoaded, function () { const tocContainer document.getElementById(toc); const headings document.querySelectorAll(.content h1, .content h2, .content h3); const list document.createElement(ul); headings.forEach(function (heading) { if (!heading.id) { heading.id heading.textContent.trim().replace(/\s/g, -).toLowerCase(); } const li document.createElement(li); const link document.createElement(a); link.href # heading.id; link.textContent heading.textContent; li.appendChild(link); list.appendChild(li); }); tocContainer.appendChild(list); });这版代码的思路很直接找出正文区域的所有标题把标题文本转成适合作为id的字符串逐项生成目录链接。对原始标题中没有id的情况脚本会自动补上逻辑上就不会出现“点了没反应”的情况。在此基础上想加滚动高亮就监听scroll事件判断当前哪个标题出现在视口附近给对应的目录项加一个active类名通过CSS控制高亮样式。4.4 目录在移动端与打印场景下的处理手机屏幕宽度有限侧边目录不能一直展开。我的做法是利用CSS媒体查询在窄屏下把目录收进一个可展开的按钮中。media (max-width: 768px) { #toc { display: none; } #toc-toggle { display: block; } }配合一个简单的按钮交互点击时切换目录的显示与隐藏移动端体验就基本可用了。打印方面如果整篇笔记需要导出PDF目录放在页面上会占用大量空间打印时最好隐藏侧边栏media print { #toc, #toc-toggle { display: none; } }我测试下来这个思路对Chrome的“打印为PDF”功能很有效隐藏目录后正文排版会干净很多。5. 代码块处理高亮、折叠、复制一步到位技术笔记里最重要的元素就是代码块。如果代码块的颜值不行整个页面的技术含量直接掉一档。本文标题里特别提到代码折叠我在这里把代码高亮和折叠一起讲了因为它们通常是配套出现的。5.1 代码高亮方案的选择目前主流的代码高亮方案有两类一类是服务器端或构建时生成高亮样式比如Pandoc配合--highlight-style参数另一类是客户端JavaScript动态高亮比如Highlight.js、Prism.js、Shiki。Pandoc内置高亮的方案最省事pandoc note.md -o note.html --standalone --highlight-style tango它会把代码包在带颜色class的标签里输出最终样式。缺点是如果你后期更换主题色需要重新转换文档不够灵活。Prism.js / Highlight.js的方案更主流。以Prism.js为例在HTML模板中加载Prism的CSS和JS文件再引入你要用的语言组件代码块会自动高亮。它的好处是语言类型标签可以动态选择主题样式改一个CSS变量就能生效。5.2 代码折叠的实现从原生标签到JavaScript方案代码折叠的需求很典型代码太长时默认只展示前几行点击“展开”按钮后再完整显示。实现方式有两种我分别说明。方案一使用details和summary标签这是HTML原生支持的折叠交互不需要任何JavaScript结构也非常清晰details summary查看完整代码/summary precode classlanguage-python # 这里是完整代码 /code/pre /details浏览器会渲染出一个默认的折叠区域用户点击summary即可展开。它是纯原生组件兼容性好缺点是展开动画和样式比较朴素需要自己写CSS来美化。方案二自定义JavaScript折叠按钮如果你希望代码块默认只显示有限的几行让页面的信息密度更可控那就要用JavaScript精确控制。我通常给需要折叠的pre代码块添加一个collapsed类然后通过按钮切换类名function toggleCode(button) { const pre button.previousElementSibling; pre.classList.toggle(collapsed); button.textContent pre.classList.contains(collapsed) ? 展开代码 : 收起代码; }配合CSSpre.collapsed { max-height: 180px; overflow: hidden; }这个方法非常灵活能控制具体折叠多少行、有没有阴影遮罩、变换动画等。实测下来max-height方案比height动画方案更性能友好尤其是在页面中有大量代码块的场景下滚动流畅度更好。5.3 折叠状态记忆与多代码块管理长笔记里可能有十几个代码块用户展开其中一个滚动到别处再回来发现它又合上了体验会有点割裂。我加了状态记忆当用户点击折叠按钮时把这个代码块的唯一标识存到localStorage页面重新加载后根据存储状态决定默认是展开还是折叠。document.querySelectorAll(.code-block button).forEach(btn { const id btn.dataset.id; btn.addEventListener(click, () { const expanded btn.classList.contains(expanded); localStorage.setItem(code- id, expanded ? 1 : 0); }); });多代码块管理的关键就是给每个块一个>document.querySelectorAll(.code-block).forEach(block { const btn document.createElement(button); btn.textContent 复制; block.appendChild(btn); btn.addEventListener(click, () { const codeText block.querySelector(code).innerText; navigator.clipboard.writeText(codeText).then(() { btn.textContent 已复制; setTimeout(() btn.textContent 复制, 2000); }); }); });这里要提醒一个浏览器限制navigator.clipboard只有在HTTPS或localhost环境下才可用如果你的HTML文件是通过file://协议直接打开的部分浏览器会拒绝调用。稳妥的降级方案是使用document.execCommand(copy)配合临时文本框或者提示用户手动选择复制。6. 颜值与阅读体验真正让它“优雅”起来的CSS细节6.1 内容宽度与行高阅读节奏的底层逻辑一个页面是否阅读舒适最先起作用的就是正文区域宽度和行高。过宽的行眼睛扫不过来过窄的行频繁换行打断思路。我的经验是把正文区域宽度控制在680px到800px之间代码块可以略宽一点。.content { max-width: 760px; margin: 0 auto; line-height: 1.75; font-size: 16px; } pre { max-width: 860px; margin: 1.5em auto; overflow-x: auto; line-height: 1.5; }行高用1.75是比较稳妥的中文阅读设置英文和代码的行高可以稍低因为代码行本身没有中文字符密集。6.2 正文标题的视觉层级与间距节奏标题层级如果不清晰读者很难快速扫描文档结构。我用一組CSS变量来统一标题颜色和间距后期要换主题就只改变量:root { --h1-size: 2.2rem; --h2-size: 1.7rem; --h3-size: 1.3rem; --heading-color: #24292f; --text-color: #24292f; --border-color: #d0d7de; } h1, h2, h3 { color: var(--heading-color); margin-top: 1.6em; margin-bottom: 0.8em; } h1 { font-size: var(--h1-size); border-bottom: 1px solid var(--border-color); padding-bottom: 0.3em; } h2 { font-size: var(--h2-size); padding-left: 0.5em; border-left: 4px solid #0969da; }其中h2加左侧竖线的做法是我在多次改版后保留的它能显著强化层级感同时不像下划线那样破坏标题区域的干净背景。6.3 暗色模式用CSS变量实现快速适配技术读者对暗色模式的需求普遍很高。在学习通宵场景下亮色页面确实很刺眼。我用纯CSS方式实现media (prefers-color-scheme: dark) { :root { --text-color: #e6edf3; --bg-color: #0d1117; --border-color: #30363d; --heading-color: #f0f6fc; } body { background-color: var(--bg-color); color: var(--text-color); } }这种方式完全依赖操作系统的主题设置用户不需要在页面内做任何操作无感适配。如果希望页面上加一个手动切换按钮那再写一小段JavaScript切换>blockquote { margin: 1em 0; padding: 0.5em 1em; border-left: 4px solid #0969da; background-color: #f6f8fa; border-radius: 0 6px 6px 0; }表格方面给头部加背景色、行间加细分隔线table { border-collapse: collapse; width: 100%; margin: 1.5em 0; } th, td { border: 1px solid var(--border-color); padding: 0.6em 1em; text-align: left; } th { background-color: #f6f8fa; font-weight: 600; }6.5 部署与本地预览的高效工作流每次改完CSS或者重新转换完笔记不必打开文件管理器去双击HTML。如果你在本地用了VS Code可以装一个Live Server插件在项目目录里启动一个本地服务地址类似http://127.0.0.1:5500保存文件后浏览器自动刷新整个预览和调样式的时间会大幅缩短。如果要发布到外网我的优先级是这样GitHub Pages Gitee Pages 自己的云服务器Nginx 内网穿透工具。GitHub Pages支持自定义域名和HTTPS免费且稳定很适合个人笔记库。有一个发布细节值得留意如果你使用相对路径比如assets/css/style.css部署到GitHub Pages的子路径https://用户名.github.io/仓库名/时只要目录结构正确一般不需要额外配置。但如果你在网页中使用了JavaScript请求外部数据接口就必须把接口地址配置成可访问的绝对地址。7. 完整示例一个可直接套用的项目结构聊到这里已经覆盖了几大核心模块下面给出一份我在实际使用中维护的项目结构你可以直接参考按自己的需要增删。markdown-notes/ ├── md/ │ ├── 001-markdown转html实战.md │ ├── 002-docker部署踩坑记录.md │ └── ... ├── dist/ │ ├── 001-markdown转html实战.html │ ├── 002-docker部署踩坑记录.html │ └── assets/ │ ├── css/ │ │ └── style.css │ ├── js/ │ │ ├── toc.js │ │ └── code-fold.js │ └── img/ │ ├── screenshot-01.png │ └── ... ├── scripts/ │ ├── build.js │ ├── copy-images.js │ └── pack-single.js ├── templates/ │ └── custom-template.html └── package.json这个结构的要点是md/目录存放原始Markdown笔记dist/是构建结果也就是最终可直接发布的文件scripts/存放构建和后期处理脚本templates/存放Pandoc的自定义模板。构建一次的主要流程运行build.js遍历md/下所有Markdown文件逐篇调用Pandoc生成HTML。运行copy-images.js把Markdown中引用的图片统一复制到dist/assets/img/。手动或脚本化地把style.css、toc.js、code-fold.js复制到dist/assets/。在本地启动Live Server预览检查目录、代码折叠、图片显示。用Git push触发GitHub Pages自动部署或者把dist/整个目录上传到服务器。我把这些步骤封装成一个脚本后每次新增或修改笔记只需要把Markdown丢进md/目录然后跑一次npm run build几分钟后线上页面就已经更新好了基本彻底告别“导出HTML再手动调整”的琐碎流程。我个人的体会是Markdown转HTML这件事难点从来不是“转出来”而是“转得好看、转得完整、转得好用”。图片路径、目录结构、代码交互这些点只要有耐心逐个击破一次后面的所有笔记都能享受同样的成果。希望这篇文章里沉淀的方法能让你的笔记库也变成一个真正能看、能分享、能沉淀的知识站点。