<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Cucurbitulae blog</title><description>Cucurbitulae blog</description><link>https://cucurbitulae.com/</link><language>en</language><item><title>主题特色与阅读体验</title><link>https://cucurbitulae.com/blog/features/</link><guid isPermaLink="true">https://cucurbitulae.com/blog/features/</guid><description>从首页找文章，在长文里定位章节，再用搜索找回读过的段落。</description><pubDate>Mon, 17 Aug 2026 00:00:00 GMT</pubDate><content:encoded>首页适合读近作，归档适合翻旧文。这两处都把篇名放在前面：最近文章按发布日期倒序排列，每篇带一小段摘要；归档则按年分组，手机上把日期收在左侧，给长标题留出两行。[文章列表](/blog) · [归档](/archives)

## 两套配色，三种明暗设置

`ink` 在浅色下是米白纸面、赭色点缀，`fresh` 则是淡蓝白纸面、灰蓝点缀。两者都有各自的深色版本。页头的羽毛或叶子图标管配色，旁边的按钮管亮色、暗色和跟随系统。第一次访问时默认是 `fresh` 并跟随系统，之后优先使用浏览器里保存的选择。

## 在长文里找一节

文章里的二至四级标题会进入目录。宽屏时，目录贴在正文右侧，滚动时会标出当前读到的章节。在手机上，目录收在篇名和日期下方；即使文章有封面，也能先确认篇名，再决定要不要展开目录。页面顶部的细线显示阅读进度。

遇到想细看的正文图片，可以点击放大，也可以用 Tab 移到图片按钮后按 Enter 打开，再按 Esc 收起。图片本身带链接时，点击会前往链接目标。

## 技术笔记读起来怎样

代码在构建时完成着色，超过 15 行会折叠，可以展开或复制。公式由 KaTeX 排版，含 Mermaid 代码块的文章会在浏览器里加载图库。图表语法有误时，原始代码会留在正文里，方便对照检查。[查看可操作的示例](/blog/markdown-guide)

## 找回读过的内容

记得主题就按[标签](/tags)找；只记得正文里的一句话，可以把其中几个连续的字输入[搜索框](/search)。搜索在浏览器里查询构建时生成的索引，依次优先匹配标题、标签、摘要和正文，同等匹配程度下新文章排在前面。

文章本身由 Astro 7 生成静态页面。评论和访问计数都是可选项，模板默认关闭；想让读者留言，可以单独启用评论。配置方法见[深度定制指南](/blog/customize)。</content:encoded><category>主题</category><category>文档</category></item><item><title>从零开始：安装与使用</title><link>https://cucurbitulae.com/blog/getting-started/</link><guid isPermaLink="true">https://cucurbitulae.com/blog/getting-started/</guid><description>在本地启动主题，写一篇有固定地址的 Markdown 文章，再把构建好的博客发布到自己的域名或 GitHub Pages。</description><pubDate>Mon, 17 Aug 2026 00:00:00 GMT</pubDate><content:encoded>从空目录到第一篇文章，只需要一个本地开发服务。下面用 `hello.md` 作例子，它最终的地址是 `/blog/hello`。

## 安装与预览

准备 Node.js 22.12.0 或更高版本、pnpm 10 和 Git。仓库的 `package.json` 指定了 pnpm 10.20.0。第一次尝试可以直接克隆主题；如果已经创建了自己的博客仓库，就把下面的地址换成自己的。

```bash
git clone https://github.com/willimt/astro-theme-ink.git my-blog
cd my-blog
pnpm install
pnpm dev
```

打开终端显示的本地地址，默认是 `http://localhost:4321`。保持这个终端运行，保存 Markdown 文件后就能在浏览器里看到变化。

## 写下第一篇文章

新建 `src/content/blog/hello.md`，把开头三项换成自己的标题、摘要和实际发布日期：

```markdown
---
title: &apos;窗边的第一篇笔记&apos;
description: &apos;周末重新整理书桌，也给写作留了一个位置。&apos;
publishDate: 2026-11-20
tags: [随笔]
---

把书桌挪到窗边之后，我发现下午四点正适合坐下来写几行字。
```

