纯 Markdown 博客的好处是：文章即数据、Git 即历史、部署可以很轻。本文总结一套在小型 Rust/Node 项目里反复验证过的目录约定，换框架也能照搬。
推荐目录结构
blog/
site.json # 站点名、导航、页脚
posts/ # 文章（一篇一个 .md）
hello-world.md
rust-axum-web-api.md
pages/ # 独立页面（关于、教程索引）
about.md
weekly/ # 周刊（可选）
data/ # JSON 数据（友链、资源列表）
posts/文件名即 slug：rust-axum-web-api.md→/blog/rust-axum-web-api- 图片放
static/或图床，Markdown 里用绝对路径/static/...或 HTTPS URL
Front Matter 最小字段
每篇文章顶部用 --- 包裹 YAML：
---
title: 文章标题
date: 2026-01-15
category: 技术分析
tags:
- Rust
- Web
excerpt: 列表页显示的摘要，一两句话说明文章价值。
---
| 字段 | 必填 | 说明 |
|---|---|---|
title | 是 | 列表与 <title> |
date | 是 | 建议 YYYY-MM-DD，用于排序 |
category | 是 | 分类筛选、侧栏统计 |
tags | 否 | 标签云、站内搜索 |
excerpt | 建议 | 首页卡片摘要；缺省时从正文截取 |
正文从第二个 --- 之后开始，支持标准 Markdown + 代码高亮。
启动时加载与排序
典型流程：
- 扫描
posts/*.md - 解析 YAML + Markdown 正文
- Markdown 转 HTML（
pulldown-cmark、marked等） - 按
date降序排序 - 放进内存缓存，文件变更时热重载或重启生效
伪代码：
posts.sort_by(|a, b| b.date.cmp(&a.date));
首页只取前 N 条，其余走分页 API——避免一次渲染几百篇。
excerpt 怎么写
好的 excerpt 像电梯演讲：
- ❌ 「本文介绍了 xxx 的相关内容。」
- ✅ 「用 Axum 搭建轻量 API：路由、状态、JSON 与错误处理四件事。」
60～120 字为宜，把读者能得到什么说清楚。
分类与标签策略
- 分类：粗粒度，5～8 个足够（如「技术分析」「资源分享」「周刊」）
- 标签：细粒度，技术栈、工具名、场景词
避免每篇文章一个独有分类，否则筛选没有意义。
写作与发布流程
本地编辑 .md → 预览（可选）→ git commit → 部署 / 上传后台
若带管理后台，流程可以是：
- 后台上传
.md到blog/posts/ - 服务重新加载缓存
- 首页、归档、搜索索引自动更新
比数据库 CMS 少一层「内容同步」问题。
常见问题
Q：中文文件名可以吗？ 建议 slug 用英文或拼音，URL 更干净，也避免编码坑。
Q：草稿怎么办？
可用 draft: true 自定义字段，加载时过滤；或放 posts/_drafts/ 不参与扫描。
Q：代码块语言标识？
写成 ```rust、```javascript，渲染器才能正确高亮。
Markdown 博客不是「过时方案」。它的核心是把内容留在自己手里。框架可以换，约定保持稳定，十年后仍能读懂今天写的文章。
评论