Aither (简体中文)

Astro-Theme-Aither 使用指南

Sat, 14 Mar 2026 08:00:00 GMT

本指南涵盖从零开始到完成部署多语言博客的全部内容。你可以从头读到尾，也可以直接跳到需要的章节。 ## 前置条件 - [Node.js](https://nodejs.org/) 22 LTS 或更高版本 - [pnpm](https://pnpm.io/) 10 或更高版本 - 一个 GitHub 账号 - 一个 [Cloudflare](https://cloudflare.com/) 账号（用于部署） ## 安装 ```bash git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git cd YOUR_REPO corepack enable pnpm install pnpm validate pnpm dev ``` 在浏览器中打开 `http://localhost:4321`，你会看到默认的博客页面。 ## 项目结构 ``` src/ ├── components/ # Astro 和 React 组件 ├── config/site.ts # 站点名称、导航、页脚、社交链接 ├── content/posts/ # 按语言组织的博客文章 │ ├── en/ # 英文文章 │ ├── zh-hans/ # 简体中文文章 │ └── .../ # 其他语言 ├── i18n/ # UI 文本翻译 ├── layouts/ # 页面布局 (Layout.astro) ├── lib/ # 工具函数 (posts, formatter 等) ├── pages/ # 路由页面 └── styles/global.css # Tailwind v4 主题变量 ``` ## 配置 ### 站点配置编辑 `src/config/site.ts`——这是整个站点的唯一配置来源。 ```typescript export const siteConfig = { name: '你的博客名称', title: '你的标语。', description: '你的站点描述，用于 SEO。', author: { name: '你的名字', avatar: '', }, // ... }; ``` 主要配置项： | 配置项 | 控制内容 | |--------|---------| | `name` | 导航栏和页脚中的站点标题 | | `social` | 页脚社交链接（GitHub、X、Discord、邮箱、RSS） | | `nav` | 导航栏菜单项 | | `footer.sections` | 页脚栏目链接 | | `ui.defaultMode` | 默认显示模式：`'light'`、`'dark'` 或 `'system'` | | `ui.defaultStyle` | 默认风格主题：`'default'` 或任意内置风格 key | | `ui.showMoreThemesMenu` | 显示或隐藏 `More Themes` 自定义主题选择菜单 | | `blog.paginationSize` | 每页文章数（默认：20） | | `sections` | 自定义内容分区（见下文） | ### 环境变量将 `.env.example` 复制为 `.env` 并填入你的值： ```bash cp .env.example .env ``` | 变量名 | 服务 | 必填 | |--------|------|------| | `PUBLIC_GA_ID` | Google Analytics | 否 | | `PUBLIC_CRISP_WEBSITE_ID` | Crisp 在线客服 | 否 | | `PUBLIC_GISCUS_REPO` | Giscus 评论 | 否 | | `PUBLIC_GISCUS_REPO_ID` | Giscus 评论 | 否 | | `PUBLIC_GISCUS_CATEGORY` | Giscus 评论 | 否 | | `PUBLIC_GISCUS_CATEGORY_ID` | Giscus 评论 | 否 | 留空即可禁用对应服务，无需修改代码。 ### 站点 URL 站点 URL 只需在一处配置——`astro.config.mjs`： ```javascript import { defineConfig } from 'astro/config'; import aither from '@aither/astro'; export default defineConfig({ site: 'https://your-domain.pages.dev', integrations: [aither()], }); ``` 所有组件通过 `import.meta.env.SITE` 读取该值，无需在其他地方重复配置。 ## 写文章 ### 创建文章在 `src/content/posts/en/` 下创建一个新的 `.mdx` 文件： ```markdown --- title: 我的第一篇文章 date: "2026-03-14T16:00:00+08:00" category: General description: 用于 SEO 和社交预览的简短摘要。 tags: [Topic, Another] pinned: false --- 正文从这里开始。使用标准 Markdown 语法。 ``` ### Frontmatter 参考 | 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | `title` | string | 是 | — | 文章标题 | | `date` | date | 是 | — | 发布时间（例如 `2026-03-14T16:00:00+08:00`） | | `category` | string | 否 | `General` | 文章分类 | | `description` | string | 否 | — | SEO 描述 | | `tags` | string[] | 否 | — | 标签列表 | | `pinned` | boolean | 否 | `false` | 是否置顶 | | `image` | string | 否 | — | 封面图片路径 | ### MDX 组件所有文章均使用 `.mdx` 格式，你可以直接在文章中导入和使用 React 组件： ```mdx import MyChart from '@/components/MyChart' 这是一个交互式图表： ``` 这是可选的——`.mdx` 文件中标准 Markdown 语法完全一样可用。 ### 置顶文章在 frontmatter 中设置 `pinned: true`。置顶文章会显示在列表顶部并带有置顶图标，置顶文章之间按日期排序。 ## 国际化（i18n）主题开箱即支持 11 种语言：英语、简体中文、繁体中文、韩语、法语、德语、意大利语、西班牙语、俄语、印度尼西亚语和巴西葡萄牙语。 ### 添加翻译文章在目标语言目录下创建同名文件： ``` src/content/posts/en/my-post.mdx # 英文原文 src/content/posts/zh-hans/my-post.mdx # 中文翻译 src/content/posts/fr/my-post.mdx # 法文翻译 ``` 每个文件是独立的——frontmatter 字段也需要翻译。 ### 翻译 UI 文本 UI 文本（导航、页脚、按钮）位于 `src/i18n/messages/`，每种语言有独立的文件： ``` src/i18n/messages/ ├── en.ts ├── zh-hans.ts ├── fr.ts └── ... ``` 编辑对应文件即可更改任何 UI 文本。 ### 浏览器语言检测主题会检测访客的浏览器语言，并显示横幅建议切换语言。用户的偏好保存在 `localStorage` 中。 ## 自定义内容分区除了博客文章，你还可以创建自定义内容分区（译文、笔记、教程等），每个分区自动拥有独立的列表页、详情页和导航入口。 ### 添加分区 **第 1 步**——在 `src/content.config.ts` 中注册集合： ```typescript const translations = defineCollection({ loader: glob({ pattern: '**/*.mdx', base: './src/content/translations' }), schema: contentSchema, }); export const collections = { posts, translations }; ``` **第 2 步**——在 `src/config/site.ts` 中添加分区配置： ```typescript sections: [ { id: 'translations', labelKey: 'translations' }, ], ``` **第 3 步**——在 `src/i18n/messages/` 的每个语言文件中添加导航标签： ```typescript nav: { blog: '博客', translations: '译文', // 添加这一行 about: '关于', }, ``` **第 4 步**——在 `src/content/translations/en/` 中创建内容： ```markdown --- title: 我的翻译 date: "2026-03-14T16:00:00+08:00" category: General --- 你的翻译内容。 ``` 列表页（`/translations/`）、详情页（`/translations/slug/`）和导航入口会自动为所有 11 种语言生成。 ## 主题定制 ### 模式与风格主题现在分成两层： - 显示模式：浅色、深色、系统（跟随操作系统偏好） - 风格主题：`default` 或任意内置自定义风格，例如 `evolution` 默认值在 `src/config/site.ts` 中配置： ```typescript ui: { defaultMode: 'system', // 'light' | 'dark' | 'system' defaultStyle: 'default', // 'default' | 自定义风格 key showMoreThemesMenu: true, // true 表示显示自定义主题选择器 }, ``` 选择浅色、深色或系统时，会回到主模式；选择自定义风格时，会保留当前的模式偏好，方便后续切回。主题切换继续使用 View Transitions API，实现平滑的圆形展开动画。如果你想让主题 UI 更简洁，可以保留模式切换，并把 `showMoreThemesMenu` 设为 `false`。这样会隐藏自定义风格列表，但仍保留浅色 / 深色 / 系统三档切换。主题展示名和主题 key 是分开的： - `evolution`、`threebody` 这类主题 key 保持稳定，只用于状态和 CSS 选择 - 面向用户的主题名称统一集中在 `src/config/themes.ts` - 本地化时优先翻译通用描述词；品牌名或强 IP 名称可以按目标语言保留一部分原名这样既能保证代码层稳定，也能让不同语言下的主题命名更自然。 ### 颜色编辑 `src/styles/global.css` 中的 CSS 自定义属性。主题使用 Tailwind CSS v4 的 `@theme` 变量： ```css :root { --color-link: ...; --color-link-hover: ...; --color-nav-text: ...; /* 等等 */ } ``` 浅色和深色模式各有一套独立的颜色变量。 ### 字体主题默认使用系统无衬线字体栈，遵循 Apple Human Interface Guidelines 排版参数（17px / 1.47 / -0.022em）。如需使用自定义字体，请在 Tailwind 主题配置中更新 font-family 值。 ## SEO 和 AI 每个页面都针对搜索引擎和 AI 智能体进行了优化： | 功能 | URL | 说明 | |------|-----|------| | 站点地图 | `/sitemap-index.xml` | 自动生成 | | RSS 订阅 | `/rss.xml` | 自动生成 | | robots.txt | `/robots.txt` | 欢迎 AI 爬虫 | | llms.txt | `/llms.txt` | AI 内容索引 | | llms-full.txt | `/llms-full.txt` | AI 全文内容 | | Markdown 导出 | `/posts/slug.md` | 每篇文章的原始 Markdown | | JSON-LD | 每个页面 | 文章结构化数据 | | Open Graph | 每个页面 | 社交预览卡片 | | OG 图片 | `/og/slug.png` | 通过 Satori 自动生成 | ## 部署 ### Cloudflare Pages 最佳实践：先创建 Pages 项目。工作流默认使用仓库名；如果需要覆盖，请设置 `CLOUDFLARE_PAGES_PROJECT_NAME`。设置这些 GitHub Secrets： | Secret | 获取方式 | |--------|---------| | `CLOUDFLARE_API_TOKEN` | Cloudflare 控制台 → API 令牌 | | `CLOUDFLARE_ACCOUNT_ID` | Cloudflare 控制台 → 账户首页 | 然后运行 `pnpm validate`，再推送到 `main`。 ### 自定义域名在 Cloudflare Pages 控制台的项目设置 → 自定义域名中添加。 ## 技术栈 | 层面 | 技术 | |------|------| | 框架 | Astro 6（SSG） | | UI 岛屿 | React 19 | | 样式 | Tailwind CSS v4 | | 组件 | 自定义 Astro 组件 + 少量 React islands | | 内容 | MDX + Content Collections | | OG 图片 | Satori + resvg-js | | 国际化 | 11 种语言 | | 部署 | Cloudflare Pages | | 包管理 | pnpm 10 | | 语言 | TypeScript 5 | ## 常用命令 | 命令 | 说明 | |------|------| | `pnpm dev` | 启动开发服务器（`localhost:4321`） | | `pnpm validate` | 运行完整的推送前校验 | | `pnpm build` | 生产环境构建 | | `pnpm preview` | 本地预览生产构建 | ## 版本规则公开发布的 release tag 使用 CalVer 风格命名，例如 `v2026.04.08`。