在本地打开 `/blog/hello`，再到[文章列表](/blog)看摘要。正文里链接其他文章时，写成 `[定制指南](/blog/customize)`。主题会在构建时补上部署子路径，读者从带或不带末尾斜杠的地址进入都能正确跳转。

| 字段                                  | 用途                                                                                    |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| `title`、`description`、`publishDate` | 必填。标题最多 80 个字符，摘要最多 200 个字符。日期可以写成 `YYYY-MM-DD`。              |
| `updatedDate`                         | 修订日期。文章页同时显示首次发表和最近更新时间。                                        |
| `tags`                                | 可选标签数组。首尾空格会被去掉，英文转为小写后去重。                                    |
| `heroImage`                           | 可选封面。`src` 是相对于文章源文件的本地图片路径，`alt` 用来描述画面。                  |
| `draft`                               | 设为 `true` 会从文章列表、搜索和 RSS 中排除。构建仍生成文章页面，知道网址的人可以阅读。 |
| `comment`                             | 设为 `false` 可关闭本篇评论。显示评论还需要配置全站 Waline 服务。                       |

要在文章旁保存插图，也可以用 `src/content/blog/hello/index.md` 组织同一篇文章，地址仍是 `/blog/hello`。两种目录结构选一种即可。

## 换成自己的博客

先在 `src/site-config.ts` 修改 `site.title`、`site.author` 和 `home.hero.about`。默认头像是 `public/avatar.webp`；替换成另一个文件时，记得一起改 `site.avatar`。首页简介、导航和评论可以等第一篇文章写完再配。[深度定制指南](/blog/customize)

## 构建与部署

```bash
pnpm build
pnpm preview
```

`pnpm build` 先运行 Astro 检查，再把静态站点写入 `dist/`。`pnpm preview` 提供这份产物的本地预览。发布前可以从首页进入文章，点一次文中的站内链接，再打开 `/rss.xml` 确认订阅链接使用自己的域名。

- **部署到域名根目录**：在托管平台的构建环境中设置 `SITE_URL`（例如 `https://example.org`），`BASE_PATH` 留空。构建命令为 `pnpm build`，发布目录为 `dist`。
- **部署到 GitHub Pages 项目子目录**：仓库自带 `.github/workflows/deploy.yml`。在仓库的 **Settings → Pages → Build and deployment → Source** 选择 **GitHub Actions**。推送到 `main` 后，工作流会设置站点域名和 `/仓库名/` 前缀，构建并发布 `dist/`。[GitHub Pages 发布设置](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)
- **使用根域名的 GitHub Pages**：如果线上地址是 `https://用户名.github.io/` 或独立域名根目录，请相应调整工作流中的 `SITE_URL` 并清空 `BASE_PATH`。

## 以后怎样更新主题

如果主题与个人博客是两个相邻的 Git 仓库，在主题目录运行下面的命令。这里假设个人博客的目录名是 `Blog`。

```bash
pnpm theme:sync --target ../Blog
```

先读预览。出现 `REVIEW` 或 `CONFLICT` 时，按仓库中的 `docs/theme-sync.md` 核对差异。预览符合预期后，用 `pnpm theme:sync --target ../Blog --apply` 写入，再到博客目录运行 `pnpm install`、`pnpm test` 和 `pnpm build`，把 `.theme-sync.json` 与主题更新一起提交。也可以用 `pnpm theme:sync:ui` 打开本机同步面板。

同步范围不含 `src/content/` 下的文章。个人博客里的示例可以自行改写或移除，以后同步时会保留这个选择。</content:encoded><category>主题</category><category>文档</category></item><item><title>深度定制指南</title><link>https://cucurbitulae.com/blog/customize/</link><guid isPermaLink="true">https://cucurbitulae.com/blog/customize/</guid><description>把演示站改成自己的博客：设置首页简介、头像和导航，调整纸色与排版，按需开启评论、浏览量和搜索。</description><pubDate>Sun, 16 Aug 2026 00:00:00 GMT</pubDate><content:encoded>换掉站名和头像之后，最显眼的变化往往来自一句写得像自己的简介。先打开 `src/site-config.ts`；下面提到的字段都可以在现有配置里逐项修改。

