澄屿

开始使用澄屿

Fri, 06 Nov 2026 00:00:00 GMT

安装依赖、启动本地网站，修改站名、作者与部署地址。

下载模板后，在包含 package.json 的目录打开终端。下列命令都在该目录执行。

检查本机环境

项目要求 Node.js 24 或更高版本，锁定的包管理器为 pnpm 11.25.0；当前示例在 Node.js 24 环境验证。先检查版本：

终端命令sh

1node --version2pnpm --version

如果终端提示找不到命令，先安装对应运行环境。保留项目的 pnpm-lock.yaml，这样安装使用同一套依赖版本。

安装与启动sh

1pnpm install --frozen-lockfile2pnpm dev

打开终端显示的地址，默认是 http://127.0.0.1:4321/。这是本机开发服务，不是已经上线的站点。若该端口正被另一份预览占用，可以先停止它，或者执行 pnpm dev --port 4322。

修改站名和作者

打开 site.config.ts，在现有对象中修改下列字段，其他配置保留。下面是局部修改示意，不要用它替换整个文件：

site.config.ts · 局部示意typescript

1title: '我的记录',2subtitle: '技术笔记与日常记录',3author: {4  name: '你的名字',5  bio: '用自己的话介绍这里。',6  tags: ['写作', '阅读'],7  github: '',8  email: '',9},

保存后检查页头、首页、关于页和文章署名。邮箱与 GitHub 留空时相应入口隐藏。首页首屏、生活切片与关于页介绍分别由 hero、life、about 配置；修改图片时同时更新替代文字和来源提示。

设置部署地址

site 是公开网站的完整地址，base 是部署路径。它们影响规范地址、RSS、站点地图和资源链接。下面的域名只是示意，发布前替换成自己的地址：

地址设置 · 局部示意typescript

1site: 'https://your-domain.example',2base: '/',

如果网站将放在某个 /blog/ 子目录，使用 base: '/blog/'，构建与托管位置保持一致。本机仍打开终端地址，无需把 site 改成 127.0.0.1。

开发预览和产物预览

命令	适合做什么
`pnpm dev`	修改正文、配置和组件，查看开发效果
`pnpm check`	检查内容字段、引用和 Astro 类型
`pnpm build`	生成并校验完整网站
`pnpm preview`	查看已经构建好的网站

需要核对完整全文搜索时，先在开发终端按 Ctrl+C，再执行：

检查正式产物sh

1pnpm check2pnpm build3pnpm preview

浏览首页、文章、资料和搜索。预览服务读取已有 dist，此时修改源文件需要重新构建才会出现变化。构建成功只更新本机产物，不会自动上传 GitHub 或部署。

新建文章

模板没有预装 first-note 这个 ID，你可以在停止预览后运行：

新建自己的草稿sh

1pnpm new article first-note

新文章默认为私人草稿。接着阅读新建、预览与发布文章，使用本机草稿模式查看它。

新建、预览与发布文章

Fri, 06 Nov 2026 00:00:00 GMT

从第一份私人草稿开始，在本机预览，再决定公开全文、只公开开头或仅供站主阅读。

新建草稿

在模板根目录运行以下命令。如果已经使用过 first-note，请换一个全库唯一的 ID。

新建文章sh

1pnpm new article first-note

工具生成 knowledge/articles/first-note/index.md，初始状态为 private/draft，不进入公开列表。

文章字段

下面是一份可以使用的完整源文件。日期是示例编写日；创建自己的文章时换成实际日期。

knowledge/articles/first-note/index.mdmarkdown

1---2id: first-note3type: article4title: 我的第一篇记录5date: '2026-11-06'6status: draft7visibility: private8summary: 记录一次具体问题，以及我怎样找到答案。9category: 学习记录10tags: [学习, 实践]11cover: code12---1314## 我遇到了什么1516先用自己的话说明问题，再补上过程、依据和下一步。

正文放在第二条分隔线之后；必需字段不要省略。

title 是页面主标题，summary 帮助列表中的读者选择文章。正文建议从 ## 开始。id 决定永久链接，不跟随标题变化；本例的地址是 /articles/first-note/。