AI 智能体在真实项目中的最佳实践（示例）

Sat, 10 Jan 2026 08:00:00 GMT

AI 智能体真正有价值的时候，往往不是它看起来“像魔法”，而是它开始表现得像一套稳定的生产力工具。效果最好的团队，不会让智能体“把一切都做完”，而是会明确任务、提供足够上下文，并让结果易于验证。这听起来很朴素，但差别非常大。任务描述清楚时，智能体可以推进得很快，产出也常常相当扎实。任务边界模糊时，它则容易浪费上下文、走很多弯路，最后交回一份看起来很自信、但没有真正解决问题的结果。 ## 从小而清晰的任务开始最适合交给智能体的任务，通常都具体、明确，而且边界清楚。不要只说“优化一下这个应用”，而要说“修复博客页移动端导航重叠的问题”，或者“为 RSS 订阅源增加一个冒烟测试”。任务越聚焦，智能体的目标就越稳定，也越不容易顺手改动无关部分。这同样能降低审查成本。任务足够小的时候，改了什么、应该怎么测、结果是否正确，都会更容易判断。 ## 把上下文写清楚对智能体来说，重要上下文最好写出来，而不是默认它能自己推断。一份高质量的任务说明通常包括： - 明确的目标 - 相关文件或目录 - 不能改动的约束条件 - 预期输出或完成标准 - 最后需要执行的验证命令人类通常能从零散信息里脑补出很多东西，智能体往往更“字面化”。如果某个细节重要，就应该明确写出来。 ## 尽量让智能体用工具，而不是靠猜智能体在动手之前，应该先查看当前系统，而不是直接套用泛化经验。这意味着先阅读相关文件，检查构建方式，理解现有约定，而不是只凭模型记忆来判断。对外部系统也是一样。如果问题依赖最新文档、部署配置或者线上实际行为，就应该优先用工具确认真实状态，而不是“凭印象回答”。这也是为什么机器可读接口如此重要。清晰的目录结构、明确的校验脚本、类型定义和显式配置，都会让智能体更可靠，因为环境本身就在提供说明。 ## 让输出天然可验证一个好的智能体工作流，不应该止步于“这是答案”，而应该止步于“这是可核验的结果”。要求智能体说明它改了什么、测了什么、哪些地方还没法验证。最理想的产出通常具备这些特点： - diff 足够小 - 校验命令能够通过 - 能给出可复现的截图或预览 - 会明确说明风险和假设验证环节，决定了智能体的产出只是“看起来合理”，还是“真的可以依赖”。 ## 让回滚和修正成本足够低再强的智能体也会走错路。正确做法不是回避智能体，而是让修正代价足够低。尽量把任务拆小，脚本保持稳定，流程保留检查点。能做到幂等的操作就尽量幂等。避免那种“一步走错，后面就会留下很大烂摊子”的工作流。如果一个任务可以拆成读取、规划、实现、验证四步，那就这么拆。智能体在那些易于检查、易于测试、易于继续推进的系统里，表现通常最好。 ## 人工复核仍然不可替代智能体非常擅长速度、覆盖率和重复劳动，但判断力仍然属于人。产品取舍、安全边界、语气风格、品牌表达，以及长期可维护性，仍然应该由理解全局的人来把关。目标不是把人移出流程，而是让人少花时间在机械劳动上，把精力放到真正需要判断和责任的地方。 ## 一个实用的心智模型可以把 AI 智能体看成一个执行力很强、速度很快、而且非常字面化的协作者。给它清晰的任务，给它合适的工具，让它展示过程，然后像审查任何重要改动一样去复核结果。真正的杠杆，就来自这里。

