Static Markdown API on Cloudflare Workers

这是一个基于 Cloudflare Workers 和 Hono 框架构建的极速、纯静态 Markdown API 驱动项目。

它的核心理念是将你的 .md 文件在部署前（构建阶段）直接转换为结构化的 JSON 数据，并打包进 Worker 中随边缘节点分发。无需数据库 (No KV / No SQL)、无需频繁调用外部 API (不受 GitHub API 限制)，实现毫秒级响应的极速访问。

✨ 特性

• 🚀 极致响应：数据内存在 Cloudflare 边缘节点直出。
• 📝 Markdown 友好：支持自动将 Markdown 构建并转换为 HTML，也可原样保留。
• 📦 零依赖数据库：无外部请求，零延迟，完全免费托管。
• 🛠 自动化构建：使用 Wrangler Custom Builds 自动监听并打包 Markdown，开发热更新。

---

🚀 快速开始

本项目强制要求使用 pnpm 作为包管理器。

1. 安装依赖

pnpm install

2. 撰写文章

直接在项目根目录的 posts/ 文件夹下按规范创建 Markdown (.md) 文件即可，例如： posts/hello-world.md

💡 提示：文章的标题将自动提取第一行作为一级标题（# Title），如果不写则默认使用文件名。

3. 本地开发调试

pnpm dev

运行后，会自动生成静态数据，并在本地 http://127.0.0.1:8787 开启开发服务器。每次修改 posts/ 目录下的文章，会自动触发重新构建（热更新）。

4. 部署到 Cloudflare

pnpm deploy

一键将应用与你的 Markdown 内容打包部署至全球网络。

---

⚙️ 配置说明

你可以在项目根目录的 config.ts 文件中轻松调整全局行为：

export const config = {
  // 默认分页条数（默认：20）
  pageSize: 20,
  
  // 列表返回时的文章摘要截取最大长度（默认：150字符）
  excerptLength: 150,
  
  // 详情接口返回的文章内容格式：
  // - 'html': 自动将 Markdown 渲染为 HTML 返回
  // - 'markdown': 原样保留 Markdown 源码供前端在客户端渲染
  returnFormat: 'html', 
  
  // 在本地存放 Markdown 文件的文件夹名（默认：'posts'）
  postsDir: 'posts',
};

---

🪧 API 接口文档

1. 获取文章列表（支持分页）

• Endpoint: GET /api/posts
• Query 参数:
  • page (可选): 请求的页码，默认为 1。
  • limit (可选): 每页数据量，未传则使用 config.ts 中配置的 pageSize。
• 返回值示例:

  {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1,
    "data": [
      {
        "filename": "hello-world",
        "title": "Hello World",
        "date": "2026-04-18T10:00:00.000Z",
        "excerpt": "这是第一篇文章测试。一切都是静态自动构建的！没有数据库，没有请求限制！...",
        "coverImage": "https://img.alicdn.com/imgextra/i3/xxx-fleamarket.png"
      }
    ]
  }

💡 字段自动提取魔法：

• coverImage (封面图)：构建引擎会自动扫描并提取整篇 Markdown 文章里的第一张图片链接。这大大方便了前端渲染列表卡片配图，如果文章无图则返回 null。
• excerpt (摘要)：会自动截取开头纯文字，并剥离掉可能引发排版错乱的换行 (\r\n) 以及所有的 Markdown 标记和内联图片，形成清爽的纯文本预览介绍。
• ⚠️ 注意：为了缩小请求带宽极速响应，列表接口不包含 content 此完整正文内容。

2. 获取单篇文章详情

• Endpoint: GET /api/post/:filename
• Path 变量:
  • :filename 为 Markdown 文件的名称（不包含 .md 后缀）。如 posts/demo.md 则对应请求 /api/post/demo。
• 返回值示例:

  {
    "filename": "hello-world",
    "title": "Hello World",
    "date": "2026-04-18T10:00:00.000Z",
    "content": "<h1>Hello World</h1>\n<p>这是第一篇文章...</p>"
  }

若 config.ts 的 returnFormat 设置为 markdown，则 content 将返回原始的 Markdown 文本结构。