## 站名、头像与分享卡片

`site.title` 出现在页头和浏览器标签页，`site.author` 是首页头像旁的名字。把头像放到 `public/`，配置里写它对外的路径。例如，`public/avatar.webp` 对应 `site.avatar: &apos;/avatar.webp&apos;`。站点图标用 `site.favicon`，分享卡片用 `site.ogImage`。如果沿用模板里的文件名，可以直接替换图片。

`site.lang` 用于页面的 `lang` 属性和 RSS 的语言标记。中文博客可以填 `zh-CN`。要把导航里的 “Archives” 改成“归档”，在 `header.menu` 改它的 `title`。目录、阅读时长等界面文字由相应组件提供，改语言标记不会自动翻译这些文字。

## 让首页简介比 About 页短

`home.hero.about` 可以分段写经历和兴趣，About 页会展示全文。首页优先取 `home.hero.summary`；省略这个字段时，会显示 `about` 的第一段。下面是可替换现有 `home.hero` 的示例：

```ts
hero: {
  tagline: &apos;程序员 · 业余摄影爱好者&apos;,
  summary: &apos;记录做工具时踩过的坑，也留一点地方给照片。&apos;,
  about: &apos;我做开发工具，喜欢把重复的小事写成脚本。\n\n周末带相机出门，回来挑一张照片写日记。&apos;,
  buttons: [{ title: &apos;关于我&apos;, link: &apos;/about&apos; }]
}
```

`home.recentPosts` 控制首页近作数量，最多 5 篇，设为 `0` 隐藏。教育经历和技能分别放在 `home.education`、`home.skills`，空数组会隐藏对应分区。想在首页显示标签或友链，开启 `home.showTags` 或 `home.showFriends`；友链内容来自 `friends`。文章列表每页显示几篇由 `blog.pageSize` 单独控制，默认 8 篇。

## 调整导航和页脚

`header.menu` 中每一项都包含显示名称 `title` 和地址 `link`。例如 `{ title: &apos;归档&apos;, link: &apos;/archives&apos; }`。手机上导航在顶栏下方，当前栏目用一条短线标出。菜单只负责链接；新增自定义栏目时，先在 `src/pages/` 创建对应页面。

页脚的文字链接放在 `footer.links`，社交账号放在 `footer.social`。后者也会出现在首页简介下方。复制主题后，记得核对演示站的版权文字、社交地址和备案链接。`footer.showQuote` 决定页脚是否显示引语。

## 换纸色、字体与正文排版

只想换默认外观，可以在 `site` 中把 `palette` 设为 `&apos;ink&apos;` 或 `&apos;fresh&apos;`，把 `theme` 设为 `&apos;system&apos;`、`&apos;light&apos;` 或 `&apos;dark&apos;`。读者保存过的个人选择优先；检查新的站点默认值时，可以用一个新的浏览器配置文件打开预览。

| 想调整的地方                     | 修改位置                                                                                                                                                              |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 浅色和深色的纸面、墨色、强调色   | `src/assets/styles/tokens.css`。`:root`、`.dark`、`.fresh` 和 `.fresh.dark` 对应四套颜色。若改变纸面颜色，`src/utils/theme.ts` 中供浏览器顶栏使用的颜色也要一起调整。 |
| 标题、正文或代码字体             | 同一文件中的 `--font-serif`、`--font-sans` 和 `--font-mono`。                                                                                                         |
| 正文基础字号、行高和代码块样式   | `src/assets/styles/global.css` 中的 `.prose` 与 `.astro-code`。                                                                                                       |
| 正文标题、引用、列表和表格的细节 | `uno.config.ts` 中的 `typography` 配置。文章列与桌面目录的布局在 `src/layouts/PostLayout.astro`。                                                                     |