category 填一个分类，tags 可填多个标签。cover 可填预设名，也可填放在 public/art/covers/ 下的公开图片文件名。正文配图和下载附件放在文章文件旁，用相对路径引用。

在本机阅读私人草稿

先停止已启动的开发服务，再在 PowerShell 中执行：

仅本机草稿预览powershell

1$env:CLARISLET_DRAFTS='1'2pnpm dev

打开终端地址，再访问 /articles/first-note/。你应该看到自己的标题和正文，以及页头的本机草稿提示。保存文件后等待重新编译，刷新检查修改。

结束时 Ctrl+C，执行 Remove-Item Env:CLARISLET_DRAFTS。这是本机开发预览，草稿不会写进正式 dist。

可下载本文附带的写作检查表。正文里的图片和链接写法见 Markdown 排版与代码示例。

选择公开范围

status: draft 留给本机预览。正式构建只收录 status: ready 且日期不晚于构建当天（UTC）的文章。准备好后，再用 visibility 决定读者能看到多少。

公开范围	匿名读者看到什么
`public`	全文和正文引用的附件
`preview`	标题、简介等公开信息，以及 `ratio` 允许的正文开头
`private`	公开列表、计数和搜索均无此条目

只有 preview 需要填写 ratio，取值从 0 到小于 1。0 只显示公开信息。0.05 和 0.1 按可见文字预算保留完整的开头段落或其他内容块，实际显示量取决于块长。可以打开阅读练习（10% 预览示例）看页面效果。标题、摘要和标签应当先确认可以公开。公开页面只携带可见正文所引用的附件。

可选站主模式允许站主登录后阅读已发布的私人内容和预览全文。真实私人稿件应放在私人仓库或仓库外的内容目录。公开 Git 仓库里的 Markdown 可以被直接阅读。

检查并发布

若要公开第一篇文章，把 first-note 改为 status: ready 和 visibility: public。核对标题、摘要、图片替代文字和下载链接，再生成正式产物。

检查与正式预览sh

1pnpm check2pnpm build3pnpm preview

在预览地址打开文章列表和 /articles/first-note/，确认发布结果。部署到托管服务前，按构建、部署与更新的检查表走一遍。

澄屿简介

Fri, 06 Nov 2026 00:00:00 GMT

模板的栏目、内容文件和基本用法。

澄屿是一套基于 Astro 的博客模板。文章保存在 Markdown 文件中，专题和资料书通过 ID 引用正文。构建后得到可以部署的静态页面。

本站是模板演示。文章介绍使用方法，随记和项目展示其他内容类型；Lorem Ipsum 是示例署名，插画也可以替换。

栏目

栏目	用途
文章	按发布时间浏览正文
专题	按指定顺序阅读一组文章
资料	通过书籍和多级目录查阅资料
随记	发布短文字、图片或链接
项目	介绍作品的用途、功能和相关地址
归档	按年份和月份查找文章

专题和资料书可以引用同一篇文章。修改正文后，各入口显示同一份内容。文章 ID 决定永久链接，目录位置和标题可以另行调整。

内容文件

knowledge 保存 Markdown 正文、附件，以及专题和书籍的 YAML 文件。
site.config.ts 设置站名、作者、首页文案和部署地址。
src 保存 Astro 页面、布局、组件和样式。
dist/public 是构建生成的公开网站，可以重新生成。

日常写作只需维护源文件。构建会校验字段与引用、处理公开范围，再生成页面、附件和搜索索引。

从哪里开始

阅读开始使用澄屿，安装依赖并启动网站。
跟随新建、预览与发布文章创建第一份草稿，在本机查看。
用 Markdown 排版与代码示例检查正文效果，按需整理专题与资料书。
确认公开范围后，构建并部署。

「澄屿入门」专题提供六篇教程的阅读顺序，「澄屿使用手册」按章节收录相同正文。

支持的写法与发布方式

默认支持标准 Markdown、GFM 表格与任务列表、代码围栏和 NOTE 提示。数学、Mermaid、MDX、任意 HTML 和视频嵌入不属于默认能力。

默认静态模式只生成公开网站，不显示登录。可选站主服务供唯一站主登录后阅读已发布的私人内容和预览全文，需要单独配置服务端环境，不提供注册或在线编辑。

