Markdown 写作与 Hexo 博客发布完整指南:从新建文件到发布上线
Markdown 写作语法与 Hexo 博客发布完整指南
Markdown 是一种轻量级标记语言。它使用少量符号表示标题、列表、链接和代码等结构,写作时接近纯文本,发布后又能转换为排版清晰的 HTML。Hexo 则是一款基于 Node.js 的静态博客框架,可以把 Markdown 文章、主题和配置文件生成一个完整网站。
本文将从创建第一个 Markdown 文件开始,讲清楚 Markdown 常用语法、Hexo 文章头部配置、本地预览、正式发布、搜索引擎优化以及常见错误。即使你此前没有接触过 Markdown,也可以按照本文逐步完成一篇 Hexo 文章的发布。
本文中的命令默认在 Hexo 博客根目录执行。所谓“博客根目录”,就是包含
_config.yml、package.json、source和themes等文件或目录的位置。
一、Markdown 文件是什么
Markdown 文件通常以 .md 为扩展名,例如: hello-world.md 。
它本质上是一个 UTF-8 编码的纯文本文件,可以使用 VS Code、NotePad++、Vim、Obsidian 或普通文本编辑器打开。和直接编写 HTML 相比,Markdown 有三个明显优点:
- 容易阅读:即使没有转换成网页,源文件也有清晰的层级。
- 容易迁移:同一份内容可以用于 Hexo、GitHub、知识库或其他内容系统。
- 专注内容:写作者不需要反复处理字体、颜色和复杂标签。
Markdown 负责描述文章结构,真正显示出来的字体、颜色、间距和代码高亮通常由 Hexo 主题控制。因此,写文章时应该优先保证结构正确,而不是在正文里加入大量 HTML 样式。
二、创建 Markdown 文件
方法一:直接在编辑器中新建
打开代码编辑器,新建文件并保存为:我的第一篇文章.md 。
保存时建议选择 UTF-8 编码,否则中文可能出现乱码。
直接创建的文章文件需要放到 你的博客目录/source/_posts/ 。
方法二:使用 Hexo 命令创建
在博客根目录打开终端,执行:hexo new post "我的第一篇文章"
post 是 Hexo 默认的文章布局,因此也可以简写为:hexo n "我的第一篇文章"
创建成功后,文件会自动生成到对应目录中:
1 | source/_posts/我的第一篇文章.md |
Hexo 会根据 scaffolds/post.md 模板自动生成文章头部。你可以修改这个模板,让以后新建的文章自动包含分类、标签和描述等字段。
三、必须理解的 Front Matter
Hexo 文章最上方由两组 --- 包围的区域叫作 Front Matter。它不是正文,而是文章的元数据。
1 |
|
常用字段说明如下:
| 字段 | 用途 | 注意事项 |
|---|---|---|
title |
文章标题 | 应准确概括内容,不要堆砌关键词 |
date |
发布时间 | 建议使用 YYYY-MM-DD HH:mm:ss |
updated |
最后更新时间 | 内容有实质更新时再修改 |
categories |
文章分类 | 一篇文章通常设置一个主要分类 |
tags |
内容标签 | 建议使用少量高度相关的标签 |
description |
页面摘要 | 部分主题会用作搜索摘要或元描述 |
permalink |
自定义固定链接 | 发布后不要频繁修改,以免旧链接失效 |
cover |
文章封面 | 是否生效取决于当前主题 |
comments |
是否启用评论 | 是否支持取决于主题和评论插件 |
Front Matter 使用 YAML 格式,缩进必须一致,通常使用两个空格,不能使用 Tab 代替缩进。标题或描述中包含冒号、井号等特殊字符时,建议用单引号包起来:
1 | title: 'Hexo 教程:从本地写作到正式发布' |
不要在开头的 --- 之前放空格、正文或不可见字符,否则 Hexo 可能把 Front Matter 当作普通文字显示。
四、Markdown 常用语法
1. 标题
Markdown 使用井号表示标题:
1 | # 一级标题 |
在 Hexo 文章中,文章名称通常已经由主题显示为一级标题。正文建议从二级标题 ## 开始,并按照 ##、###、#### 的顺序逐级使用,不要为了字体大小跳级。
标题符号后必须保留一个空格:
1 | ## 正确写法 |
清晰的标题层级既方便读者浏览,也有利于主题自动生成文章目录。
2. 普通段落与换行
连续文字会组成一个段落。开始新段落时,应在两段之间保留一个空行:
1 | 这是第一段内容。 |
不要用大量空格或连续回车调整页面距离,具体间距应该交给主题样式控制。
3. 粗体、斜体与删除线
1 | **这是粗体** |
显示效果分别为:这是粗体、这是斜体、这是删除线。
强调格式应该服务于阅读。整段加粗或在每句话中重复加粗,会让页面显得杂乱,也会削弱真正重点的辨识度。
4. 无序列表
1 | - Markdown 源文件容易维护 |
显示效果:
- Markdown 源文件容易维护
- Hexo 可以生成静态网页
- Git 可以保存修改历史
- 星号也可以用于无序列表
子列表需要缩进:
1 | - 博客内容 |
显示效果:
- 博客内容
- 教程
- 使用记录
- 网站页面
- 关于
- 隐私政策
- 星号列表
- 星号缩进列表
5. 有序列表
1 | 1. 新建文章 |
当顺序会影响结果时使用有序列表;如果各项没有先后关系,则使用无序列表。
6. 引用
在段落前添加 > 可以创建引用:
1 | > 发布前先进行本地预览,可以提前发现链接、图片和排版错误。 |
显示效果如下:
发布前先进行本地预览,使用命令
hexo server或hexo s,可以提前发现链接、图片和排版错误。
引用他人的观点时,应注明作者和来源并添加链接。不要把从其他网站复制的长段落当作自己的原创内容。
7. 行内代码与代码块
命令、文件名和配置字段适合使用行内代码:
1 | 运行 `hexo server` 启动本地预览。 |
多行代码使用三个反引号包围,并在开头标明语言:
1 | ```javascript |
显示效果:
1 | const siteName = '我的 Hexo 博客'; |
标明语言后,支持该语言的 Hexo 主题会进行语法高亮。代码必须经过实际验证;涉及删除文件、覆盖配置或修改权限的命令,还应说明风险和适用环境。
8. 链接
1 | [Hexo 官方文档](https://hexo.io/docs/) |
链接文字应说明目标页面,不建议大量使用“点击这里”这类含义不清的文字。发布前应逐一检查外部链接是否有效。
站内文章可以使用完整固定链接,也可以使用 Hexo 的 post_link 标签。使用完整链接容易理解:
1 | [另一篇 Hexo 教程](/hexo-hosting-github-vs-cloudflare.html) |
使用 Hexo 标签可以在文件名变化时更稳妥地定位文章,但语法会受 Hexo 处理:
1 | {% post_link 文章文件名 '显示文字' %} |
9. 图片
标准 Markdown 图片语法为:
1 |  |
显示效果为:
图片和链接的区别就在于方括号之前的 !。
方括号中的替代文字不是装饰,它会在图片无法加载时显示,也能帮助无障碍阅读和搜索引擎理解图片内容。应具体描述图片,例如:
1 |  |
不要写成没有信息量的 ![图片],也不要在替代文字中堆砌关键词。上面的图片显示失败就是因为图片不存在,无法加载所以就显示了替代文字。
图片可以存放在 source/images/ 中,然后使用从网站根目录开始的路径:
1 | source/images/hexo-local-preview.webp |
文章内引用:
1 |  |
如果 _config.yml 中启用了 post_asset_folder: true,也可以为每篇文章建立同名资源目录。不过不同主题、渲染器和图片插件的引用方式可能不同,启用前应先在本地验证。
为了提升页面加载速度,建议:
- 上传前压缩图片;
- 照片优先考虑 WebP 或经过压缩的 JPEG;
- 图标、截图按实际显示尺寸导出;
- 不要仅用图片呈现关键文字和操作步骤;
- 确认图片拥有使用权,必要时标明来源与许可。
关于博客或网站加载图片适用哪些格式,我们后续会讲。
10. 表格
1 | | 命令 | 作用 | |
显示效果为:
| 命令 | 作用 |
|---|---|
hexo clean |
清理旧的生成文件 |
hexo generate |
生成静态网站 |
hexo server |
启动本地预览 |
hexo deploy |
按配置部署网站 |
表格适合比较结构一致的信息。手机屏幕较窄,因此不要制作列数过多、单元格内容过长的表格。
11. 分隔线
单独一行输入三个短横线可以创建分隔线:
1 | --- |
显示效果为:
注意:文章开头的 --- 是 Front Matter 边界,正文中的 --- 才是分隔线。而且这里的 --- 要和上下文之间隔开空行,否则不会生效。
12. 任务列表
1 | - [x] 完成文章初稿 |
显示效果为:
- 完成文章初稿
- 本地检查排版
- 发布到正式网站
是否显示为可勾选样式取决于 Markdown 渲染器和主题,但即使没有交互功能,列表内容通常仍能正常显示。
13. 特殊字符转义
如果想直接显示 Markdown 符号,可以在符号前加反斜杠:
1 | \*这段文字不会变成斜体\* |
显示效果为:
*这段文字不会变成斜体*
当内容中出现模板标签、花括号或 HTML 时,还应留意 Hexo 使用的渲染器是否会进行额外处理。
五、一篇高质量教程文章应该怎样组织
语法正确只是基础。真正有价值的教程应帮助读者解决一个明确问题。可以采用以下结构:
- 开头说明目标:读者完成后能得到什么结果。
- 列出适用条件:操作系统、软件环境和前置知识。
- 给出完整步骤:每一步说明操作、预期结果和判断成功的方法。
- 解释关键原因:不仅告诉读者“输入什么”,还说明为什么这样做。
- 处理常见错误:列出错误现象、原因和解决办法。
- 提供复查清单:方便读者在发布前逐项确认。
- 标注更新时间:软件和平台规则变化后及时修订。
教程中的截图只能辅助说明,不能替代文字。搜索引擎和使用屏幕阅读器的访客都需要可读的文字步骤。对命令输出、报错信息和配置值,应尽量使用可复制的文本,而不是只放一张截图。
六、在 Hexo 中预览文章
文章写完后,不要直接发布。先在博客根目录启动本地服务器:
1 | hexo server |
如果系统提示找不到 hexo 命令,可以使用项目本地版本:
1 | npx hexo server |
终端通常会显示类似地址:
1 | http://localhost:4000/ |
在浏览器中打开该地址,重点检查:
- 标题、日期、分类和标签是否正确;
- 目录层级是否连续;
- 代码块有没有被截断;
- 图片能否加载,替代文字是否准确;
- 站内链接和外部链接能否打开;
- 电脑和手机宽度下是否都能正常阅读;
- 是否存在错别字、残缺段落和占位内容。
修改 Markdown 文件后,Hexo 通常会自动重新生成页面。若页面没有更新,可以停止服务器后清理缓存并重新启动:
1 | hexo clean 或 hexo cl |
停止本地服务器时,在终端按 Ctrl + C, 有时可以使用 Ctrl+Shift+R 强制浏览器清除缓存后刷新页面。
七、生成静态网站
确认预览无误后,执行:
1 | hexo clean |
也可以使用缩写:
1 | hexo clean |
命令含义如下:
| 命令 | 作用 |
|---|---|
hexo clean |
删除旧缓存和旧的 public 生成结果 |
hexo generate |
根据文章、主题和配置生成静态文件 |
生成完成后,网站文件通常位于 public/ 目录。这个目录是构建结果,不是文章源文件。正常情况下,应修改 source/_posts/ 中的 Markdown,而不是直接修改 public/,因为下次生成时手动修改的内容会被覆盖。
八、发布 Hexo 博客的三种常见方式
方式一:使用 Hexo Deployer
先安装 Git 部署插件:
1 | npm install hexo-deployer-git --save |
然后在站点 _config.yml 中配置部署目标。下面仅为结构示例,仓库地址和分支要替换成自己的实际值:
1 | deploy: |
执行生成和部署:
1 | hexo clean |
也可以组合为:
1 | hexo clean |
使用这种方式前,要确认 Git 身份验证、目标分支和网站根路径已经正确配置。不要把 GitHub Token、私钥或其他凭据直接写进文章、公开仓库或 _config.yml。
方式二:推送源码,由 GitHub Actions 自动构建
这种方式会把 Hexo 源码推送到 GitHub,再由工作流安装依赖、运行构建并发布。日常写作流程通常是在博客根目录下执行下面的命令:
1 | git status |
推送后,到仓库的 Actions 页面查看构建状态。只有工作流成功完成且 Pages 设置正确,网站内容才会真正更新。
源代码仓库中不要提交以下敏感内容:
- API Key、Token、私钥和密码;
- 含个人隐私的配置或日志;
.env等本地环境文件;- 未经授权的图片、字体和付费资源。
方式三:由 Cloudflare Pages 等平台自动构建
托管平台连接 Git 仓库后,通常需要设置:
1 | 构建命令:npm run build |
Hexo 项目的 package.json 一般会把 npm run build 映射到 hexo generate;如果部署失败就要将构建命令改为 npx hexo generate,具体要以自己项目中的 scripts 配置为准,不能盲目照抄。
自动构建失败时,先查看部署平台的构建日志,重点检查 Node.js 版本、依赖安装、构建命令、输出目录和环境变量。
九、文章发布后的验证
部署显示成功并不等于文章一定可访问。发布后还应进行以下验证:
- 使用无痕窗口打开文章的正式网址;
- 确认页面返回正常内容,而不是 404 或重定向循环;
- 检查 HTTPS 是否有效;
- 点击目录、分类、标签、上一篇和下一篇链接;
- 检查图片、代码复制按钮和移动端菜单;
- 查看网页源代码,确认标题和描述已正确生成;
- 将站点地图提交到 Google Search Console;
- 修复 Search Console 报告的抓取、索引和移动端体验问题。
如果使用缓存或 CDN,网站更新可能不会立即出现在所有节点。可以先确认部署产物是否正确,再按托管平台的规则清理缓存,不要反复修改文章来碰运气。
十、常见错误与解决方法
1. 中文显示乱码
可能原因:Markdown 文件不是 UTF-8 编码。
解决方法:在编辑器中以 UTF-8 重新保存。还应检查主题模板和配置文件的编码,不要只修改浏览器设置。
2. Front Matter 显示在正文中
可能原因:
- 文件开头的
---不完整; ---前出现了其他字符;- YAML 缩进错误;
- 引号没有成对闭合。
解决方法:用最小化 Front Matter 测试,然后逐项恢复字段,定位出错的配置。
3. 执行命令后找不到 Hexo
可以先确认当前目录包含 package.json,再执行:
1 | npm install |
项目本地安装通常比依赖全局版本更容易保持团队和构建环境一致。
4. 新文章没有出现在首页
检查以下项目:
- 文件是否位于
source/_posts/; - 是否误建成了草稿;
date是否设置成未来时间;- Front Matter 中是否设置了
published: false; - 本地缓存是否仍是旧版本;
- 主题是否启用了隐藏文章的自定义字段。
5. 图片本地正常,线上无法显示
常见原因包括:
- 路径大小写不一致;
- 使用了本地磁盘路径;
- 图片没有提交到仓库;
- 站点部署在子目录,但根路径配置不正确;
- 图床开启了防盗链或图片已被删除。
Linux 构建环境通常区分大小写,因此 Cover.webp 和 cover.webp 会被视为两个不同文件。
6. 修改后线上内容没有变化
按顺序检查:
- Markdown 文件是否已经保存;
- Git 提交是否包含该文件;
- 推送的分支是否为部署平台监听的分支;
- 自动构建是否成功;
- 输出目录是否正确;
- 浏览器或 CDN 是否仍在使用缓存。
7. 永久链接出现 404
修改 permalink 或文件名后,旧网址可能失效。应尽量保持已发布文章的网址稳定;确实需要修改时,应在托管平台设置从旧地址到新地址的永久重定向,并同步更新站内链接和站点地图。
十一、面向搜索引擎的基础优化
SEO 的核心不是重复关键词,而是让页面准确、完整地满足读者需求。
标题
标题应该具体说明主题和结果。例如“Markdown 写作与 Hexo 发布完整指南”比“我的学习笔记”更容易让读者判断文章是否有用。不要用与正文无关的夸张标题吸引点击。
摘要
description 应使用自然语言概括文章解决的问题。每篇重要文章尽量使用独立摘要,不要复制同一段模板。
内容结构
一个页面只围绕一个主要主题展开。使用连续的标题层级、短段落、步骤列表和必要的表格,让读者能快速定位信息。
站内链接
在相关内容之间建立自然链接,例如从 Hexo 安装教程链接到本文,再从本文链接到部署排错教程。链接应真正帮助读者继续解决问题,而不是机械地给每段文字添加链接。
内容维护
软件版本、平台界面和政策会变化。发现步骤失效后应及时修订,并更新 updated 日期。不要仅修改日期却不更新正文。
十二、申请 Google AdSense 前需要注意什么
博客的内容丰富之后,可以申请Google Adsense来创收,这个和Youtube Adsense申请是一样的,如果已经通过YPP了,那就共用一个Adsense账号。
先说明一个重要事实:没有任何单篇文章、固定字数、文章数量或模板能够保证 AdSense 审核通过。 Google 会评估整个网站,最终结果以 AdSense 后台和审核通知为准。
根据 Google 官方说明,申请网站应具备原创且有价值的内容、清晰可用的导航,并符合 AdSense 计划政策和 Google 发布商政策。审核可能涉及整个网站,而不只是提交申请时填写的首页。
1. 提供原创、完整、对读者有帮助的内容
一篇适合长期运营的教程,应该包含作者自己的验证、解释、经验和排错方法。只替换标题、拼接多篇文章、批量生成缺少核验的页面,不能为读者提供可靠价值。
发布本文前,建议你结合自己的实际网站进行二次完善,例如:
- 加入自己使用的操作系统和 Hexo 环境;
- 放入自己拍摄或制作的步骤截图;
- 记录真实遇到的错误及解决过程;
- 补充与你当前主题相匹配的配置;
- 删除自己没有验证过的部署方式。
这些内容会让文章真正属于你的站点,也能减少读者照做后遇到偏差。
2. 建立清晰的网站导航
网站菜单至少要让访客容易找到首页、文章分类和重要说明页面。检查是否存在空分类、打不开的菜单、循环跳转、仅登录可见内容、大量弹窗或仍显示“建设中”的页面。
3. 完善网站身份与联系信息
建议根据网站实际情况提供:
- 关于页面:说明网站主题、作者背景和内容范围;
- 联系页面:提供有效且愿意公开的联系渠道;
- 隐私政策:说明网站使用的统计、Cookie、广告和第三方服务;
- 免责声明:对于技术操作、外部链接或特定领域内容说明责任边界。
其中,隐私披露不是装饰。Google 发布商政策要求发布商说明因使用 Google 产品和服务而发生的数据收集、共享和使用,包括 Cookie、网络信标、IP 地址或其他标识符等技术。隐私政策应根据网站实际使用的服务和适用地区法律编写,不能直接复制一份与实际情况不符的模板。
4. 确保网站完整可访问
申请前逐项检查:
- 网站已经正式上线,不是空主题或半成品;
- 主要页面无需登录即可访问;
- 没有大面积空白页、测试页和重复页;
- 导航、分页、分类、标签和文章链接有效;
- 移动端可以正常阅读;
- HTTPS 正常,域名没有安全警告;
robots.txt没有误拦截重要页面和广告审核抓取;- 页面加载速度处于合理水平;
- 文章以完整句子和段落为主,而不是只有图片或标题。
5. 遵守内容和流量政策
站长需要对展示广告页面上的内容负责,包括评论区等用户生成内容。不要发布侵权、抓取、误导或其他违反 Google 发布商政策的内容,也不要购买虚假流量、参加付费点击计划或诱导访客点击广告。
广告上线后,不能使用“支持本站请点击广告”等文字,也不能把广告伪装成下载按钮、导航或正文链接。站长本人也不应点击自己网站上的广告。
6. 不要迷信“最低文章数量”和“最低字数”
Google 官方要求强调的是独特、有趣、高质量的内容和良好用户体验,而不是一个公开的固定文章数量或统一字数。十篇空泛文章不一定比五篇经过实际验证的完整教程更有价值。
更实用的判断方式是:
- 每个主要分类是否都有实际内容;
- 读者能否仅凭文章完成目标;
- 是否解释了关键步骤与风险;
- 是否有大量相似、重复或自动生成页面;
- 网站是否仍留有演示文字和空白页面;
- 内容是否能体现作者的经验与判断。
7. 官方资料
政策和产品流程可能调整,申请前应再次查看最新官方说明:
十三、发布前最终检查清单
内容检查
- 标题准确描述文章内容
- 开头明确说明读者能解决什么问题
- 操作步骤已经亲自验证
- 命令、路径和配置值没有明显错误
- 引用内容已注明来源
- 图片拥有使用权并包含准确替代文字
- 没有未完成段落、占位符或演示文字
- 文章包含自己的经验、解释或实际案例
Markdown 与 Hexo 检查
- 文件使用 UTF-8 编码
- Front Matter 能被正常解析
- 标题层级没有无故跳级
- 代码块的反引号成对闭合
- 图片、站内链接和外部链接有效
- 本地预览没有明显排版问题
-
hexo generate执行成功 - 正式网址可通过无痕窗口访问
网站与 AdSense 检查
- 网站导航清楚且所有主要链接可用
- 已建立符合实际情况的关于、联系和隐私政策页面
- 没有空页面、测试页面或大面积重复内容
- 手机端可正常浏览
- 网站使用 HTTPS
- 没有政策禁止的内容或误导性功能
- 流量来源真实,不诱导广告点击
- 已阅读最新的 Google 官方政策
十四、总结
使用 Markdown 发布 Hexo 博客,可以归纳为一条稳定的流程:
1 | 明确读者问题 |
Markdown 语法并不复杂,真正决定文章质量的是内容是否准确、完整、原创并能解决实际问题。对于准备申请 AdSense 的博客,与其追求所谓“快速过审模板”,不如持续完善网站结构、写出经过验证的原创内容、公开必要的站点信息,并长期遵守发布商政策。
完成第一篇文章后,可以把本文的 Front Matter 和检查清单整理到 scaffolds/post.md 中,形成自己的写作模板。这样以后每次新建文章,都能从一致、可靠的结构开始。