AI 原生内容驱动型网站应该是什么样的？（示例）

Fri, 09 Jan 2026 08:00:00 GMT

过去二十年，我们为人类读者构建网站。接下来的十年，AI 智能体会成为同样重要的读者。这不是一个遥远的假设——它正在发生。 ## 两类读者你的网站现在有两类读者。第一类是人类。他们用眼睛扫描页面，被标题吸引，在段落间跳跃，凭直觉判断一篇文章是否值得读下去。他们需要排版、留白、视觉层级。第二类是 AI 智能体。它们用结构化协议解析页面，从 `llms.txt` 获取站点索引，从 JSON-LD 理解内容语义，从 Markdown 端点提取干净的文本。它们不在乎你的字体多好看——它们在乎你的内容是否机器可读。传统网站只服务第一类读者。AI 原生网站同时服务两类。 ## 内容即接口 AI 原生网站的核心信念是：**内容本身就是接口**。不是 API，不是数据库，不是 GraphQL 端点。是你写的每一篇文章、每一个页面。当内容组织得足够好，AI 智能体可以直接理解和使用它，不需要你额外构建一套"机器专用"的系统。这意味着什么？ ### 结构化元数据每篇文章不仅仅是一段文字。它有标题、日期、分类、标签、描述——这些 frontmatter 字段构成了机器可理解的语义层。搜索引擎十年前就开始利用这些信息，但 AI 智能体对它们的依赖程度远超搜索引擎。一个 AI 智能体在回答"这个项目用了什么技术栈"时，不会像人类一样通读整篇文章。它会先检查 JSON-LD 结构化数据，然后检查 frontmatter 的 tags 和 category，最后才扫描正文。如果你的元数据是空的，智能体的回答质量会大幅下降。 ### 多格式输出同一篇内容应该有多种获取方式： - **HTML 页面**——给人类读者，带排版和样式 - **Markdown 端点**——给需要纯文本的 AI 智能体 - **JSON-LD**——给需要结构化数据的搜索引擎和智能体 - **RSS**——给需要订阅更新的读者和机器人 - **llms.txt**——给需要站点概览的 AI 智能体你不需要为每种格式单独维护内容。写一次 Markdown，系统自动生成所有格式。这是"内容即接口"的实际含义——一次写作，多重消费。 ## 可发现性 AI 智能体如何找到你的内容？答案不是"等它来爬"，而是主动告诉它。 ### robots.txt：欢迎而非拒绝很多网站在 robots.txt 中屏蔽 AI 爬虫。这是一个短视的决定。如果你的内容是公开的、你希望被引用的，那么屏蔽 AI 爬虫只会让你的内容从 AI 的知识图谱中消失。 ``` User-agent: GPTBot Allow: / User-agent: ClaudeBot Allow: / User-agent: PerplexityBot Allow: / ``` 主动欢迎 AI 爬虫，然后用结构化数据引导它们理解你的内容。 ### llms.txt：站点地图的 AI 版本 `sitemap.xml` 告诉搜索引擎你有哪些页面。`llms.txt` 做同样的事，但面向 AI 智能体。它用人类可读的格式描述站点结构、内容分类、获取方式。这不是一个假设的标准——已经有越来越多的 AI 工具在检查这个文件。 ### Markdown 端点：干净的文本在任何文章 URL 后面加 `.md`，返回该文章的原始 Markdown。没有 HTML 标签，没有导航栏，没有页脚——只有标题、元数据和正文。这对 AI 智能体极其友好。它们处理 Markdown 的效率远高于 HTML，因为不需要从大量的布局标记中提取实际内容。 ## 多语言是原生能力在 AI 时代，多语言不再是"锦上添花"，而是基础设施。 AI 智能体服务全球用户。当一个非英语用户通过 AI 智能体查询你的内容时，如果你只有英文版本，智能体需要额外翻译——这个过程中必然损失信息。但如果你提供了对应语言的版本，智能体可以直接引用原文，回答质量显著提高。更重要的是，`hreflang` 标签让 AI 智能体知道同一篇内容有哪些语言版本可用。这是一个被低估的信号——它告诉智能体"这个站点认真对待多语言内容"。 ## 性能就是可访问性页面加载速度不仅影响人类体验。AI 智能体在抓取内容时也有超时限制。一个加载三秒的页面对人类来说"有点慢"，对 AI 爬虫来说可能意味着"抓取失败"。静态生成（SSG）是 AI 原生网站的最佳选择。每个页面都是预渲染的 HTML，没有 JavaScript 执行依赖，没有客户端渲染延迟。AI 爬虫获取的是完整的、最终的内容，而不是一个空的 `

