Blogcraft
一个基于 Astro 的极简双语博客。用 Markdown 写作，静态生成，即开即用。支持中英文双语、暗色/亮色主题、全文搜索和 GitHub 讨论评论。
特性
- 双语 — 默认中文，支持英文（
/en/），自动 hreflang SEO、语言切换器、翻译关联 - 暗色/亮色主题 — 遵循
prefers-color-scheme，支持手动切换，localStorage 持久化，无闪烁 - 全文搜索 — 基于 Pagefind，构建时索引，零外部依赖，离线可用
- GitHub 评论 — 集成 Giscus，用 GitHub Discussions 作为评论区，无需额外认证
- SEO 内置 — 自动生成站点地图、Open Graph 标签、robots.txt、语义化 HTML
- 响应式 — 移动优先，最大内容宽度 900px
- 快速 — 纯静态生成，零 JS 运行时
技术栈
| 层 | 选型 |
|---|---|
| 框架 | Astro v5（静态站点生成） |
| 内容 | Markdown + Content Collections |
| 搜索 | Pagefind（构建时索引） |
| 评论 | Giscus（GitHub Discussions） |
| 包管理器 | pnpm |
| 样式 | 纯 CSS + Custom Properties |
前置要求
# 安装 pnpm
npm install -g pnpm快速开始
# 克隆仓库
git clone https://github.com/Alistairccc/BlogCraft.git
cd BlogCraft
# 安装依赖
pnpm install
# 启动开发服务器（默认 http://localhost:4321）
pnpm dev生产构建
pnpm build输出在 dist/ 目录。本地预览：
pnpm preview写作
博文存放在 src/content/blog/，按语言分目录：
src/content/blog/
├── zh/ # 中文文章（默认语言）
│ ├── hello-world.md
│ └── ...
└── en/ # 英文文章
├── hello-world.md
└── ...每篇文章需要 frontmatter：
---
title: "我的第一篇文章"
description: "卡片和 SEO 用的简短描述"
lang: zh
translationKey: "hello-world" # 关联中/英文版本
pubDate: 2026-05-27
draft: false
---关联翻译： 同一篇文章的中英文版本使用相同的 translationKey，页面会自动显示语言切换按钮。
草稿： 设置 draft: true，文章不会出现在首页和站点地图中。
项目结构
BlogCraft/
├── public/
│ ├── favicon.ico
│ └── robots.txt
├── src/
│ ├── components/ # 可复用组件
│ │ ├── BlogCard.astro # 文章卡片
│ │ ├── Footer.astro
│ │ ├── Giscus.astro # Giscus 评论区
│ │ ├── Header.astro
│ │ ├── LanguageSwitcher.astro
│ │ ├── SearchBar.astro
│ │ └── ThemeToggle.astro
│ ├── content/
│ │ ├── blog/en/ # 英文文章（Markdown）
│ │ ├── blog/zh/ # 中文文章（Markdown）
│ │ └── config.ts # Content Collection schema
│ ├── i18n/
│ │ ├── ui.ts # 翻译键值对
│ │ └── utils.ts # i18n 辅助函数
│ ├── layouts/
│ │ └── BaseLayout.astro # 所有页面的 HTML 外壳
│ ├── pages/
│ │ ├── index.astro # 首页（中文）
│ │ ├── about.astro # 关于页（中文）
│ │ ├── blog/ # 博客相关页面
│ │ │ ├── index.astro # 文章列表（中文）
│ │ │ └── [...slug].astro # 文章详情页（中文）
│ │ ├── search.astro # 搜索页（中文）
│ │ └── en/ # 英文版页面
│ │ ├── index.astro
│ │ ├── about.astro
│ │ ├── blog/
│ │ │ ├── index.astro
│ │ │ └── [...slug].astro
│ │ └── search.astro
│ └── styles/
│ ├── global.css # 设计变量、重置、布局
│ └── blog.css # 文章排版样式
├── astro.config.mjs
├── package.json
└── README.md配置
站点 URL
在 astro.config.mjs 中设置域名：
export default defineConfig({
site: 'https://your-domain.com',
});同时更新 public/robots.txt 中的 sitemap URL。
Giscus（评论功能）
博客使用 Giscus 将 GitHub Discussions 作为评论区。
- 确保仓库已开启 GitHub Discussions
- 安装 Giscus app 到你的仓库
- 打开 giscus.app，填入库信息后获取配置
- 更新
src/components/Giscus.astro中的data-repo、data-repo-id、data-category、data-category-id
搜索
搜索使用 Pagefind，作为构建后步骤运行（pnpm build 会执行 astro build && npx pagefind --site dist）。无需外部服务或 API Key。
修改翻译
编辑 src/i18n/ui.ts 来添加或修改翻译键值：
export const ui = {
zh: {
'nav.home': '首页',
'nav.blog': '文章',
},
en: {
'nav.home': 'Home',
'nav.blog': 'Blog',
},
};键名通过 TranslationKey 类型获得强类型支持。
部署
本项目为纯静态站点，可部署到任意静态托管平台（Cloudflare Pages、Vercel、Netlify 等）。构建命令：
pnpm build将 dist/ 目录部署到你的托管平台即可。
许可证
MIT
评论