教程（三） 编写上传自己的博客文章

这篇讲怎么用 Markdown 编辑器写文章，再用 Hexo 命令把它发到博客上。前提是 Hexo 博客已经部署好。

准备一个 Markdown 编辑器

Markdown 是一种轻量级标记语言，创始人为約翰·格魯伯。它允许人们使用易读易写的纯文本格式编写文档，然后转换成有效的XHTML（或者HTML）文档。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。

写文章先要一个 markdown 编辑器。可选的很多，用的人比较多的有 MarkdownPad、BookPad、小书匠、typora 等。我用的是 typora，不过编辑器不同并不影响写博客，甚至不用专门的编辑器也能写得很好。

动笔前要学一点 Markdown 语法。有学习成本，但不高，收益却不小，以后日常写作、写技术文档都用得上：markdown基础语法教程

编辑器大多免费，这里只给一个下载链接，想用别的请自行搜索：markdownpad下载地址

这两个推荐今天都要打个折扣。Typora 已经收费，官网标价 14.99 美元，有 15 天试用，一份授权最多 3 台设备。MarkdownPad 官网还停在“New: Introducing MarkdownPad 2!”，支持的系统只列到 Windows XP 到 8，是个老软件了。

想要免费的，我会先推 VS Code：它自带 Markdown 支持，Ctrl+K V 就能边写边看预览，拖进来的图片还会自动复制到工作区。再就是 Obsidian，个人使用免费，不用注册，只有同步和发布服务另收费。

学语法时还会碰到一个小困惑：Markdown 没有唯一标准。格魯伯在 Daring Fireball 发布的最后一版是 2004 年的 1.0.1，后来社区整理出了 CommonMark 规范，GitHub 用的 GFM 又是 CommonMark 的严格超集。所以表格、任务列表这类写法，在某个编辑器里能显示，换个平台不一定行。

用 Hexo 命令写一篇文章

写文章要先在 Hexo 存放文章的位置建一个对应的 Markdown 文件，这要用到 Hexo 命令。常用命令和它们的作用见官方文档：hexo命令文档

不看文档也行，常用命令很少，也很简单。写一篇文章只需要下面几步：

1. 新建一篇 post：

$ hexo new post "post title with whitespace"

默认情况下，Hexo 用文章标题决定文件路径。对于独立页面，Hexo 会建一个以标题命名的目录，里面放一个 index.md 文件。

完整的命令是 hexo new [layout] <title>，layout 决定文件落在哪：

不写 layout 时，用的是 _config.yml 里 default_layout 的值，默认就是 post。标题里有空格要加引号，这也是上面例子带引号的原因。文件名由 new_post_name 控制，默认 :title.md。

2. 命令执行后，文章会以 “命名.md” 的形式出现在 Hexo 目录的 source/_posts 下：

3. 按路径打开文件写文章。注意正文要写在标签页下方：

文件顶部用 --- 夹住的那几行叫 front-matter，常用字段有 title、date、updated、tags、categories、permalink 等。注意只有文章支持分类和标签，给 page 写 tags 是没用的。

4. 写完后依次执行这三条命令，文章就上传好了：

 hexo clean   #清除缓存文件 db.json 和已生成的静态文件 public
 hexo g       #生成网站静态文件到默认设置的 public 文件夹(hexo generate 的缩写)
 hexo d       #自动生成网站静态文件，并部署到设定的仓库(hexo deploy 的缩写)

不放心的话，还可以用这条命令在 4000 端口先调试一下静态网页：

hexo s

做完这些，就能在博客上看到你的文章了：

三条命令各管什么

上面那三行注释有一处不准。按官方命令文档：

• hexo clean 删掉缓存 db.json 和生成目录 public；
• hexo g 把 source 生成成静态网页，放进 public；
• hexo d 只负责部署，本身不生成。

最后一条和上面注释里写的不一样，也最容易坑人。看 Hexo 源码，hexo d 只在 public 不存在时才顺手生成一次；public 还在，它就把上一次的产物直接推上去。所以只改了文章、只跑 hexo d，线上看到的还是旧内容。稳妥的写法是一行：

hexo clean && hexo g -d

-d 表示生成完接着部署，反过来 hexo d -g 是部署前先生成，效果一样。

g、d、s 这些缩写官方文档没写，但确实能用：Hexo 注册命令时用 abbrev 给每个命令名生成了唯一前缀。反过来，hexo c 同时撞上 clean 和 config，不成立，清理还是写全 hexo clean。

发不出去时先查这三处

写文章阶段最常见的三个问题，官方疑难解答里都有：

1. 生成时报 YAML 解析错误，比如 incomplete explicit mapping pair：front-matter 里的字符串带冒号，要用引号括起来。标题里写“教程：xxx”就会中招。
2. 改了文章，页面没变：缓存问题，hexo clean 再生成。
3. hexo s 报 Error: listen EADDRINUSE：4000 端口被别的程序占了，换个端口 hexo server -p 5000。

文章里的图片加载不出来怎么办

Markdown 里的图片是以路径或链接的形式出现的。第一次用 Markdown、又把文件挪到别的目录时，相对路径都可能失效，图片就加载失败了。解决办法见：如何解决博客中图片加载失败问题

现在你已经是一个成熟的博主了，开始输出自己的知识和文章吧！