白山的技术手记Site Wiki

Site Wiki

网站实现说明

由 Markdown 技术文档生成的 wiki 页面。公开版已对敏感服务器信息做占位符脱敏。

返回技术导航 返回首页文章
Source: 01-site-implementation.md

1. 技术栈

这个网站是一个纯静态站点，核心技术非常直接：

  • 页面：手写 HTML
  • 样式：单文件 styles.css
  • 交互：单文件 site.js
  • 代码高亮：本地 vendored Prism
  • 图表：Mermaid 11，通过 CDN 按页面加载
  • 媒体：本地图片、GIF、备案图标

没有使用以下能力：

  • 没有前端框架
  • 没有打包器
  • 没有模块化构建
  • 没有 CMS
  • 没有模板编译或服务端渲染

这意味着站点部署简单、结构透明，但页面复用和批量维护依赖人工一致性。

2. 目录结构

text
www/
  index.html
  styles.css
  site.js
  projects/
    echo.html
  posts/
    index.html
    three-layer-architecture.html
    facts-function-calling.html
    play-systems.html
    experiment-and-thesis.html
  assets/
    img/
    vendor/prism/

结构上可以分成四层：

  • 根目录：站点公共入口与全局资源
  • projects/：项目专题页
  • posts/：文章页与文章目录
  • assets/：图片、背景、图标、Prism 依赖

3. 页面分型

首页 index.html

职责：

  • 展示博客定位
  • 突出《回声》项目
  • 汇总近期文章
  • 提供主题切换和主导航

特点：

  • 英雄区使用 SVG 曲线装饰
  • 项目卡片与文章卡片使用统一玻璃风格
  • 页面本身不承载复杂脚本逻辑，主要依赖全局脚本增强体验

项目页 projects/echo.html

职责：

  • 承担《回声》的总览页
  • 用截图、玩法循环、架构图和文章入口组织项目信息

特点：

  • 引入 Mermaid，用于循环图、架构图和结局流程图
  • 作为内容枢纽，指向四篇技术文章的具体章节

文章目录 posts/index.html

职责：

  • 作为技术内容的轻量入口页
  • 保持文章列表清晰，不引入过多交互

文章页 posts/*.html

职责：

  • 展开单一技术主题
  • 组合正文、代码块、图示、节标题与目录锚点

特点：

  • 由 site.js 动态插入右侧“本文目录”
  • 某些文章按需引入 Mermaid
  • 使用 Prism 高亮代码

4. 样式系统

4.1 主题变量

styles.css 以 :root 和 :root[data-theme="dark"] 管理主题变量，核心变量包括：

  • 文本：--ink、--muted、--dim
  • 背景：--bg、--surface、--panel
  • 强调色：--signal、--amber、--cyan
  • 玻璃拟态：--glass-bg、--glass-border
  • 阴影：--shadow
  • 最大内容宽度：--max

这套变量的价值在于：

  • 明暗主题切换成本低
  • 大部分组件无需改结构，只需依赖变量
  • 页面视觉风格统一

4.2 视觉语言

站点并不是传统的极简白底博客，而是混合了以下特征：

  • 玻璃拟态卡片 .glass
  • 网格与径向渐变背景
  • 轻量动效与滚动显现
  • 项目页上的大图英雄区
  • 等宽字体用于元信息、目录标签和代码相关元素

视觉上它更像“项目档案 + 技术手记”的混合体，而不是纯文字博客。

4.3 布局模式

常见布局抽象如下：

  • .section：统一章节宽度与留白
  • .hero / .blog-hero / .post-hero：不同页面头图区
  • .featured-project、.article-grid、.capture-grid：卡片与栅格布局
  • .post-content：正文阅读列
  • .wide-figure：图片或图表容器

正文区固定为 width: min(880px, 100%)，但长时序图通过 .post-content .sequence-figure 额外扩宽到 1320px，避免图示被窄列压缩。

5. 全局脚本职责

site.js 目前是站点唯一的全局行为层，负责以下能力：

  1. 加载遮罩与进度条
  2. 自动/手动主题切换
  3. Mermaid 初始化与 SVG 修正
  4. Prism 代码高亮二次处理
  5. 页面转场动画
  6. 滚动显现 reveal
  7. 项目专题悬浮书签
  8. 文章页悬浮目录
  9. hover 倾斜与磁吸效果

这是一种“单脚本集中管理”的实现方式，优点是部署简单，缺点是职责较多，后续扩展时会增加阅读成本。

6. 第三方依赖集成

6.1 Prism

Prism 通过本地文件加载：

  • assets/vendor/prism/prism.js
  • prism-csharp.min.js
  • prism-json.min.js
  • prism-autoloader.min.js

site.js 中会：

  • 将 Prism 设为手动模式
  • 为缺失语言类的代码块自动推断 json 或 csharp
  • 设置 autoloader 的 languages_path

这种方式适合内容型站点，因为它不需要额外打包工具。

6.2 Mermaid

Mermaid 只在需要图表的页面按需加载。当前实现要点如下：

  • 页面中把 Mermaid 源码放在 <script type="text/plain" class="mermaid-source">
  • site.js 查找 .mermaid-figure，调用 mermaid.render
  • 渲染后把 SVG 塞回 .mermaid-output
  • 通过 adjustMermaidViewBox() 修正边界、padding、底部空间与长时序图裁剪问题

当前已经加入的重要修正：

  • mirrorActors: true
  • 清理 clip-path 和 mask
  • 根据实际内容重算 viewBox
  • 显式写入 width、height、aspect-ratio
  • 通过 data-viewbox-* 属性做页面级微调

7. 响应式策略

站点的响应式主要依赖三组断点：

  • 1040px：调整书签面板和正文布局
  • 920px：将多列布局折叠成单列
  • 560px：压缩头图、图表和页脚布局

设计原则偏向：

  • 桌面端重点展示大图、侧边目录和专题书签
  • 移动端优先保证可读性和滚动顺序

8. 当前实现特点与风险

优点

  • 结构简单，便于直接修改
  • 视觉统一，项目气质明确
  • 页面间关系清楚，内容漏斗完整
  • 图表、代码块、截图三类技术展示手段都已具备

风险

  • 模板重复：头部、页脚、依赖引入在多个 HTML 中重复维护
  • 版本控制依赖手工：资源 cache busting 通过查询参数手动维护
  • 路径依赖相对引用：页面层级变化时容易出错
  • site.js 职责集中：后续扩展容易变成长脚本维护负担
  • 部分界面字符串在源码读取中存在编码异常迹象，后续应统一检查文件编码是否稳定为 UTF-8

9. 适合的后续演进

当前阶段不一定需要上框架，但有三条自然演进路线：

  1. 保持纯静态，补充文档和模板规范。
  2. 引入静态站点生成器，把页头页脚与文章模板抽离。
  3. 如果内容持续增长，再考虑把文章内容迁移到 Markdown 驱动的内容系统。

对这个站点来说，最先值得做的不是“技术升级”，而是把模板复用和内容维护流程整理清楚。