personal-shrine · 项目笔记

铸造圣所（fire-disposal/personal-shrine）：Astro 静态站点 + Obsidian 笔记库，构建时渲染；全站静态、无运行时 CDN。工作流 = Obsidian 写笔记 → 构建渲染 → pnpm ship 静态部署。

定位

• 个人档案网站：工具（/tools/，单文件离线 HTML）+ 笔记档案（/notes/，Obsidian 库）+ 项目（/projects/）。
• 边界：Markdown 是数据，HTML 是渲染结果；网页只是 Obsidian 库的外层呈现。

架构与数据流

src/content/notes/ (Obsidian 库, .md)
  → remark-vault: wikilink / 嵌入(![[…]]) / 行内#tag / callout
  → Astro 构建 → dist/ 纯静态 → rsync 主机

技术栈

• Astro（静态生成）+ TypeScript。
• Obsidian 笔记库（src/content/notes/ 直接作 vault）。
• KaTeX（构建期数学）+ github-slugger（路由 slug）；零运行时 JS 依赖。

核心设计要点

• 静态优先：核心不是"快"，而是边界清晰——无运行时状态=无故障面、dist/ 可审计（产物即线上）、内容与展示分离。
  • 动态只有两个正当理由（用户生成内容 / 实时数据）；个人笔记都不沾，静态是诚实的答案。
  • 代价：改笔记要重新构建、无内置搜索（靠分类+标签+浏览器查找）、交互只能渐进增强；换来"十年后还能打开"。
• 内容管线：src/content/ Markdown 唯一事实来源；frontmatter zod 校验（写错构建即失败）；索引 /notes/（置顶+日期）+ 详情 /notes/<slug>/（正文+headings 目录）；样式按页拆分（notes.css 仅笔记页）。
• Obsidian 库约定：双链按文件名解析（与文件夹无关），子文件夹即路由 [...slug]；draft:true 隐藏、pinned:true 置顶、行内 #tag 跳索引；附件统一 assets/，![[...]] 嵌入在构建时镜像 dist/notes/。
• 离线可移植：无运行时 CDN / 远程字体（自托管 public/fonts/）；工具页单文件 file:// 即用；整站可 rsync；若 Astro 死，dist/ 依然活（框架是构建期依赖，非运行期）。

近期重点与路线图

• 内容层随 vault 演进（分类对齐、开发/ 一项目一文件收敛）；持续保持静态 / 离线 / 可移植。
• 定位不变：框架仅作构建期依赖，不做运行时后端。

边界与不做

• 不引入运行时后端 / 数据库 / 用户系统（纯静态）。
• 不做客户端搜索（除非引入客户端索引）。

部署与门禁

• pnpm ship：build → auto-commit → push；CI 构建、校验、rsync（dist 摘要不变则跳过）。
• Husky pre-push（pnpm check && pnpm build）；pnpm build 链：scan-tools → astro build → copy-note-assets → bundle-tools → validate-tools。

情报来源

• src/content/notes/开发/ 现有笔记与 AGENTS.md。

更新动向

• 2026-08-28：开发文件夹收敛为一项目一文件（STFCS / Nursing VP Sim / personal-shrine / Twinsia）。

这份笔记本身就是使用说明。档案室（src/content/notes/）是一个几乎完整的 Obsidian 库：用 Obsidian 打开这个文件夹即可写作，网页在构建时负责渲染，两边共用同一份 Markdown。

用 Obsidian 打开

1. Obsidian → Open folder as vault → 选择 src/content/notes/。
2. 库配置（附件目录、链接格式）已内置在 .obsidian/ 里，无需手动设置。
3. 直接写：wikilink、嵌入、标注、行内标签、子文件夹 —— 全部原生支持。

写完后 git push，GitHub Actions 自动构建部署；本地可用 pnpm dev 实时预览。

元信息字段

字段	必填	说明
title	否	笔记标题，同时作为页面标题；缺失时自动以文件名补写
description	否	一句话摘要，显示在索引卡片上；缺失时自动随机补一句赞美欧姆弥赛亚（中/拉/英）
date	否	创建日期 YYYY-MM-DD；缺失时构建自动按本地日期补写
updated	否	最后更新日期
category	否	分类：log 日志 / essay 随笔 / study 研习 / system 系统 / shrine 圣所 / dev 开发
tags	否	标签数组或空格分隔的字符串，两者皆可
pinned	否	true 时置顶到索引最前
draft	否	true 时仅存在于源码，不渲染到网页

Obsidian 语法支持

Wikilink

[[personal-shrine|静态优先架构]] → 静态优先架构

带别名：[[疾病总索引|疾病索引]]。链接按 文件路径 → 文件名 → 标题 → 别名 的顺序解析；解析不到的链接会以灰色虚线下划线显示（类似 Obsidian 的未创建链接）。

嵌入

![[shrine-grid.svg]]

标注（Callout）

> [!warning] 注意
> 这是警告标注。

行内标签

#笔记 会被渲染成指向档案索引的标签链接，比如这句话里的 #笔记。索引页收到 ?tag= 参数时会自动过滤。

标题索引

页面右侧（移动端为正文上方）的 Index · 目录 小组件根据正文里的 ## / ### 标题自动生成，点击即跳转，滚动时高亮当前章节。中文标题同样可用。

编辑约定

• 正文用 ## 作为一级章节标题，### 作为小节；# 留给页面大标题。
• 附件统一放进 assets/ 文件夹，用 ![[文件名]] 引用。
• 子文件夹直接建 —— 路由自动跟随（如 开发/ 下的笔记在 /notes/开发/…）。
• 想临时隐藏一篇笔记：改 draft: true。想让它常驻顶部：改 pinned: true。

src/content/notes/          ← Obsidian 库根目录
├── .obsidian/              ← 库配置（本地状态，不提交）
├── assets/                 ← 附件目录
├── 学习/                   ← 专业课笔记 / 通用类 / INBOX
├── 教科书/                 ← 内科护理学 / 外科护理学 / 新编护理学基础
├── 开发/                   ← 一项目一文件（本文件所在）
└── 娱乐/                   ← 人物卡 / 祷文集 / 暗潮

保持前端零运行时依赖：索引、目录、链接解析全部在构建时完成，网页本身不含笔记数据。