准备发布私人内容或部分预览时，先查阅公开范围说明。

Markdown 排版与代码示例

Sun, 18 Oct 2026 00:00:00 GMT

在同一篇文章里查看常用 Markdown 排版，以及代码高亮、终端输出与 NOTE 提示。

下面按元素展示 Markdown 和 GFM 写法。代码围栏内是源文本，围栏外是页面效果。

标题与段落

文章主标题来自元信息，正文建议从二级标题 ## 开始，按需要使用 ###。小标题会形成正文目录，层级应表达内容关系。

段落写法markdown

1## 第一个问题23这是第一段，段落之间留一个空行。45### 更具体的观察67这是另一段。

一段中文与英文混排

这是一段中文排版样例。段落包含中文标点、English words 和较长的说明，用于观察字体、行距和自动换行。改变窗口宽度时，正文在阅读区域内重新排列；表格和代码的长行在各自区域内滚动。

Astro 负责页面组织，Markdown 保存正文。像 status: draft 这样的短表达适合使用行内代码；普通说明继续使用自然语言，避免整段都变成技术标识。

强调、引用与换行

行内与引用markdown

1**关键结论**、*轻度强调*、~~不再采用的说法~~和 `行内代码`。23> 先留下问题，再补充能回答它的材料。

关键结论、轻度强调、~~不再采用的说法~~和 行内代码。

先留下问题，再补充能回答它的材料。

引用也可以包含第二段，用来补足上下文。

普通段落靠空行分开。如果需要同段内的硬换行，可以在行末放两个空格。不要用连续空行代替页面间距。

列表与任务

列表写法markdown

11. 先确定要回答的问题。22. 再组织材料。3   - 保留来源。4   - 写下自己的解释。56- [x] 留下标题7- [ ] 补充可验证的例子

先确定要回答的问题。
再组织材料。
- 保留来源。
- 写下自己的解释。
完成之后读一遍，检查步骤是否连贯。

留下标题
记录来源
在自己的文章中应用一次

任务列表用于展示记录中的完成状态。网站没有在线编辑后台，勾选状态应在 Markdown 源文件中维护。

表格与长内容

表格写法markdown

1| 内容 | 用途 |2| --- | --- |3| `summary` | 帮助读者选择文章 |4| 正文 | 展开过程与依据 |

内容	用途	阅读时关注什么
标题	说清楚本篇的问题	能否辨认主题
`summary`	在列表里提供判断依据	与正文是否一致
正文	展开过程与依据	段落能否连起来
`a-long-example-identifier-for-a-narrow-screen`	展示较长标识	宽表格在自身区域横向滚动

表格、任务列表和删除线属于当前明确支持的 GFM 扩展。基础规则可查CommonMark 参考。

图片、链接与附件

图片使用相对于本文的文件路径，方括号写替代文字。本图是模板内绘制的流程示意，帮助说明内容怎样变成网页。

图片写法markdown

1![源文件经过构建后生成可阅读网页的流程](./reading-flow.svg)

图示：正文先保存为源文件，构建后才成为页面。说明文字使用普通段落维护，不需要插入 HTML。

站内链接可以写成 [写作指南](content:source)，效果见写作指南。下载附件也用相对路径，写法和移动文件时的注意事项见正文链接与附件。

代码、终端与提示

源码与高亮

代码围栏第一行依次写语言和可选的显示设置。title="reading-note.ts" 显示文件名，{3-4} 突出第 3 至 4 行，caption 显示代码下方的说明。复制按钮只复制源码。

围栏写法markdown

1```typescript title="reading-note.ts" {3-4} caption="记录问题和自己的解释。"2const title = '阅读记录';3const note = {4  question: '这段说明回答了哪个问题？',5  explanation: '先复述，再补回限制条件。',6};78console.log(title, note);9```

reading-note.tstypescript

1const title = '阅读记录';2const note = {3  question: '这段说明回答了哪个问题？',4  explanation: '先复述，再补回限制条件。',5};67console.log(title, note);

记录问题和自己的解释。

未指定语言或找不到对应高亮器时，代码仍会显示。窄屏上的长行可以在代码块内横向滚动。

终端输出

