关于这个网站

项目概述

这是 KeyBonk 团队的官方网站，托管在 GitHub Pages 上。整个网站是一个纯静态站点，没有后端服务器，所有页面都通过 Python 脚本预编译生成。

技术选型

为什么选择预编译？

最初的方案是客户端动态渲染：浏览器加载 Markdown 文件，用 JS 解析并渲染。这种方式简单但有明显缺点：

首屏白屏 — 需要等 JS 加载、解析 Markdown 后才能看到内容
SEO 不友好 — 搜索引擎爬虫拿到的是空壳 HTML
依赖 JS — 如果 JS 加载失败，页面完全空白

最终我们选择了预编译方案：用 Python 脚本在构建时把 Markdown 转成完整的 HTML，直接部署。好处是：

即时加载 — 服务器直接返回完整 HTML，无需等待 JS 渲染
SEO 友好 — 爬虫直接拿到完整内容
不依赖 JS — 即使 JS 失败，文章内容依然可见（只有代码高亮和交互受影响）

技术栈

构建脚本：Python + markdown-it-py
前端：原生 HTML / CSS / JS，无框架
代码高亮：highlight.js
部署：GitHub Pages
开源协议：WTFPL

架构设计

目录结构

keyBonk-org.github.io/
├── content/          # Markdown 源文件
│   ├── docs/         # 文档
│   └── blog/         # 博客
├── docs/             # 编译输出的文档 HTML
├── blog/             # 编译输出的博客 HTML
├── css/              # 样式文件
├── js/               # 脚本文件
├── imgs/             # 图片资源
└── build_site.py     # 构建脚本

构建流程

build_site.py 是核心构建脚本，流程如下：

扫描 content/ 下的 Markdown 文件，解析 frontmatter 元数据
递归构建目录树，生成侧边栏导航数据
将 Markdown 渲染为 HTML，提取标题生成文章目录（TOC）
拼接导航栏、侧边栏、内容区、目录栏、页脚，输出完整 HTML
写入对应的输出目录

Frontmatter

每篇 Markdown 文件以 JSON 格式的 frontmatter 开头，支持以下字段：

字段	说明
`title`	文章标题
`date`	发布日期（用于博客排序，格式：`YYYY-MM-DD HH:MM:SS`）
`author`	作者
`avatar`	作者头像路径
`summary`	摘要（显示在文章列表）
`tags`	标签数组
`id`	自定义 URL 路径（如 `001` → `/blog/001/`）
`weight`	排序权重（数字越小越靠前，默认按标题字典序）

页面布局

文档页：三栏布局 — 左侧边栏导航 + 中间内容 + 右侧文章目录
博客页：两栏布局 — 内容区 + 右侧文章目录
博客列表：单栏，文章卡片按日期降序排列
文档列表：左侧边栏 + 文章卡片

侧边栏导航支持多级目录嵌套，默认折叠，点击箭头展开/折叠，当前页面所在路径自动展开。

响应式设计

当屏幕宽度 ≤ 900px 时，导航栏简化为「Logo + GitHub + 主题切换 + 菜单按钮」，隐藏导航链接和搜索框，通过菜单按钮展开移动端菜单。

开发过程

这个网站从零开始搭建，经历了几次重大重构：

初始版本 — 客户端 JS 动态渲染 Markdown
重构 — 改为 Python 预编译 HTML，提升加载速度和 SEO
完善 — 逐步添加侧边栏导航、文章目录、代码高亮、响应式设计等功能

整个过程由我和网站维护者小狄协作完成：小狄提出需求和设计方向，我负责实现具体代码。

后续计划

搜索功能
更丰富的文档内容
性能优化

让每一次按键掷地有声！