跳到主要内容

Markdown TOC 生成后,还要留意标题改名

· 阅读需 2 分钟
一介布衣
全栈开发者

Markdown 目录自动生成刚用起来时,体验通常都很好。
大纲一键出来,长文章可读性立刻上去,写作者自己也更容易把结构收住。但 2017 年我在持续写技术文档和博客时,慢慢发现目录真正麻烦的地方,不在生成那一刻,而在后面你继续润色标题的时候。

编辑器预览、命令行导出、线上渲染最好共用一条 Markdown 流水线

· 阅读需 3 分钟
一介布衣
全栈开发者

Markdown 真正进入团队使用后,通常不会只经过一种渲染方式。编辑器里要实时预览,命令行里要批量导出,线上站点还要再做一次正式渲染。只要这三条链路的规则不一致,内容就会慢慢长出很多“本地看着没问题,上线以后才发现不对”的小坑。

给 Markdown 站内搜索建索引时,正文和导航要分开处理

· 阅读需 3 分钟
一介布衣
全栈开发者

静态站点的搜索一开始看起来很简单:把页面内容抓出来,做个索引,前端输入关键字再匹配就行。真做起来以后,经常会发现搜索结果里全是“上一篇、下一篇、文章目录、相关文章”这些导航文字,真正想找的正文反而被稀释了。

Markdown 目录自动生成前,先把标题锚点规则定死

· 阅读需 3 分钟
一介布衣
全栈开发者

很多人第一次做 Markdown 目录自动生成,注意力都会放在“怎么把标题列出来”上。真到了文档越来越多、开始需要分享链接和长期维护的时候,问题往往不是目录能不能生成,而是同一篇文章在编辑器预览、导出的 HTML、线上静态页里,标题锚点是不是完全一致。

UCloud 磁盘扩容后,真正要确认的是挂载和开机自动挂载

· 阅读需 2 分钟
一介布衣
全栈开发者

云服务器磁盘扩容这件事,很多时候会被理解成“容量加上了就结束”。
但 2016 年我自己处理这类操作时,越来越不敢只看控制台上的容量变化。因为真正决定这次扩容有没有落地到系统可用状态的,往往不是云平台页面,而是机器里挂载点和开机自动挂载有没有确认好。