用 terminal 围栏展示命令和输出。它有独立样式，省去源码行号和复制按钮。

本地运行 · 示例输出terminal

$ node reading-note.js

阅读记录
已保存：问题、解释与下一步。

NOTE 提示

普通引用继续使用 >。需要单独提示时，在引用首行写 [!NOTE]，后面可加标题。

提示写法markdown

1> [!NOTE] 复制之前2> 先核对文件和上下文，再运行示例。

复制之前

先核对文件和上下文，再运行示例。

专题与资料书

Fri, 12 Jun 2026 00:00:00 GMT

用稳定链接、专题顺序和资料书目录组织同一批文章。

本篇以 first-note 为例，请先按新建、预览与发布文章创建它。接下来将它加入一个专题和一本资料书。

文章 ID

id 在整个内容根中唯一。参考资料、随记和项目也有自己的 ID，即使分别放在不同目录，也不能重复。标题可以改善，文件夹可以整理，但已经发布的 ID 应继续保留。

文章和参考条目都放在 knowledge/articles，通过 type: article 或 type: reference 区分。参考条目适合记录来源、收藏理由、适用场景和自己的解释，不必复制一篇外部文章。

正文链接与附件

链接到其他条目时使用稳定 ID，例如 [阅读第一篇记录](content:first-note)。目标须先存在。构建时会自动加上部署的 base，并按目标类型生成文章、随记或项目的地址。

相对源链接适合在编辑器里跟读，例如 [另一份源文件](../other-note/index.md)。图片和下载附件也使用相对路径，例如 ![示意图](./diagram.png)。移动源文件时保留 ID，同时检查移出和指向该文件的相对链接。只发布正文实际引用的附件。

专题顺序

创建 knowledge/topics/first-steps.yaml：

knowledge/topics/first-steps.yamlyaml

1id: first-steps2title: 入门笔记3intro: 按顺序阅读入门笔记。4entries: [first-note]

entries 的排列就是建议阅读顺序，与文章发布日期分开。加入第二篇时，先创建其正文，再将真实 ID 加进数组。不存在的引用会阻断构建，避免发布空入口。

同一篇可以属于多个专题。例如 Markdown 排版教程同时收录在「澄屿入门」和「排版与技术写作」中。从各自的专题进入时，篇次和前后篇按该专题的顺序显示。

资料书目录

创建一本自己的书。若你在演示副本中练习，请用新的书籍 ID，保留演示的 handbook。

knowledge/books/my-handbook.yamlyaml

1id: my-handbook2title: 我的手边书3subtitle: 遇到问题时回来查4intro: 保存记录、来源和可再次使用的说明。5order: 106theme: index7chapters:8  - title: 开始记录9    children:10      - title: 第一个问题11        children:12          - id: first-note

分支使用 title 和 children，叶项使用 id。目录可以继续嵌套，不把文章正文写进 YAML。运行检查与构建后，资料架出现新书，叶项打开同一篇 first-note。

演示站的使用手册收录六篇教程，网站开发参考收录两份资料，「阅读与笔记」展示空书状态。

选择合适的内容类型

类型	建议保存什么	新建命令示例
article	一个展开的问题与过程	`pnpm new article first-note`
reference	来源、用途和解释	`pnpm new reference reading-reference`
jotting	短观察、片段和提问	`pnpm new jotting first-jot`
project	成品的用途、功能和使用入口	`pnpm new project first-project`

表中命令分别创建不同内容，不要对已有 ID 重复执行。它们都从私人草稿开始。随记可以设置 time，同日记录按时间倒序；项目的真实地址留空时不出现按钮，示意图预设不等于项目截图。

引用校验

删除正文前，搜索它的 ID，检查专题、书籍、正文链接、关联阅读和首页配置。移动源文件后再跑一次检查，因为相对链接和附件仍跟随文件位置。

构建先过滤目标内容，再计算目录、计数和索引。因权限过滤而没有可见条目的书籍不会输出；主动设置 chapters: [] 的空书会保留。列表页数根据当前可见内容生成。

整理完成后运行 pnpm check 和 pnpm build，再检查原有正文地址和集合入口。

构建、部署与更新

Mon, 27 Apr 2026 00:00:00 GMT

