极简中文主题使用指南与功能演示

从这里开始

NekoBlank 是一个用 Hugo 构建的中文静态博客。现在的主题叫作「港口手记」：旧纸、炭墨、锈橙批注与灰蓝色的页边线条，借用《极乐迪斯科》绘画中沉静、略带旧痕的气氛。图像和装饰围绕内容展开，正文保留适合长文阅读的宽度。

白天是温暖的浅色纸面，夜间则换成深灰绿色。右上角的太阳／月亮按钮可以手动切换主题，旁边的小箭头可以选择「按时间」或「跟随系统」。默认按当地时间切换：07:00–19:00 为白天，其余为夜间；手动选择会保留，重新选择「按时间」才恢复自动切换。字体优先使用设备上的中文衬线字体，不需要额外下载网络字体。

这篇文章既是使用指南，也是演示页。可以点目录跳到某一节、展开下面的代码、查看图片，或打开右下角的电台边听边读。

写下第一篇文章

文件与基本信息

博客文章放在 content/posts/ 中；ReJava 课程位于 content/rejava/，有独立入口，不混入「所有文章」列表。

新建一个 Markdown 文件，在开头写入 front matter：

---
title: "一则港口手记"
date: 2026-10-03T09:00:00+08:00
summary: "用一两句话说明这篇文章在讲什么。"
tags: ["随笔"]
categories: ["生活"]
draft: true
---

预览方法： 保存为 content/posts/harbor-note.md 后运行 npm run dev，在 /posts/harbor-note/ 查看。draft: true 只在显示草稿的本地开发模式出现；准备发布时改为 false 或删除这一行。这里的标签只是示例，复制到新文章后才会出现在标签页。

summary 用于文章列表的摘要，tags 会自动汇总到所有标签。标签不需要另建文件，也不需要手动维护数量。要关闭单篇文章的目录，可在 front matter 中添加 toc: false。

本地预览与构建

首次准备项目时安装依赖，随后启动预览：

npm ci --include=dev
npm run dev

运行演示： 打开 http://localhost:1313/，修改一段文字并保存，页面会更新。开发命令同时监听 CSS 与内容；用 Ctrl+C 结束预览。需要已安装 Node.js 和 Hugo，项目当前验证的版本见仓库 README。

准备检查完整输出时运行：

npm run build
npm test

检查方法： 构建成功后可在 public/ 中看到生成页面，测试命令验证导航、电台和阅读交互中的关键逻辑。这两个命令只做本地构建与检查，不会发布网站。不要直接修改 public/，下次构建会重新生成它。

阅读与寻找文章

所有文章按时间倒序收录博客手记；时间线按年份整理同一批文章。两者使用同一份内容，只是浏览方式不同。ReJava单独收纳课程与复习资料。

标签页直接显示全部主题和对应篇数。标签较少时，一眼就能看全，点击名称即可进入相关文章列表。

章节目录

桌面阅读时，侧栏显示主章节编号、当前章节和阅读进度。当前章节下的小节会展开；「展开小节」可以显示完整目录。

手机上，目录收在顶部的吸顶按钮里。打开后点选章节，目录会收起并跳到相应位置；按 Esc 可以收起面板。浏览器的前进、后退也可用于返回之前的章节。

阅读进度按正文位置估算，展开长代码后会重新计算。文章开头的字数与阅读时间同样是参考值，不代表精确的阅读耗时。

长代码

超过 12 行的代码会收起，可以按需展开。下面是一段完整的 JavaScript 示例，函数检查输入，末尾包含可直接运行的断言：

function countTopics(topics) {
  if (!Array.isArray(topics)) {
    throw new TypeError('主题必须是数组。');
  }

  const counts = new Map();
  for (const topic of topics) {
    if (typeof topic !== 'string' || !topic.trim()) {
      throw new TypeError('主题名称必须是非空字符串。');
    }
    const name = topic.trim();
    counts.set(name, (counts.get(name) ?? 0) + 1);
  }
  return counts;
}