` 等待 JavaScript 填充。这也是为什么 Astro 的岛屿架构特别适合内容驱动型网站——静态 HTML 为主体，只在需要交互的地方加载 JavaScript。 ## 设计哲学把以上所有原则合在一起，AI 原生内容驱动型网站的设计哲学可以总结为： **为人类写作，为机器标注，让内容自己说话。** 你不需要为 AI 做任何"特殊"的事情。你需要做的是把本该做好的事情做到极致：清晰的结构、准确的元数据、多格式输出、合理的语义标记。当你把这些做好，你的内容对人类和机器同时变得更好。这不是未来。这是现在。

✨ 为什么选择 Astro-Theme-Aither（示例）

Sat, 03 Jan 2026 08:00:00 GMT

一个相信文字本身就很美的 AI 原生 Astro 主题。 ## 设计理念极简设计，不极简工程。当页面上没有花哨的视觉元素来掩盖问题时，任何瑕疵都会被放大。极简设计对工程质量的要求更高，而不是更低。排版参数遵循 Apple 人机界面指南：17px / 1.47 / -0.022em。全站统一无衬线系统字体栈。字体本身就是视觉标识。 ## AI 原生为 AI 智能体时代而生。每个页面都天然可被机器阅读： - **llms.txt** — AI 智能体内容索引，`/llms.txt` - **llms-full.txt** — 全文输出，`/llms-full.txt` - **Markdown 端点** — 任何文章 URL 后加 `.md` 获取源文件 - **JSON-LD** — 每篇文章的 Article 结构化数据 - **robots.txt** — 明确欢迎 GPTBot、ClaudeBot、PerplexityBot 你的内容不只是发布了——它是 AI 可发现的。 ## 基于 Astro Astro 的岛屿架构意味着只有交互组件加载 JavaScript。其他一切都是静态 HTML 和 CSS，瞬间加载。交互式岛屿：主题切换器（View Transitions API 圆形展开动画）、语言切换器、浏览器语言检测、移动端导航。 ## 功能 - **Tailwind CSS v4** — `@theme` 设计令牌，完整明暗主题定制 - **i18n** — 多语言支持，自动浏览器语言检测 - **文章置顶** — 将重要文章固定在列表顶部 - **深色模式** — 浅色 / 深色 / 系统，View Transitions API 动画 - **Content Collections** — 构建时类型安全 Markdown 验证 - **SEO** — Open Graph、规范 URL、Twitter Cards - **RSS + 站点地图** — 自动生成，零配置 - **Google Analytics / Crisp Chat / Giscus** — 可选，通过 `.env` 配置 - **Vitest + Playwright** — 单元 + E2E 测试，集成 CI - **部署** — GitHub Pages（默认）+ Cloudflare Pages（可选） ## 适合谁如果你相信好的文字自己会说话： - **博客作者** — 想让文字成为绝对主角 - **技术写作者** — 需要清晰的代码块和内容结构 - **多语言作者** — 需要内置 i18n 和语言检测 - **开发者** — 欣赏工程质量过硬、可放心扩展的代码库写任何话题——排版会让它看起来很好。

📝 Markdown 样式指南（示例）

Fri, 02 Jan 2026 08:00:00 GMT

这篇文章演示了 Astro-Theme-Aither 支持的每一个 Markdown 功能。写作时可以将它作为参考。 Markdown 是一种轻量级标记语言，用纯文本就能写出格式丰富的文章。只需一个文本编辑器和几个简单的符号，就能创作出排版优美的内容。 ## 标题使用 `##` 作为章节标题，`###` 作为子章节，`####` 作为三级子章节。避免在正文中使用 `#`——文章标题已经作为顶级标题渲染。 ### 三级标题 #### 四级标题合理使用标题层级能帮助读者快速了解文章结构。建议每篇文章用两到三级标题，层级过深会让结构变得混乱。好的标题应该简短、清晰，能准确概括该章节的内容。 ## 段落与换行普通段落文本自然流动。在段落之间留一个空行来分隔它们。这是第二个段落。保持每个段落围绕一个想法，以获得最佳阅读体验。写作建议：每个段落不宜过长，三到五句话为佳。过长的段落会形成大块的文字墙，降低阅读的愉悦感。如果一个段落的内容太多，考虑将它拆分为两个段落，或者用列表来组织信息。 ## 强调 - **粗体文本** 使用 `**双星号**` - *斜体文本* 使用 `*单星号*` - ***粗斜体*** 使用 `***三星号***` - ~~删除线~~ 使用 `~~双波浪号~~` 强调应当谨慎使用。如果一段文字中到处都是粗体和斜体，那就等于没有强调。只在真正重要的关键词或短语上使用强调，让它们在视觉上突出出来。 ## 链接 [行内链接](https://astro.build) 使用 `[文本](url)` 语法。链接文本应该有描述性，让读者不点击链接也能知道链接指向什么内容。避免使用"点击这里"或"链接"这样的无意义文本作为链接描述。 ## 列表无序列表： - 第一项 - 第二项 - 嵌套项 - 另一个嵌套项 - 第三项有序列表： 1. 第一步 2. 第二步 1. 子步骤一 2. 子步骤二 3. 第三步任务列表： - [x] 搭建项目 - [x] 写第一篇文章 - [ ] 部署到生产环境列表是组织信息的利器。当你有三个以上的并列项时，用列表比用逗号分隔的句子更清晰。嵌套列表适合展示层级关系，但嵌套不宜超过两层，否则结构会变得难以阅读。 ## 引用 > 抽象的目的不是为了模糊，而是为了创造一个新的语义层级，在其中可以做到绝对精确。 > > — Edsger W. Dijkstra 嵌套引用： > 第一层 > > > 第二层 > > > > > 第三层引用块非常适合用来展示名人名言、重要提示、或者从其他来源引用的段落。在技术文章中，引用块也常被用来高亮需要特别注意的信息，比如注意事项或警告。 ## 代码使用反引号包裹行内 `代码`。带语法高亮的代码块： ```typescript showLanguage interface Post { title: string; date: Date; description?: string; tags?: string[]; draft?: boolean; } function getPublishedPosts(posts: Post[]): Post[] { return posts .filter((post) => !post.draft) .sort((a, b) => b.date.getTime() - a.date.getTime()); } ``` ```css showLanguage @theme { --font-sans: 'system-ui', sans-serif; --font-serif: 'ui-serif', 'Georgia', serif; } ``` 代码块现在默认带行号，写教程、做代码评审，或者引用较长示例时都会更顺手。代码块在技术写作中至关重要。始终为代码块指定语言标识符（如 `typescript`、`css`、`python`），这样渲染引擎才能正确地进行语法高亮。对于 macOS 上的命令行指令，可以使用 `zsh` 作为语言标识符： ```zsh pnpm install pnpm dev ``` 如果是 JSON 配置文件，也可以显式打开语言标题，方便教程里快速分辨代码类型： ```json showLanguage { "name": "my-blog", "version": "1.0.0", "scripts": { "dev": "astro dev", "build": "astro build" } } ``` 行内代码适合在文本中提及变量名、函数名、文件路径等短小的代码片段。比如提到 `getPublishedPosts` 函数或 `src/config.ts` 文件时，用行内代码将它们标记出来，读者能够一眼区分代码和普通文本。 ## 数学公式行内公式可以直接写在句子里，例如 `$E = mc^2$`；较复杂的表达式则适合用块级公式： $$ \int_0^1 x^2 \, dx = \frac{1}{3} $$ 这些公式会在构建阶段通过 KaTeX 渲染成静态输出，因此页面不需要额外依赖浏览器端数学引擎。 ## Mermaid 图表如果你要写流程图、时序图或结构图，可以使用 `mermaid` 代码块： ```mermaid flowchart TD Draft["Markdown 草稿"] --> Build["Astro 构建"] Build --> Html["面向读者的 HTML 页面"] Build --> Protocol["面向智能体的 Markdown 与 JSON"] Html --> Reader["人类读者"] Protocol --> Agent["AI 智能体"] ``` 这类图表会在 Astro 构建时直接变成 SVG，而不是等到前端再运行 Mermaid。 ## 思维导图如果你想从 Markdown 层级直接生成真正的思维导图，可以使用 `markmap` 代码块： ```markmap # Aither 写作 ## Markdown 基础 ### 标题 ### 表格 ## 富文本能力 ### KaTeX 数学公式 ### Mermaid 图表 ### Markmap 思维导图 ## 发布界面 ### 面向读者的页面 ### 面向智能体的端点 ``` 它和普通图表不同：Markmap 会保留层级结构，并提供轻量交互，适合整理大纲、课程内容或复杂主题。 ## 表格 | 功能 | 状态 | 备注 | |---|---|---| | 深色模式 | 支持 | 浅色 / 深色 / 跟随系统 | | RSS 订阅 | 内置 | `/rss.xml` | | 站点地图 | 自动生成 | 通过 `@astrojs/sitemap` | | SEO | 内置 | Open Graph + 规范链接 | 右对齐和居中列： | 左对齐 | 居中 | 右对齐 | |:---|:---:|---:| | 文本 | 文本 | 文本 | | 较长文本 | 较长文本 | 较长文本 | 表格适合展示结构化的对比信息。当数据有明确的行列关系时，表格比段落文字更直观。但 Markdown 表格不适合太复杂的数据——如果你的表格超过五六列或需要合并单元格，可能需要考虑其他展示方式。 ## 分割线使用 `---` 创建分割线： --- 分割线后的内容。分割线适合在同一篇文章中分隔两个主题完全不同的部分。不过，大多数情况下用标题来划分章节就足够了，分割线应当节制使用。 ## 图片图片使用标准 Markdown 语法： ```markdown ![替代文本](./image.jpg) ``` 本主题以排版为核心，但在需要时图片同样可以正常使用。 ### 图片使用建议替代文本（alt text）非常重要。它不仅帮助视障用户通过屏幕阅读器理解图片内容，也在图片加载失败时作为后备显示。好的替代文本应该简洁地描述图片的内容和作用，而不是简单地写"图片"或"截图"。 ## 写作最佳实践掌握 Markdown 语法只是第一步，真正重要的是如何运用这些工具写出高质量的内容。以下是一些通用的写作建议： - **先写大纲再填内容** —— 用标题搭建文章骨架，确定逻辑流向，然后逐节填充细节 - **一个段落一个重点** —— 避免在一个段落中讨论多个不相关的话题 - **善用列表** —— 把并列的信息用列表组织，读者扫一眼就能掌握要点 - **代码配文字** —— 代码块前后加上解释性文字，说明这段代码做了什么、为什么要这样写 - **定期回顾** —— 写完后从头到尾读一遍，删掉多余的内容，改善表达不清的地方 Markdown 的简洁正是它的力量。它让你专注于写作本身，而不是格式调整。希望这篇指南能帮助你充分利用 Astro-Theme-Aither 提供的排版能力，写出赏心悦目的文章。

