不建 Hugo、不用 Hexo,纯 Markdown 文件也能接入 Coco-AI!

之前我们介绍过如何通过 Coco-AI 检索 Hugo 和 Hexo 的文件结构。这种方式虽然适合博客类内容,但对于一些零碎的笔记或者并非建站类的 Markdown 文件,显然不够灵活。

为了解决这个问题,我写了一个适配器(connector),并发布了对应的 Docker 镜像,来实现任意 Markdown 文件目录的元数据整理与 API 暴露

👉 镜像地址:https://hub.docker.com/r/cloudsmithy/flask-markdown-connector


核心原理

该 connector 的主要逻辑是:

  1. 递归扫描目录及子目录下的 Markdown 文件
  2. 识别或补充元数据(即 YAML Front Matter);
  3. 通过 RESTful API 暴露这些 Markdown 的结构信息和元数据内容

如下图所示,我们会在每个 Markdown 文件开头添加或提取出 YAML 元数据:

元数据展示

一键部署

使用以下命令即可快速拉起服务:

1
2
3
4
5
docker run -d --name markdown-connector \
-p 1313:5000 \
-v "$(pwd):/app/markdown" \
--restart always \
cloudsmithy/flask-markdown-connector

参数说明:

  • -d:后台运行容器;
  • --name markdown-connector:指定容器名称;
  • -p 1313:5000:将宿主机的 1313 端口映射到容器的 5000 端口;
  • -v "$(pwd):/app/markdown":将当前目录挂载进容器;
  • --restart always:配置容器异常退出后自动重启;
  • cloudsmithy/flask-markdown-connector:镜像名称。

API 一览

通过浏览器访问 http://localhost:1313/apidocs 即可打开内置 Swagger 文档。方便上层系统(如 Coco-AI)访问 Markdown 文件的元数据与内容。接口结构简洁直观,支持获取索引、刷新缓存、读取内容等功能。

Swagger 文档

🔹 GET /

功能:返回服务启动提示信息
说明:用于检查服务是否正常运行
示例响应

1
{ "message": "Markdown Connector is running." }

🔹 GET /api/posts

功能:获取生成的 index.json(缓存版)
说明:返回 Markdown 文件的路径与元数据列表,从缓存中读取,响应速度快
用途:Coco Server 可用作索引加载入口
示例响应

1
2
3
4
5
6
7
8
9
[
{
"title": "Docker 学习笔记",
"path": "dev/docker.md",
"tags": ["docker", "学习"],
"created": "2024-11-22"
},
...
]

🔹 GET /index.json

功能:实时渲染当前 Markdown 目录结构
说明:等价于 /api/posts,但是实时读取文件而非使用缓存,适合调试或手动使用
用途:确保数据为最新状态时使用


🔹 GET /api/refresh

功能:重新扫描并生成最新的 index.json 缓存
说明:用于强制刷新目录索引,适用于新增 / 修改了 Markdown 文件后
响应示例

1
{ "message": "Index cache refreshed." }

🔹 GET /posts/

功能:列出 Markdown 文件路径列表(不含元数据)
说明:返回所有可访问的 Markdown 文件路径,用于构建下拉菜单、快速跳转
响应示例

1
["notes/linux.md", "dev/docker.md", "ideas/gpt-agent.md"]

🔹 GET /posts/{filename}

功能:获取指定 Markdown 文件的内容
参数

  • {filename}:Markdown 文件路径(相对于挂载目录)

用途:用于前端点击跳转后展示具体笔记内容
响应示例

1
2
3
4
{
"filename": "dev/docker.md",
"content": "# Docker 学习笔记\n\n## 容器 vs 镜像 ..."
}

  • 用于 Coco Server,推荐使用 /api/posts 作为内容索引源;
  • 使用 /api/refresh 后再拉一次 /api/posts 可确保内容最新;
  • 若前端需要展示具体内容,可调用 /posts/{filename}
  • 若用在其他 AI 项目中,也可用于构建轻量级 Markdown 知识检索接口。

与 Coco Server 集成

在 Orbstack 中,我们可以清晰地看到本地 Markdown 文件已经映射到容器中:

Orbstack 文件映射

接着我们将 connector 的服务地址填入 Coco Server 配置中:

配置 Coco Server

你可以使用 /api/posts/index.json 接口,它们返回的内容基本一致:

  • /api/posts 是来自缓存的接口;
  • /index.json 是实时渲染本地文件结构。

另外,通过 /api/refresh 还可以手动触发缓存刷新:

刷新缓存


效果演示

成功接入后,Coco Server 就可以读取 Markdown 文件的结构与元数据信息:

Coco 成功抓取

点击条目还可以跳转到对应的网页:

跳转链接

当然,和之前一样,也支持在搜索栏中直接搜索并跳转:

搜索跳转


小结

通过这个 Flask 版 Markdown Connector,我们可以将任意 Markdown 文件目录结构化暴露给 Coco-AI,实现:

  • 笔记内容统一索引
  • 结构与元数据清晰可控
  • 快速部署,无需 Hugo/Hexo 建站

这对于日常碎片化笔记管理来说,是一个非常轻量又灵活的解决方案。

不建 Hugo、不用 Hexo,纯 Markdown 文件也能接入 Coco-AI!

https://xu-hardy.github.io/不建-hugo、不用-hexo,纯-markdown-文件也能接入-coco-ai!/

作者

Xu

发布于

2025-07-02

更新于

2025-07-01

许可协议

评论