## 单独开启评论或阅读量

模板默认关闭评论和访问计数。先取得自己的 Waline 服务地址，再在 `src/site-config.ts` 里填需要使用的字段。两项功能可以共用一个服务。[Waline 部署说明](https://waline.js.org/guide/get-started/)

```ts
comment: {
  provider: &apos;waline&apos;,
  server: &apos;https://waline.example.org&apos;
},
pageview: {
  server: &apos;&apos;, // 暂时只开放评论
  siteWide: true
}
```

启用评论后，滚动到文章末尾附近才会加载评论客户端。想单独关闭某篇的评论，在那篇文章开头加 `comment: false`。

要显示文章阅读量，把服务地址也填入 `pageview.server`。此时 `pageview.siteWide: true` 会额外显示页脚的全站访问量；只关掉 `siteWide` 就只保留文章阅读量。计数请求失败时页面显示「—」，实际计数为零时显示 `0`。

## 搜索开关控制什么

`search.enabled: false` 会隐藏页头的搜索入口，访问 `/search` 时页面会提示搜索已关闭。构建仍会生成 `/search-index.json`，其中包含已发表文章的索引。`draft: true` 的文章会从索引中排除，但文章网址依然可以访问。

写作字段和部署环境变量见[安装与使用](/blog/getting-started)。想检查自己的字号和配色是否适合阅读，可以用[Markdown 语法速查](/blog/markdown-guide)里的引用、代码和表格做对照。</content:encoded><category>主题</category><category>文档</category></item><item><title>Markdown 语法速查</title><link>https://cucurbitulae.com/blog/markdown-guide/</link><guid isPermaLink="true">https://cucurbitulae.com/blog/markdown-guide/</guid><description>一页对照常用写法与实际效果：站内链接、图片、带标题的代码块、可展开的长代码、Mermaid 流程图和数学公式。</description><pubDate>Sun, 16 Aug 2026 00:00:00 GMT</pubDate><content:encoded>这篇文章本身就是一份排版样张。写技术笔记时，可以照着下面的例子插入图片、解释一段代码，或者画出几个步骤之间的关系。

## 文本与链接

`**加粗**` 适合点出**结论**，`*serif*` 可以标记外文术语 _serif_，文件名和命令则用反引号包起来，例如 `pnpm dev`。

文章标题来自开头的 `title` 字段，正文从 `##` 二级标题开始写。二到四级标题会出现在文章目录里。链接到别的文章时，从 `/blog/` 开始写；跳到本篇某节时，只写锚点就够了。

```markdown
[主题定制](/blog/customize)
[本篇的流程图](#流程图)
```

试一下：[主题定制](/blog/customize) · [本篇的流程图](#流程图)

## 引用与列表

段首写一个 `&gt;` 就能得到引用块。引用别人的话时，可以另起一行写出处。下面用一段观察记录作示例：

&gt; 下午四点，白云刚好移到窗前那根树枝后面。我等风停了一下，才按下快门。

有先后顺序的操作用编号，例如：

1. 挑出这次要写的照片。
2. 给照片写一句描述。
3. 打开预览，读一遍图注。

## 图片

如果插图已经放在 `src/assets/`，可以在 Markdown 里用相对于**文章源文件**的路径引用它。下面这行适用于当前文件 `src/content/blog/markdown-guide.md`。方括号里写画面的内容，可以帮助读者理解图片。

```markdown
![一枝绿叶横过蓝天，枝条后方是一团白云。](../../assets/cover-demo.png)
```

![一枝绿叶横过蓝天，枝条后方是一团白云。](../../assets/cover-demo.png)

点图可以放大，按 Esc 返回正文。如果给图片加了链接，点击会前往你设置的地址。

## 代码块

在三枚反引号后写上 `ts title=&quot;reading.ts&quot;`，代码框就会显示文件名。要让读者一眼找到计算结果的那一行，在行末加上注释 `// [!code highlight]`。渲染后可以看到高亮效果：

```ts title=&quot;reading.ts&quot;
const wordsPerMinute = 350
const minutes = Math.ceil(700 / wordsPerMinute) // [!code highlight]
```

需要展示修改前后时，可以用 `[!code --]` 标出删去的行，用 `[!code ++]` 标出新增的行。

## 流程图

把代码围栏的语言写成 `mermaid`，就能把文本步骤画成图。下面是这张图的完整源文：

```text
flowchart LR
  A[写文章] --&gt; B[预览] --&gt; C[发布]
```

```mermaid
flowchart LR
  A[写文章] --&gt; B[预览] --&gt; C[发布]
```

## 数学公式

一句话里的公式用一对 `$` 包起来。例如 `$t = n / v$` 会排成 $t = n / v$，其中 $n$ 是字数，$v$ 是每分钟阅读的字数。要让公式单独占一行，把 `$$` 各放在公式的上一行和下一行：

$$
t = \frac{700}{350} = 2
$$

## 表格

表格适合横向比较。第二行的冒号决定该列的对齐方式，例如 `---:` 表示右对齐。

| 稿件 | 字数 | 按每分钟 350 字估算 |
| ---- | ---: | ------------------: |
| 随笔 |  700 |              2 分钟 |
| 教程 | 2100 |              6 分钟 |

## 长代码块折叠

超过 15 行的代码默认折叠。可以用下面的例子试试展开和复制：它从两篇笔记的标签里统计每个标签出现了几次。

```js title=&quot;count-tags.js&quot;
const notes = [
  { title: &apos;窗边的云&apos;, tags: [&apos;摄影&apos;, &apos;随笔&apos;] },
  { title: &apos;整理相册&apos;, tags: [&apos;摄影&apos;, &apos;工具&apos;] }
]

function countTags(notes) {
  const counts = new Map()
  for (const note of notes) {
    for (const tag of note.tags) {
      counts.set(tag, (counts.get(tag) ?? 0) + 1)
    }
  }
  return counts
}

const counts = countTags(notes)
console.log(counts.get(&apos;摄影&apos;)) // 2
```</content:encoded><category>markdown</category><category>写作</category></item><item><title>欢迎使用 astro-theme-ink</title><link>https://cucurbitulae.com/blog/welcome/</link><guid isPermaLink="true">https://cucurbitulae.com/blog/welcome/</guid><description>从一篇文章开始认识这个博客：挑一张喜欢的纸色，翻翻归档，或动手写下第一篇随笔。</description><pubDate>Sun, 16 Aug 2026 00:00:00 GMT</pubDate><content:encoded>首页像一本按时间编排的文集。点开一篇近作，先看到篇名和日期，再往下读。遇到比较长的技术笔记，可以展开手机上的目录，直接跳到手头要用的那一节。

## 挑一种纸色

初次打开时，主题默认使用偏蓝的 `fresh`，明暗跟随系统。如果你喜欢米白纸面和偏暖的墨色，点一下页头的叶子图标，就会切到 `ink`。旁边的明暗按钮可以单独切换，所以暖色纸面也有深色版本。

## 从哪里开始读

还记得文章大约什么时候写的，可以去[归档](/archives)按年份翻。只记得一两个词，直接用[搜索](/search)。想把新文章收进自己的阅读器，订阅地址是 [RSS](/rss.xml)。

如果你也打算用这套主题写博客，可以从自己眼下想做的事开始：

- **搭好博客，发表第一篇文章**：[从零开始：安装与使用](/blog/getting-started)。
- **看看长文、目录和搜索读起来怎样**：[主题特色与阅读体验](/blog/features)。
- **换上自己的头像、简介和配色**：[深度定制指南](/blog/customize)。
- **试写带代码、图表或公式的笔记**：[Markdown 语法速查](/blog/markdown-guide)。</content:encoded><category>主题</category><category>astro</category><category>unocss</category></item></channel></rss>