教程（三）：使用 Markdown 编写并发布 Hexo 文章

博客搭好之后，下一步不是继续折腾主题，而是把文章写进去。这篇旧文记录的是最基础的一条发布链路：用 Markdown 写正文，用 Hexo 创建文章文件，本地确认页面，再生成并部署到博客。

先准备 Markdown 写作环境

Markdown 是一种轻量级标记语言。它用接近纯文本的写法表达标题、列表、链接、图片和代码块，再由工具转换成 HTML 页面。对个人博客来说，它的优点很直接：文件轻、可读性高、迁移成本低，也适合长期保存技术笔记。

编辑器不必纠结。早期常见选择有 MarkdownPad、小书匠、BookPad、Typora 等；现在使用 VS Code、Obsidian 或普通文本编辑器也可以。关键不是编辑器名字，而是先掌握少量基础语法：

• 用 #、##、### 组织标题层级；
• 用 - 或数字列表梳理步骤；
• 用反引号标记命令和代码；
• 用 [文字](链接) 插入链接；
• 用 ![说明](图片路径) 插入图片。

如果还不熟悉语法，可以先看一遍 Markdown 基础语法教程。旧文里还附过 MarkdownPad 下载地址，但这个工具已经不是今天的首选，只保留为当时文章的历史参考。

用 Hexo 新建文章文件

写 Hexo 文章前，需要先在项目里创建对应的 Markdown 文件。进入 Hexo 项目根目录后，执行：

hexo new post "post title with whitespace"

这条命令会创建一篇新的 post。默认情况下，Hexo 会根据文章标题生成文件路径，并把文章文件放到 source/_posts 目录。标题里有空格时，用引号包起来更稳。

创建完成后，可以在 Hexo 目录中看到新生成的 .md 文件。

打开这个文件后，顶部通常会有一段 Front Matter，用来记录标题、日期、标签等元信息。正文要写在这段元信息下面，不要写进 --- 包起来的配置区里。

本地预览并部署

文章写完后，先清理旧产物，再生成静态文件，最后部署：

hexo clean
hexo g
hexo d

这三条命令分别对应：

• hexo clean：清除缓存文件 db.json 和已经生成的 public 静态文件；
• hexo g：生成网站静态文件，是 hexo generate 的缩写；
• hexo d：按照部署配置发布网站，是 hexo deploy 的缩写。

如果不放心，可以在部署前先启动本地预览：

hexo s

默认情况下，Hexo 会在本机的 4000 端口启动服务。打开本地页面后，重点检查标题层级、代码块、链接和图片是否正常显示。确认没问题，再执行生成和部署。

部署完成后，文章就会出现在博客列表或归档页中。

图片无法加载时先查路径

Markdown 里的图片本质上是一段路径或链接。第一次从本地编辑器迁移到 Hexo 项目时，最常见的问题就是图片相对路径失效：编辑器里能看到，部署后的网页却加载不出来。

遇到这种情况，先确认三件事：

• 图片文件是否真的进入了 Hexo 会打包的资源目录；
• Markdown 中的图片路径是否指向部署后的公开访问路径；
• 生成后的页面里，图片链接是否和实际文件位置一致。

旧文把这个问题留给下一篇教程处理：如何解决博客中图片加载失败问题。

到这里，一篇 Hexo 文章从创建、写作、预览到部署的闭环就完成了。后面真正需要反复练习的，不是命令本身，而是稳定地写、稳定地检查、稳定地发布。

评论

发布评论