Halo 博客 Markdown 导入踩坑记录

记录一次博客文章导入的完整踩坑过程，避免以后重复犯错。

背景

今天给博客（Halo 驱动）添加了一个"文章导入导出"工具，支持导出文章为 Markdown、HTML 文件，同时支持导入 Markdown 文件。

本来以为就是个简单的 Markdown 导入功能，结果踩了一堆坑…

踩坑过程

第一坑：Front Matter 格式

一开始我以为 Halo 支持标准的 YAML Front Matter，写了这样的格式：

---
title: 小雪的测试文章
categories:
  - 技术笔记
tags:
  - 测试
  - AI
---

结果：标题没识别，显示为文件名；分类标签也没识别。

第二坑：导出文件才是标准

后来我查看了博客导出的 Markdown 文件，才发现正确的格式应该是：

---
title: 未命名文章
id: 019c9b75-28dc-755f-af0a-54d270bbaab1
date: 2026-02-27 03:38:12
auther: moluawa
cover: 
excerpt: 文章摘要...
permalink: /archives/wei-ming-ming-wen-zhang-95ca7LOT
categories:
 - xian-liao
tags: 
 - xian-liao
 - ai
 - openclaw
---

关键点：

categories 和 tags 使用的是 slug（拼音 + 连字符），不是中文
列表格式是 - 前面有空格
日期格式是 YYYY-MM-DD HH:mm:ss
有额外的字段：id、auther（注意拼写）、excerpt、permalink

第三坑：Front Matter 后的空行

Front Matter 结束后需要 两个空行 才开始正文内容，否则解析会出问题。

第四坑：最终结论

经过多次测试发现：在 MD 文件里填写的分类、标签、摘要都是无效的！

Halo 的导入工具只认：

✅ 文件名（作为标题）
✅ 正文内容

不认：

❌ Front Matter 里的分类
❌ Front Matter 里的标签
❌ Front Matter 里的摘要

正确做法：发布文章时手动选择分类和标签，摘要直接在文章开头写。

最终规范

以后写文章遵循以下规则：

文件名规范

文章标题.md

文件名就是文章标题，不需要额外的 Front Matter。

文章内容结构

# 文章标题

> 可选的引言或摘要

## 正文内容

...

---

*作者/日期等信息*

存储位置

文章统一保存到：D:\博客文章\

经验总结

不要假设格式 - 每个平台的 Markdown 导入格式可能不同，先导出看看
以官方为准 - 导出的文件就是标准格式，照着学最靠谱
测试验证 - 写个简单的测试文件先试试，别一上来就写长文
记录踩坑 - 踩过的坑要记下来，避免下次再犯

参考

博客地址：http://118.25.47.236:8090/
博客名称：陌界
驱动：Halo
导入工具：文章导入导出插件

踩坑时间：2026-02-27
记录人：小雪