手册

这个文件说明站点怎么组织、日间和夜间主题在哪,以及内容从工作室还是示例文件来。

站点结构

  • / 首页:区块顺序和内容可以在工作室里改。没有数据库时,仍是开场、精选作品、历程、最新文章、每日热点
  • /works 作品列表。有案例的条目进入 /works/[slug],页内分问题、过程、结果
  • /blog 文章列表,/blog/[slug] 单篇,/feed.xml 是 RSS
  • /about 关于
  • /ledger 写作账本,从博客列表底部进入
  • /colophon 版权页
  • /almanac 历书,只计公开贡献
  • /garden 花园。一间房间里的示例笔记:书桌上的随笔、架上的柜格、手边的日志、深处的回廊。笔记互相链接,页末有反向链接
  • /lab 实验室。示例项目的开源、演示、更新日志和文档
  • /tools 工具,分文档处理、换算和文字。PDF、单位、纸张、字数、标点和摘句在浏览器里完成,不上传。汇率在 /tools/convert,由浏览器向 Frankfurter 读取 ECB 参考汇率,不经过本站接口。/tools/fx 转到换算页的汇率
  • /learn 课程。教室地图上的站外链接目录,分文献、讲义、课室、备查。四类都空着,链接稍后补上。不报名,也不收款
  • /docs/usage 使用说明,/docs/handbook 本手册
  • /changelog 修改日志
  • /my 私人工作室,/my-gate 密码页。不要把它们加进公开导航、页脚或 sitemap

公开导航只有博客、作品、关于。使用说明、手册、修改日志、版权页和 RSS 在页脚。GitHub 旁边有历书,以及花园、实验室、工具和课程。这四条不进顶栏,也不放到首页。

设计令牌和日间 / 夜间

主题写在 app/globals.css,用 <html data-theme="day"> 或 data-theme="night" 切换。选择存在 localStorage 的 site-theme。

默认是日间:底色是暖的纸色。夜间用同一套间距和字体,只换深色。

以前保存过的 cool 会当成夜间,cute 会当成日间,避免还指着已经删掉的主题。没有保存过选择的人看到日间。

常用变量:

  • --bg --text --muted:页面底色、正文、次要文字
  • --card --card2:卡片和浅底
  • --accent --accent2:强调色。渐变字用 .grad-text,不要和填充用的 .grad 叠在同一个字上
  • --radius --shadow:圆角和阴影
  • --on-accent:强调色上面的字色
  • --header-bg:顶栏
  • --input-border:密码框和输入框边框

公开页面靠字号和细线分开,几乎不用阴影。密码框和工作室里的输入框仍有清晰的边框。

字体在 app/layout.tsx 用 next/font 加载:

  • Source Serif 4:标题里的拉丁字符。中文标题落到 Noto Serif SC
  • Noto Sans SC:正文和导航
  • Geist Mono:小标题和代码

动效要尊重 prefers-reduced-motion。系统要求减少动画时,页面不再平滑滚动。

内容从哪来

数据库可用时,公开页面读 Neon:

  • 已发布的文章
  • 设为显示的作品
  • 设为显示的首页区块
  • 关于页正文

数据库没有配置,或者这次没连上时,改用下面这些示例,页面仍然打开:

  • lib/data.ts:作品 works、文章 posts、历程 journeySteps
  • lib/model.ts 里的关于页示例和首页五段
  • lib/dramas.ts:只给 /my 的追剧分页。公开页面不要 import 它
  • data/hot.json:每日热点,由脚本写入
  • data/almanac.json:历书快照,由脚本写入。只含公开贡献的日期、次数和档位
  • docs/usage.md、docs/handbook.md、CHANGELOG.md:说明文档。网页直接渲染这些文件

作品没有上传封面时用色块(grad-a 到 grad-f),不是照片。没有真实照片时,不要放假装是本人的图片。工作室里可以另传一张图,也可以继续用色块。

文章的阅读时间按正文估算。单篇从二级和三级标题生成目录。列表按时间排,页面底部给出较新和较旧的一篇。

在工作室里改

先设置 MY_PASSWORD,打开 /my-gate,再进 /my。数据库用 DATABASE_URL。表会在第一次连接时建好,说明见使用说明。

  • 文章:写 Markdown,能预览。草稿不公开。发布后出现在 /blog。地址只用小写英文、数字和短横线。封面可以上传,也可以贴 https 图片地址。
  • 首页:上移、下移、隐藏、删除,或按类型新加一节。
  • 作品:改标题、一句话、标签、色块、链接和是否公开。
  • 关于:整页 Markdown。

保存之后,公开页面的缓存会立刻作废,下一次打开看到新内容。上传失败或数据库没配好时,接口返回 503,工作室里直接写出原因,而不是一张报错页。

改示例文件

数据库还没接上时,公开内容仍来自 lib/data.ts。可以在 works 或 posts 里加一项,字段和现在的示例一样。category 用「技术文章」或「生活记录」时,会进博客页原有的两个小节;其它分类会另起一节。slug 会变成 /blog/[slug]。

数据库一旦启用,公开页面就不再把 lib/data.ts 和数据库拼在一起。示例会在第一次建表时抄进数据库。之后要改公开内容,用工作室,或者直接改数据库。删掉数据库里的文章后,示例不会再自动出现,除非数据库本身不可用。

加一条修改日志

打开 CHANGELOG.md,在最上面已有记录之前加一节:

## 2026-11-11

### 修复
- 说明这次改了什么,用能看懂的句子。

日期用 YYYY-MM-DD。新的放在旧的上面。网页 /changelog 渲染的就是这个文件,不用再改页面组件。

约定

  • 不要把密码、数据库连接串或 Blob 令牌写进仓库。.gitignore 忽略 .env*,但保留 .env.example(里面只有空的变量名)。
  • 不要编造 Instagram、X 或其他还没有的链接。没有地址就先不放入口。
  • GitHub 地址用 https://github.com/qihaiqianqiu777。
  • 公开页面不要写「未部署」或实现细节。占位内容可以留着,等有真实材料再换。
  • /my 保持 noindex。robots.ts 继续禁止 /my、/my-gate、/api/。

还没换成真实内容的部分

这些要等站点主人自己的材料:

  • 头像:首页现在是名字的第一个字,默认仍是 W,不是照片
  • 示例作品和文章:在 lib/data.ts,数据库第一次连接时会抄一份进去
  • 关于页的简介(没有写雇主、学历、年限)
  • lib/dramas.ts 里的追剧记录
  • Instagram 和 X:有真实主页后再加回页脚