const result = countTopics(['Java', 'Hugo', 'Java']);
console.assert(result.get('Java') === 2, 'Java 应出现两次');
console.assert(result.get('Hugo') === 1, 'Hugo 应出现一次');
console.assert(countTopics([]).size === 0, '空数组应返回空结果');

运行演示： 将示例保存为 topics.mjs，执行 node topics.mjs，正常时没有断言输出。把输入改为 [''] 应抛出明确的错误。代码只作为文章内容显示，网站不会自动运行它。

Markdown 与内容组件

文字、列表与引用

可以用 粗体 标出重点、用 斜体 表示引用语气，也可以用删除线保留修改痕迹。行内代码如 Map、npm run build 会与正文区分。

1. 先写清楚一个具体问题。
2. 再放上能够解释它的例子。
3. 最后记录结论与尚未解决的部分。

留下一段以后还能读懂的笔记，比堆满一页术语更有用。

提示块

alert 短代码支持 info、success、warning、error 四种类型。下面就是实际渲染效果：

并列内容与表格

columns 短代码用 <---> 分隔各栏，窄屏会自动改为上下排列：

如果信息需要逐项比较，表格更直接：

数学公式

启用数学支持后，KaTeX 会渲染行内公式，例如 $e^{i\pi} + 1 = 0$，也支持独立公式块：

$$ \sum_{k=1}^{n} k = \frac{n(n+1)}{2} $$

KaTeX 从 CDN 加载；如果网络不可用，原始公式仍然保留在正文中。

图片预览

图片宽度会适应正文区域。点击下面的图可打开预览，按 Esc 关闭；预览组件无法加载时仍然能看到正文图片。已有链接包裹的图片保留原链接行为。

演示图与首页使用同一幅公版画作，来源记录在 static/art/CREDITS.md。页首的背景插画属于装饰，不会进入文章图片预览。

港口电台

首次进入网站时，电台不会自动出声。点击右下角的播放按钮，即可收听本地氛围曲《港口夜航》；打开旁边的设置可以调整音量或切换频道。

「极乐迪斯科」频道嵌入 Sea Power 的官方 Bandcamp 专辑，共 30 首曲目。切换到这个频道后，在官方播放器里选曲并播放。收起设置面板仍可继续听，方形按钮会停止并关闭原声播放器；两个频道不会同时播放。

通过站内链接切换文章、标签、课程与关于页时，电台会留在原处，音乐可以连续播放。浏览器前进、后退与深浅模式切换也保留当前电台。手动刷新、关闭页面或发生完整页面重载时，仍需要再次点击播放；本地频道会记住音量与进度。

官方原声需要网络连接，并遵循平台的访问与试听规则。若嵌入播放器无法播放，面板中有前往官方专辑的链接。

维护近期事项与外观

手动修改事项状态

关于页的近期事项由 data/roadmap.toml 管理。每项只需标题与状态：

[[items]]
title = "完成一篇 Java 学习笔记。"
status = "todo"

[[items]]
title = "整理网站的阅读目录。"
status = "done"

预览方法： 把第一项改为 done 后保存，关于页应显示「已完成」和删除线；改回 todo 则恢复「待完成」。复制一个完整条目可新增事项，移动条目可以调整顺序。状态只接受这两个值，拼写错误时构建会指出问题。

装饰与主题

全站配色、纸面和页边装饰由主题 CSS 管理，白天与夜间使用对应的颜色变量。文章正文和课程共用阅读样式，修改装饰时无需逐篇编辑内容。

内页绘画在 data/artworks.toml 中配置，关闭 enabled 可隐藏这些插画，首页的公版莫奈画作仍会保留。各幅作品的作者与来源见 static/art/disco/CREDITS.md。

修改完成后，先本地预览，再构建检查并提交 Git。这样无论是一次小的颜色调整，还是一轮新的界面设计，都能找到上一个可用版本。