Coding Space：一个 Markdown 静态知识站

项目解决的问题

本站把分散在目录中的 Markdown 转换成可浏览、可搜索的个人知识空间。内容源保留在仓库，构建输出是 HTML、CSS、JavaScript 和搜索索引，运行时不依赖数据库或后端接口。

这份说明基于仓库当前实现，用作项目入口与维护指南。

从内容到页面

content/ 下的 Markdown
  → build-site.js 扫描已配置的板块
  → 提取文章标题、生成页面地址、组织目录
  → 渲染正文、目录与跨文章链接
  → 写入 site/dist/ 与共享全文搜索索引
  → 静态托管或 serve-site.js 本地预览

核心文件与职责

本地运行与验证

在仓库根目录执行：

npm ci
npm run site:build
npm test
npm run site:serve

浏览器打开 http://127.0.0.1:4173。需要其他端口时执行 PORT=5000 npm run site:serve。

验证一次内容更新时，检查首页入口、文章正文、站内相对链接、页内目录和全文搜索。搜索可输入多个以空格分隔的关键词，结果需要同时包含这些词，最多显示 20 条。

为什么采用这样的结构

内容与页面分开，使写文章无需改 HTML。共享索引按需加载，使每一页无需重复携带整个板块的搜索数据。构建使用 Node.js、markdown-it 与任务列表扩展，浏览器端不加载 Markdown 解析器。依赖通过锁文件固定。

代价也很明确：当前支持嵌套列表、引用、表格、任务清单和本地图片复制。公式、Mermaid 图形及任意原始 HTML 尚未接入；完整支持范围见 Markdown 验收页。

新增内容的步骤

1. 按目的选择知识库、指南、实践、算法、项目或博客目录。
2. 写一个顶级标题，按问题拆分二级小节，代码块标明语言。
3. 用相对于当前 Markdown 的路径链接已有文章。
4. 构建并预览，确认搜索可以找到正文后半部分的词语。
5. 更新相关主题的阅读入口，让文章能从已有内容到达。

新增整个板块时，还需要更新构建脚本中的 CONTENT_GROUPS。移动或重命名文章可能改变页面地址，应先检查旧链接的影响。

后续改进的判断依据

全文索引随内容量增长，加载和过滤成本也会增加；应先测量实际索引大小与搜索响应，再决定是否分片。若文章需要复杂 Markdown、图片或公式，应先建立对应样例，再扩展渲染能力。部署地址确定后，才能可靠地生成 canonical URL 与 sitemap 等依赖域名的信息。

继续阅读：阅读地图、把零散笔记整理成知识系统。

更多项目：并发一致性实验、Markdown 渲染与图片验收。