作者主导结构和核心观点，正文部分内容由 AI 协助生成。
没错，写博客时最折腾、最扫兴的那几件事，这次终于被我们一口气彻底解决了！
如果你也是静态博客（比如 Astro / Fuwari / Hexo）的重度用户，大概率经历过这种被本地写文疯狂劝退的折磨场景：
在本地编辑器（比如 Typora、Obsidian 或 VS Code）里辛辛苦苦写完一大段，里面用上了博客专属的特色语法（比如 GitHub 样式的 Admonition 警告块、自定义卡片、代码高亮、剧透块等）。结果本地编辑器要么直接显示成一坨生硬的代码标签，要么样式排版与线上相差十万八千里。
想看真实效果？你只能老老实实打开终端敲：
pnpm dev
然后眼睁睁看着 Node.js 占用好几百兆内存，等几秒启动本地服务，再切到浏览器刷新查看；好不容易看到哪里不对，改个标点或换张图片，又得在编辑器与浏览器之间来回反复横跳……
读文章时也是同理：当我们在笔记本小屏或缩放比例较大的屏幕上浏览长文时，右侧悬浮的目录（TOC）常常因为空间不足被直接隐藏；而左侧的信息卡片和右下角的浮动按钮又多少有些抢戏，很难安安静静沉浸在长篇阅读中。
为了拯救写文与阅读体验，我们花时间把这两个痛点连根拔起：纯浏览器端 1:1 即时预览工具 与 文章沉浸式阅读模式 正式登场！
一、纯本地 Markdown 即时预览工具
预览工具入口现已直接集成在博客的工具箱导航中：访问 /tools/markdown-preview 即可体验。
1. 纯本地浏览器端处理，零服务依赖与绝对隐私
市面上很多在线 Markdown 预览工具，本质上都是把你写的草稿文字发到远端服务器解析后再把 HTML 吐回来。对于经常需要写随笔、内网配置或未公开发表草稿的站长来说，这无疑存在极大的数据泄露隐患。
我们的预览工具核心原则是：100% 纯客户端运行。
- 零服务端上传，所有 AST 词法分析、Frontmatter 解析均在你的浏览器本地瞬间完成；
- 即便拔掉网线、完全处于离线环境，预览与大纲交互依然行云流水！
2. 1:1 源码级复刻全站排版
这绝不是市面上那种套个通用的 GitHub Markdown CSS 敷衍了事的预览器，而是将博客本身的样式系统与渲染管线进行同构映射：
- Frontmatter 元数据实时解析：输入文章的 YAML 头部（标题、发布日期、描述、标签等），上方会自动以真实博文的规范卡片渲染；
- 全套扩展指令支持：支持包含
:::note、:::tip、:::important在内的多级警告块、行内剧透折叠、KaTeX 数学公式渲染； - 代码高亮与样式对齐：完整支持 Prism 语法高亮与主题跟随。
3. 递归多级大纲树（TOC）
右侧大纲不仅能实时追踪正文变化，还内置了基于栈结构的层级归纳算法：从 H1 到 H4 自动梳理父子层级并递归缩进，点击任意标题平滑跳转，排版结构一览无余。
二、文章沉浸阅读模式：把舞台还给文字
写好了文章，当然还要有绝佳的阅读环境。
现在，当你打开博客的任意一篇文章详情页时，右下角控制栏中已经多出了一个“沉浸阅读”开关按钮。
1. 点击切换与微交互反馈
- 点击右下角沉浸模式按钮，伴随着丝滑的微浮动动效与图标形态切换，整篇博客即可进入全屏聚焦阅读状态；
- 同时贴心地绑定了键盘监听——在沉浸模式下，直接按下键盘上的 Esc 键即可秒级退回常规布局。
2. CSS Grid 双通道无缝滑入
大部分博客的“阅读模式”往往做得非常粗糙：要么把侧边栏直接 display: none 导致页面瞬间大幅抖动回流，要么正文宽度突然暴增，阅读视线极其难受。
我们采用了基于现代 CSS Grid 双层通道与交叉淡入 的自适应设计：
- 平滑淡出个人卡片：左侧原本的个人资料卡片平滑淡出，文章目录（TOC）如同丝带般平滑滑入左侧黄金阅读视野；
- 正文宽度锁定：文章主体完全保持既有的舒适黄金排版宽度与视口位置，不会产生哪怕 1 像素的跳动与闪烁；
- 彻底解决笔记本小屏痛点：对于 1080P 或启用系统高 DPI 缩放（125%~150%）的用户，右侧常年被遮蔽的目录在沉浸模式下被重新唤醒，左侧导航、中间阅读，体验极度舒适！
三、踩坑与技术幕后
看似直观的功能，在实际编码落地时依然有不少耐人寻味的技术细节：
1. 跨时区与全站时间规范单一事实来源
预览工具在解析文章 Frontmatter 的 published 时间时，最初直接用了浏览器内置的 new Date()，结果因本地时区与全站格式不同产生微小偏差。
后来我们重构将全站的 date-utils.ts 引入为唯一的单一事实来源（Single Source of Truth），统一了时间解析逻辑，彻底消除了不同时区环境下的渲染不一致。
2. 避免大纲监听器与主站 TOC 发生冲突
因为预览器右侧自带一套独立的大纲目录，而主站文章页本身也有悬浮目录组件，如果使用全局选择器或相同的大纲容器 ID，很容易导致滚动监听器相互误触发。
我们在样式和 DOM 作用域上做了彻底的局部隔离（Scoped TOC），确保预览器内的标题和高亮游标只在自身容器内响应。
3. 多级标题跳级的栈回溯算法
在实际写文章时，有时候难免会从 ## 二级标题 直接跳到 #### 四级标题，如果采用简单的平铺循环遍历，往往会导致缩进嵌套崩溃。
我们通过栈结构（Stack）维护当前标题的活跃层级链，遇到同级或更高级标题时自底向上安全回弹，从而保证了大纲树算法在面对任何非规范 Markdown 时都能稳健渲染。
四、写在最后
折腾自己的独立博客，最快乐的时刻莫过于发现痛点、写下代码，并最终看到它每天都在真真切切地优化自己的创作与阅读体验。
这两项功能现已全量集成到博客生产环境，欢迎大家在阅读本文时点击右下角体验沉浸模式，或者前往 Markdown 实时预览工具 亲自上手体验！如果你有更好的点子或遇到任何排版细节问题，随时在下方评论区留言交流~
这篇文章是否对你有帮助？
发现错误或想要改进这篇文章？
在 GitHub 上编辑此页