Hansen's ink

主题特色与特性

Mon, 17 Aug 2026 00:00:00 GMT

astro-theme-ink 是一款基于 [Astro 5](https://astro.build) 与 [UnoCSS](https://unocss.dev) 构建的纯静态个人博客主题。本文把它的设计理念与全部特性讲清楚。 ## 设计理念：墨落纸上主题的英文名是 "ink on paper" —— 墨色文字落在纸上。它体现在三件事上： - **单一强调色**：全站只有 accent 一个彩色，其余全部交给灰阶分层与留白 - **衬线标题 + 无衬线正文**：标题用衬线字体营造"印刷页面"的呼吸感 - **克制的动效**：只在你最注意的地方出现 —— 悬停划线、入场淡入、滚动渐显 ## 两套配色 × 明暗模式主题内置两套配色，互相独立，又可与明暗模式任意组合（共 4 种观感）： | 配色 | 气质 | 浅色纸面 | 深色纸面 | | --------- | ------------------ | -------------------- | ------------------- | | **ink** | 暖调纸感 | 米白 `42 35% 97%` | 暖黑 `32 18% 8%` | | **fresh** | 雾霾蓝清新（默认） | 淡蓝白 `212 28% 97%` | 深夜蓝 `215 25% 9%` | 顶栏的调色板按钮（羽毛 / 叶子）切换配色，月亮按钮在亮色 → 暗色 → 跟随系统之间循环，选择都会记住。切换时有 300ms 的柔和过渡；页面顶部还有一层极淡的"天际光晕"渐变，随配色自动变化。 ## 首页：全部配置驱动首页的每个分区都由 `src/site-config.ts` 里的 `home` 配置块驱动，**改配置即改页面，无需碰组件**： - 英雄区：tagline、位置、个人简介、按钮、社交入口 - 最近文章（数量可配） - 教育经历时间线 - 技能分组 - 可选：标签云、友链预览 ## 阅读体验文章页针对长文做了很多设计： - **目录**：桌面端右侧吸顶、滚动高亮当前位置；移动端折叠在文章开头 - **阅读进度条**：顶部一条细线随滚动推进 - **上一篇 / 下一篇**：按发布时间自动取相邻文章 - **封面图**：`heroImage` 字段即可 - **正文排版**：悬停划入的链接下划线、自定义圆点/衬线序号列表、内嵌墨条引用块、渐变分割线、行悬停高亮的表格 ## 代码块代码块走的是构建期 Shiki 管线，与很多成熟主题一致： - 粘性行号 + 左侧条带，横向滚动时行号不消失 - 支持标题（`lang title="文件名"`） - 右上角语言标签，悬停切换为复制按钮（带 "Copied!" 气泡） - 超过 15 行自动折叠，底部 "Show all" 展开 - 支持 `[!code highlight]` 高亮、`[!code ++]` / `[!code --]` diff 标记 ## 搜索与评论 - **站内搜索**：构建时生成 JSON 索引，前端本地过滤 + 关键词高亮，**无任何外部服务** - **评论**：Waline（自部署，Vercel + LeanCloud 即可），配置里填上服务器地址即启用 - **浏览量**：同一 Waline 服务器提供文章页访问计数 ## SEO 与分享 - 每篇文章自动输出 JSON-LD `BlogPosting` 结构化数据 - Open Graph / Twitter Card / canonical / theme-color 齐全 - RSS + sitemap 开箱即用（构建时生成） ## 技术底座 - **Astro 5** 纯静态输出（`output: 'static'`），构建产物可直接托管到任意平台 - **UnoCSS**（presetWind3 + presetTypography + presetIcons）：按需生成，几乎不产生冗余 CSS - 零运行时框架、无 jQuery 之类的依赖，页面体积很小 ## 目录结构 ``` src/ ├── site-config.ts # 所有配置（站点、首页、评论、友链…） ├── content.config.ts # 内容集合 schema ├── assets/styles/ # 设计 token（两套配色）+ 全局样式 ├── components/ # 布局组件（Header/Footer/卡片/目录/评论…） ├── layouts/ # BaseLayout / PostLayout ├── pages/ # 首页、博客、标签、归档、友链、关于、搜索、RSS… ├── plugins/ # Shiki 代码块管线（移植自 astro-theme-pure） ├── utils/ # 工具函数（日期、阅读时长、搜索索引…） └── content/blog/ # 你的文章（Markdown） ``` 下一步：[从零开始：安装与使用](../getting-started/) 会带你把它跑起来。

从零开始：安装与使用

Mon, 17 Aug 2026 00:00:00 GMT

本文带你从零把 astro-theme-ink 跑起来，并完成第一篇文章和一次部署。 ## 1. 环境准备需要 Node.js 22+ 和 pnpm： ```bash node -v # v22.0.0+ pnpm -v # v10+ ``` ## 2. 获取主题把仓库 clone 到本地（或者直接下载 ZIP 解压）： ```bash git clone <你的仓库地址> my-blog cd my-blog ``` > 如果是从 GitHub 模板仓库创建，也可以直接用 "Use this template"。 ## 3. 安装依赖并启动 ```bash pnpm install pnpm dev ``` 打开 http://localhost:4321 就能看到主题首页。开发模式下改文件会热更新。 ## 4. 写第一篇文章在 `src/content/blog/` 下新建一个 Markdown 文件，例如 `hello.md`： ```markdown --- title: '你好，世界' description: '我的第一篇文章。' publishDate: 2026-08-17 tags: [随笔] --- 这里是正文。支持标准 Markdown 语法。 ``` 保存后刷新浏览器，文章就会出现在首页的"最近文章"和 `/blog` 列表里。 **Frontmatter 字段速查：** | 字段 | 必填 | 说明 | | ------------- | ---- | -------------------------------------------------------------------------------------------------------- | | `title` | ✅ | 标题（≤80 字） | | `description` | ✅ | 一句话摘要（≤200 字） | | `publishDate` | ✅ | 发布日期 | | `updatedDate` | — | 更新日期（显示"Updated"） | | `tags` | — | 标签数组 | | `heroImage` | — | 封面图：`heroImage: { src: ../../assets/cover.png, alt: '…' }`（相对文章文件的本地资源，构建时自动压缩） | | `draft` | — | `true` 时仅在 URL 可见，不进列表 | | `comment` | — | 单篇关闭评论 | ## 5. 配置个人信息编辑 `src/site-config.ts`，把站点改成你的： ```ts site: { title: "Hansen's ink", // 站点标题 author: 'Hansen W.', // 作者名 description: '……', lang: 'en', // 语言 avatar: '/avatar.png', // 首页头像（放 public/） palette: 'fresh' // 默认配色：'ink' 或 'fresh' } ``` 首页内容（简介、教育、技能等）改 `home` 配置块，评论和浏览量在 `comment` / `pageview` 里填你的 Waline 服务器地址。 ## 6. 构建与部署 ```bash pnpm build # 产物在 dist/ pnpm preview # 本地预览构建结果 ``` **重要**：部署前把 `astro.config.ts` 里的 `site: 'https://example.com'` 换成你的真实域名 —— sitemap、canonical 和 RSS 都依赖它。纯静态产物可以部署到任何平台： - **Vercel / Netlify**：连上仓库自动构建（build 命令 `pnpm build`，输出目录 `dist`） - **Cloudflare Pages**：同上 - **GitHub Pages**：构建后把 `dist/` 内容推送到 pages 分支 ## 7. 更新主题（主题与博客分开时）如果把主题放在 `D:/Code/astro-theme-ink`，而真实文章和个人配置放在 `D:/Code/Blog`，主题升级时使用同步脚本，而不是直接复制文件： ```powershell cd D:/Code/astro-theme-ink pnpm theme:sync --target ../Blog pnpm theme:sync --target ../Blog --apply cd ../Blog pnpm test pnpm build ``` 第一条只列出变更，第二条才写入。脚本会保留文章、个人图片、域名、部署设置和个人站点配置；将生成的 `.theme-sync.json` 一起提交。需要解决 `REVIEW` 或 `CONFLICT` 时，阅读仓库中的 `docs/theme-sync.md`。也可以执行 `pnpm theme:sync:ui` 打开本机同步面板，在浏览器中完成目录选择、预览和确认应用。 ## 8. 清理演示内容把 `src/content/blog/` 下的示例文章删掉或改写，把 `public/avatar.png`、`favicon/` 换成你自己的，就完成了。遇到问题？可以看[主题特色与特性](../features/)了解功能，或去[深度定制](../customize/)调整细节。

深度定制指南

Sun, 16 Aug 2026 00:00:00 GMT

主题的几乎一切定制都收拢在几个文件里。本文按"配置 → 样式 → 内容 → 部署"的顺序完整过一遍。 ## 1. 站点信息：`src/site-config.ts` ```ts title="site-config.ts" site: { title: "Hansen's ink", // 站点标题（浏览器标签、页头品牌） author: 'Hansen W.', // 作者名（首页与页脚版权） description: '……', // 站点描述（meta description） lang: 'en', // html lang 与 RSS language favicon: '/favicon/favicon.ico', avatar: '/avatar.png', // 首页头像（public/ 下） ogImage: '/og-card.svg', // 社交分享卡片 palette: 'fresh', // 默认配色 'ink' | 'fresh' titleDelimiter: ' · ' // 标题分隔符 } ``` ## 2. 页头与导航 ```ts title="site-config.ts" header: { menu: [ { title: 'Blog', link: '/blog' }, { title: 'Tags', link: '/tags' }, { title: 'Links', link: '/links' }, { title: 'About', link: '/about' } ] } ``` 菜单项在桌面端内联展示，移动端自动变成顶栏下方的横向滚动条。当前页会高亮（带 `aria-current`）。 ## 3. 页脚 ```ts title="site-config.ts" footer: { copyright: '© 2020 - 2026 Hansen W.', // 自定义版权行；不写则默认 © 年份作者 links: [{ title: 'RSS', url: '/rss.xml' }], // 版权行后的链接 social: { github: { label: 'GitHub', url: 'https://github.com/willimt' } // 支持 github/gitlab/rss/mail/x/weibo } } ``` ## 4. 首页内容：配置驱动首页完全由 `home` 配置块驱动，**填了内容分区就出现，清空就消失**： ```ts title="site-config.ts" home: { hero: { tagline: 'Developer / Designer / Photographer', // 名字上方的小字 location: 'China / QingDao', // 位置徽标 about: '一段关于你的介绍……', buttons: [{ title: 'More about me', link: '/about' }] }, recentPosts: 5, // 0 隐藏文章区 education: [ { school: '某大学', major: '专业', degree: '学历', date: 'Aug 2021 - Jul 2024' } ], skills: [ { title: 'Program', items: ['Python', 'Java', 'C'] } ], showTags: false, // 首页是否显示标签云 showFriends: false // 首页是否显示友链预览 } ``` ## 5. 评论系统（Waline）主题的评论和浏览量共用一个 **Waline** 服务器（自部署、无平台绑定）。部署方法： 1. 按 [Waline 官方文档](https://waline.js.org/guide/get-started/) 部署到 Vercel + LeanCloud（或自托管），拿到形如 `https://your-waline.vercel.app/` 的服务器地址 2. 填进 `site-config.ts`： ```ts title="site-config.ts" comment: { provider: 'waline', server: 'https://your-waline.vercel.app/' // 填上即启用评论 } ``` 评论框会出现在文章末尾。`server` 留空则整块隐藏。 ### 文章浏览量同一 Waline 服务器还提供浏览量：把地址填进 `pageview.server`，文章页的 meta 行就会显示当前文章的浏览量： ```ts title="site-config.ts" pageview: { server: 'https://你的-waline-服务器/' // 留空则隐藏 } ``` 实现原理：向 `{server}/article` 发送 POST（`{path, type: 'time', action: 'inc'}`）计数并取回最新值——这是 Waline 3 的计数语义（v2 是 GET 计数，组件会自动回退兼容），无额外依赖；请求失败时显示 0。没有 Waline 的话也可以用不蒜子（busuanzi）之类的服务，自行接入即可。 ### 全站访问量 `pageview.siteWide`（默认 `true`）开启时，页脚会显示"**total visits**"全站总访问量：每个页面每被打开一次就 +1，数据同样来自 Waline 服务器（固定虚拟路径 `/site-pv`），与文章阅读量互不干扰。不需要时设 `siteWide: false` 即可。 ## 6. 搜索开关 ```ts title="site-config.ts" search: { enabled: true } ``` 关闭后顶栏的搜索入口和 `/search` 页内容都会消失（搜索索引也不再生成）。 ## 7. 配色与字体：`src/assets/styles/tokens.css` 两套配色的全部颜色都在这里，直接改 HSL 三元组即可调出你自己的色板： ```css title="tokens.css" :root { /* ink · 浅色 */ --paper: 42 35% 97%; --accent: 22 46% 44%; /* 强调色，改这一个就能换整体气质 */ } .fresh { /* fresh · 浅色 */ --paper: 212 28% 97%; --accent: 213 30% 45%; } .dark { /* ink 深色 */ } .fresh.dark { /* fresh 深色 */ } ``` 字体栈也在这里（`--font-serif/--font-sans/--font-mono`），想换字体改这三行即可。 ## 8. 排版与组件：`uno.config.ts` - `theme.colors`：把 token 映射成工具类（`bg-paper`、`text-ink`…） - `shortcuts`：`paper-card`（卡片）、`chip`（胶囊）、`link-ink`（链接）、`icon-link`（图标按钮） - `presetTypography`：正文排版的全部细节（标题、链接动效、列表标记、引用块、表格…） ## 9. 代码块语法代码块支持标题、高亮和 diff 标记： ````markdown ```bash title="deploy.sh" git pull --ff-only # [!code highlight] systemctl restart my-app # [!code ++] rm -rf /var/cache # [!code --] ``` ```` - `title="文件名"`：显示标题条 - `[!code highlight]`：高亮该行 - `[!code ++]` / `[!code --]`：标记新增 / 删除行 - 超过 15 行自动折叠；右上角悬停出复制按钮 ## 10. 写文章 Frontmatter 字段详见[安装与使用](../getting-started/)。补充几个技巧： - `draft: true`：草稿只通过 URL 访问，不进列表和搜索 - `heroImage: { src: ../../assets/cover.png, alt: '…' }`：文章封面。必须是相对文章文件的本地资源，构建时会被 sharp 压缩并生成响应式尺寸（不会布局抖动） - 正文支持：标题锚点（悬停显示 `#`）、表格、引用、脚注、图片圆角投影；正文里的图片自动懒加载、点击可放大（lightbox） - 数学公式：行内 `$E = mc^2$`、独立公式 `$$...$$`，KaTeX 渲染，自动适配暗色模式（长公式可横向滚动） ## 11. 部署细节 - 把 `astro.config.ts` 的 `site` 改成真实域名（sitemap / canonical / RSS 依赖它） - `pnpm build` 输出纯静态 `dist/`，任意平台可托管 - 备案/ICP 之类的页脚文字写在 `footer.links` 里即可 ## 12. 移除演示内容清单 - `src/content/blog/` 下的示例文章（welcome / features / getting-started / customize / markdown-guide）可全部删除 - `public/avatar.png`、`public/favicon/`、`public/og-card.svg` 换成你的 - `site-config.ts` 里的演示配置改为你的信息 ## 常见问题 **改了颜色没生效？** 确认改的是 `tokens.css` 里的 HSL 三元组（空格分隔，不是逗号），并重新 `pnpm dev` 或构建。 **头像显示不出来？** `site.avatar` 必须是 `public/` 目录下的真实路径（如 `/avatar.png`），放 `src/` 下拿不到。 **评论框不出现？** `comment.server` 为空即关闭。按 Waline 文档部署好服务器后把地址填进 `comment.server`（和 `pageview.server`）再构建。 **想加新的页面类型？** 复制 `src/pages/` 下已有的页面（如 `links/index.astro`）改内容，再在 `header.menu` 加一行导航。 **如何让默认就是雾霾蓝？** `site.palette: 'fresh'`。访问者之后也能在顶栏自由切换，选择会记住。

Markdown 语法速查

Sun, 16 Aug 2026 00:00:00 GMT

本文用来展示主题对 Markdown 的排版效果。 ## 文本 **加粗**、_斜体_、`行内代码`，以及[链接](https://astro.build)。 ## 引用 > 墨水有它的脾气：落在纸上之前，谁也不知道它会洇开多少。 > > —— 佚名 ## 代码块 ```ts // 一个简单的类型 interface Post { title: string description: string publishDate: Date tags: string[] } ``` ```bash pnpm dev ``` ## 列表有序列表： 1. 打开终端 2. 安装依赖 3. 开始写作无序列表： - 温暖纸感配色 - 衬线标题 - 轻量搜索 ## 表格 | 功能 | 状态 | 备注 | | ---- | ---- | ------------- | | RSS | ✅ | 开箱即用 | | 搜索 | ✅ | 本地索引 | | 评论 | ⚙️ | 需配置 Waline | ## 图片本地图片会被自动懒加载并居中、圆角展示；推荐用 HTML 标签写上宽高避免布局抖动： ## 长代码块折叠超过 15 行的代码块会自动折叠，点击底部的 "Show all" 展开： ```bash # 一个很长的部署脚本示例（用于演示代码块折叠） set -euo pipefail APP_DIR="/opt/my-app" BACKUP_DIR="/var/backups/my-app" log() { echo "[$(date +'%Y-%m-%d %H:%M:%S')] $*" } backup() { log "Backing up $APP_DIR ..." mkdir -p "$BACKUP_DIR" tar -czf "$BACKUP_DIR/app-$(date +%Y%m%d%H%M%S).tar.gz" -C "$APP_DIR" . log "Backup done." } deploy() { log "Pulling latest code ..." cd "$APP_DIR" && git pull --ff-only log "Restarting service ..." systemctl restart my-app log "Service restarted." } main() { backup deploy log "All done. Exiting." } main "$@" ```

欢迎使用 astro-theme-ink

Sun, 16 Aug 2026 00:00:00 GMT

欢迎来到 **astro-theme-ink** —— 一款温暖纸感风格的个人博客主题。 ## 设计理念墨落在纸上。全站只使用一种强调色（赭石色），其余全部交给灰阶分层与留白： - 米白/奶油底色，暖墨色文字 - 衬线字体标题，营造"印刷页面"的感觉 - 克制的微交互：卡片悬停、箭头滑动、滚动渐隐 ## 功能特性 - 📝 文章列表分页、标签、按年归档 - 🔍 内置轻量全文搜索（构建时生成索引，无外部依赖） - 💬 Waline 评论 + 浏览量（可选，共用一个服务器） - 📡 RSS 订阅 - 🌗 亮色 / 暗色 / 跟随系统三种主题 - 📖 文章目录（桌面端侧栏） - 🚀 纯静态输出，可部署到任意平台 ## 快速开始 ```bash pnpm install pnpm dev ``` 构建并预览： ```bash pnpm build pnpm preview ``` ## 写一篇文章在 `src/content/blog/` 下新建一个 Markdown 文件即可： ```markdown --- title: '文章标题' description: '一句话摘要' publishDate: 2026-08-16 tags: [标签一, 标签二] --- 这里是正文。 ``` > 提示：`draft: true` 可以让文章只在 URL 下可见、不出现在列表中。 ## 主题文档系列 - [主题特色与特性](../features/) —— 设计理念与全部功能 - [从零开始：安装与使用](../getting-started/) —— 环境、安装、写文章、部署 - [深度定制指南](../customize/) —— 配置、配色、代码块语法、FAQ 祝写作愉快。