👋 你好，世界（示例）

Thu, 01 Jan 2026 08:00:00 GMT

欢迎来到 Astro-Theme-Aither。这是一个基于一个信念构建的 AI 原生博客主题：文字本身就很美。统一的无衬线系统字体栈、Apple HIG 排版参数，以及不喧宾夺主的布局。这里的一切都服务于一个目标——让你的文字看起来优美、读起来舒适。 ## 为什么再造一个博客主题互联网上有无数博客主题，那为什么还要再做一个？答案在于优先级。大多数主题为视觉冲击力而优化——大图、复杂布局、华丽动画。这些在演示中很好看，但当读者真正坐下来阅读一篇两千字的文章时，它们只会碍事。 Astro-Theme-Aither 从不同的前提出发：内容就是产品。主题的职责是以它应得的认真态度呈现内容：Apple HIG 正文参数（17px / 1.47 / -0.022em）、充足的留白、让长文阅读变得舒适而不是疲惫的垂直节奏。技术决策也延续了这一理念。主题使用 Astro 的岛屿架构——只有交互组件（主题切换、语言切换、语言检测、移动端导航）加载 JavaScript。其他一切都是静态 HTML 和 CSS。没有布局偏移，没有加载动画。页面加载完毕，你开始阅读。 ## 开始使用搭建只需几步： 1. **克隆仓库** — 使用 GitHub 模板按钮或直接 `git clone` 2. **安装依赖** — 运行 `pnpm install` 3. **配置站点** — 编辑 `src/config/site.ts` 设置标题、描述和导航 4. **配置服务** — 复制 `.env.example` 为 `.env`，填入 API 密钥（GA、Crisp、Giscus） 5. **替换内容** — 用你自己的文章替换 `src/content/posts/` 中的示例 6. **本地开发** — 运行 `pnpm dev` 启动热更新开发服务器 7. **部署** — 推送到 GitHub，CI 工作流自动部署到 Cloudflare Pages ### 项目结构 ``` src/ ├── components/ # Astro 和 React 组件 ├── config/ # 站点配置（site.ts） ├── content/ # Markdown 文章（按语言组织） ├── i18n/ # 翻译和语言工具 ├── layouts/ # 页面布局（Layout.astro） ├── lib/ # 共享工具（posts, formatter, markdown-endpoint） ├── pages/ # 路由页面（按语言） └── styles/ # 全局 CSS + Tailwind v4 @theme 令牌 ``` ### 写第一篇文章在 `src/content/posts/zh-hans/` 下创建 `.md` 文件： ```markdown --- title: 我的第一篇文章 date: "2026-01-15T16:00:00+08:00" category: General description: SEO 和社交预览的简短摘要 tags: [话题, 标签] pinned: false --- 正文从这里开始。 ``` `title`、`date`、`category` 是必填项。`description` 强烈建议填写。设置 `pinned: false` 可将文章置顶。多语言内容只需在对应语言目录（`en/`、`ko/`、`fr/` 等）创建同名文件。 ## 开箱即用 ### 内容功能 - **RSS 订阅** — 自动生成 `/rss.xml` - **站点地图** — 通过 `@astrojs/sitemap` 自动生成 - **SEO 标签** — 每页自动生成 Open Graph、Twitter Cards、规范 URL - **JSON-LD** — Article 结构化数据，服务 AI 和搜索引擎 - **深色模式** — 浅色 / 深色 / 系统切换，View Transitions API 圆形展开动画 - **i18n** — 多语言支持，自动浏览器语言检测 - **文章置顶** — 将重要文章固定在列表顶部 - **分页** — 基于文件的 SSG 分页，带页码导航 ### AI 原生功能 - **llms.txt** — AI 智能体内容索引，`/llms.txt` - **llms-full.txt** — AI 全文消费，`/llms-full.txt` - **Markdown 端点** — 任何文章 URL 后加 `.md` 获取纯 Markdown - **robots.txt** — 明确欢迎 AI 爬虫（GPTBot、ClaudeBot、PerplexityBot） ### 开发者功能 - **TypeScript** — 严格模式，全类型化 - **Content Collections** — 构建时 frontmatter 类型验证 - **Tailwind CSS v4** — `@theme` 设计令牌 - **Vitest + Playwright** — 单元测试 + E2E 测试 - **部署** — GitHub Pages（默认）+ Cloudflare Pages（可选） - **Google Analytics** — 可选，环境变量配置 - **Crisp Chat** — 可选在线客服，环境变量配置 - **Giscus 评论** — 可选 GitHub Discussions 评论 ### 性能静态 HTML + 最小 JavaScript 岛屿 = Lighthouse 四项满分。 ## 自定义 - **颜色** — 编辑 `src/styles/global.css` 中的 CSS 变量 - **字体** — 修改 Tailwind 主题配置中的字体族 - **导航** — 更新 `src/config/site.ts` 中的导航数组 - **服务** — 在 `.env` 中设置 GA、Crisp、Giscus 环境变量 - **语言** — 在 `src/i18n/` 添加新语言，创建对应路由 ## 设计理念主题的视觉简洁是刻意的，但这不等于工程简单。底层处理了大量关注点：Apple HIG 排版参数、明暗两种模式的无障碍色彩对比、View Transitions API 动画、自动浏览器语言检测、语义化 HTML 结构、AI 友好的内容端点，以及从手机到超宽屏的阅读体验优化。好的设计是隐形的。当你在这个主题上阅读一篇文章，只是单纯享受文字而完全没注意到主题的存在——这就是设计在按预期工作。祝写作愉快。