构建静态网站、设置部署路径，并随内容更新搜索索引。

默认静态模式将网站生成到 dist/public。确认内容状态和发布日期后，构建并检查该目录，再上传到静态托管服务。

本地检查与构建

在模板根目录执行：

发布前的本地流程sh

1pnpm check2pnpm test3pnpm build4pnpm preview

check 会检查字段、引用与类型。test 验证内容和服务规则。build 使用 Astro 输出完整页面，收集附件、建立 Pagefind 索引，并检查实际产物链接。只有全部成功才替换 dist，失败不会覆盖上一成功版本。

preview 默认监听本机 4321，读取已有产物。若仍有 dev 占用端口，先在对应终端停止它。

发布目录

默认 static 模式只发布 dist/public 中的内容。其中包含页面、浏览器资源、正文附件、分页辅助数据、全文索引、RSS 和站点地图，应作为同一版本一起上传。

不要只拷贝首页，也不要把 dist 父目录、知识源、开发缓存或运行凭据作为公开目录。静态托管需要支持目录地址读取 index.html，例如 /articles/source/ 对应该目录的页面。

上传 GitHub 的是已提交源码；对外网站使用的是构建产物。当前模板自带的工作流负责检查，没有自动部署步骤。选择托管方式后，再按对应平台配置发布位置和 HTTPS。

根路径与子路径

在 site.config.ts 中设置自己的 site。部署根路径使用 base: '/'；部署在 /blog/ 时使用 base: '/blog/'，并让文件实际位于该路径。

子路径配置 · 局部示意typescript

1site: 'https://your-domain.example',2base: '/blog/',

保留其他配置，重新构建再查看页面与资源地址。路径问题常表现为首页可开、图片或搜索不可用，不要用逐页硬编码绝对地址来补救。

搜索与分页一起更新

Pagefind 在构建时读取允许的正文。增加文章后，重新构建才能获得新全文索引。文章列表的字段搜索与全站全文搜索范围不同：前者查询标题、摘要、标签和专题名，后者查询已索引的正文。

默认列表按页生成；分类和关键词筛选才按需读取当前栏目的检索数据、当前页卡片。部署时包含 listing、pagefind 和相关脚本，不混用不同构建版本。

替换示例内容

先写自己的正文，再调整首页 home.featured 和 home.recent，然后修改专题和书籍 YAML。删除示例前搜索其 ID，清理正文链接、关联阅读和集合引用，最后再删除无需保留的附件。

可以移除整套示例，但应保留自己的有效内容关系。不要为了使构建通过，随意把缺少发布状态的文件改成公开；先明确它应该是草稿、私人、预览还是公开。

可选站主服务

需要完整私人阅读时，将 clarislet.config.ts 的 mode 改为 owner，或者设置 CLARISLET_MODE=owner 后构建。此时会生成 public 和 owner 两个目标。

凭据通过 pnpm owner:password 工具设置，用户名、密码与会话密钥使用服务端环境变量，具体要求见工程的 docs/deployment.md。这里不提供可直接复用的默认密码。启动本项目 Node 服务进行统一认证，不能使用普通静态托管公开整个 dist。

恢复 static 时清理相应环境设置，再构建并重启预览服务，使它读取新的 manifest。SQLite 只保存会话，正文继续由 Markdown 维护。

发布检查清单

核对日期、发布状态和公开范围，确认标题与摘要可以公开。
打开首页、文章末页、代表性正文和资料目录，检查图片、附件和永久链接。
搜索新增文章，确认匿名访问找不到私人或草稿正文。
从正文返回列表，确认页码、筛选和滚动位置恢复。
在手机宽度和明暗主题下检查表格、代码和导航。
发布同一次构建的 dist/public 内容，包括页面、附件和索引。

如果启用了站主服务，再分别用匿名、登录和退出后的会话检查全文、附件与索引的访问结果。

阅读练习（10% 预览示例）

Thu, 16 Oct 2025 00:00:00 GMT

虚构阅读练习，用于展示 10% 预览的公开开头。

练习说明

这是一份虚构阅读练习，材料是一段工具说明。

先找出说明中的动作和条件，再用一个例子检查理解。