@jet-w/astro-blog 0.1.6 → 0.2.1

package/templates/default/content/posts/blog_docs_zh/01.get-started/02-install.md

@@ -0,0 +1,137 @@
+---
+title: 安装
+description: 设置你的开发环境并安装 Astro 博客
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 入门
+  - 安装
+---
+
+# 安装
+
+本指南将帮助你在电脑上设置 Astro 博客。
+
+## 前置要求
+
+在开始之前，请确保你已具备：
+
+### Node.js
+
+需要 Node.js 18.x 或更高版本。
+
+```bash
+# 检查你的 Node.js 版本
+node --version
+# 应该输出：v18.x.x 或更高
+```
+
+::: tip 安装 Node.js
+如果你没有 Node.js，请从 [nodejs.org](https://nodejs.org) 下载。
+选择 **LTS** 版本以获得最佳稳定性。
+:::
+
+### 包管理器
+
+npm 随 Node.js 一起安装。你也可以使用 pnpm 或 yarn：
+
+```bash
+# 检查 npm 版本
+npm --version
+
+# 或使用 pnpm（推荐，安装更快）
+npm install -g pnpm
+pnpm --version
+```
+
+## 安装依赖
+
+进入你的博客项目文件夹并安装依赖：
+
+```bash
+# 使用 npm
+npm install
+
+# 或使用 pnpm
+pnpm install
+```
+
+这将安装 `package.json` 中定义的所有必需包。
+
+## 启动开发服务器
+
+启动本地开发服务器：
+
+```bash
+# 使用 npm
+npm run dev
+
+# 或使用 pnpm
+pnpm dev
+```
+
+你应该看到类似这样的输出：
+
+```
+🚀 astro  v5.x.x ready in 1234ms
+
+┃ Local    http://localhost:4321/
+┃ Network  use --host to expose
+```
+
+::: tip 热重载
+开发服务器支持热重载。当你保存文件时，浏览器会自动刷新以显示你的更改。
+:::
+
+## 在浏览器中打开
+
+在浏览器中访问 `http://localhost:4321`。你应该能看到你的博客首页！
+
+## 验证安装
+
+检查一切是否正常工作：
+
+1. **首页加载** - 你看到博客首页
+2. **文章列表** - 导航到 `/posts` 查看文章
+3. **深色模式** - 切换顶部的主题开关
+4. **搜索** - 尝试搜索功能
+
+## 常见问题
+
+### 端口已被占用
+
+如果端口 4321 被占用，Astro 会使用其他端口。检查终端输出获取实际 URL。
+
+或者指定不同的端口：
+
+```bash
+npm run dev -- --port 3000
+```
+
+### 依赖安装失败
+
+尝试清除缓存：
+
+```bash
+# 删除 node_modules 和 lock 文件
+rm -rf node_modules package-lock.json
+
+# 重新安装
+npm install
+```
+
+### Node.js 版本过旧
+
+将 Node.js 更新到 18 或更高版本。考虑使用 [nvm](https://github.com/nvm-sh/nvm) 来管理 Node 版本：
+
+```bash
+# 安装 nvm 后：
+nvm install 20
+nvm use 20
+```
+
+---
+
+开发服务器运行起来了吗？太好了！让我们 [创建你的第一篇文章](./03-create-post)。

package/templates/default/content/posts/blog_docs_zh/01.get-started/03-create-post.md

@@ -0,0 +1,176 @@
+---
+title: 创建第一篇文章
+description: 编写并发布你的第一篇博客文章
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 入门
+  - 写作
+---
+
+# 创建第一篇文章
+
+让我们来写你的第一篇博客文章！这才是真正有趣的开始。
+
+## 文章存放位置
+
+所有博客文章都放在 `content/posts/` 目录：
+
+```
+content/
+└── posts/
+    ├── my-first-post.md    ← 你的文章放在这里
+    ├── another-post.md
+    └── tech/               ← 或者放在子目录中
+        └── tutorial.md
+```
+
+## 创建新文章
+
+在 `content/posts/` 中创建一个名为 `hello-world.md` 的文件：
+
+```markdown
+---
+title: Hello World
+description: 我的第一篇博客文章
+pubDate: 2025-01-15
+author: 你的名字
+tags:
+  - 介绍
+categories:
+  - 个人
+---
+
+# Hello World
+
+欢迎来到我的博客！这是我的第一篇文章。
+
+## 我为什么开始写博客
+
+我开始写这个博客是为了：
+
+1. 分享我学到的东西
+2. 记录我的旅程
+3. 与他人建立联系
+
+> 最好的开始时间是昨天，其次是现在。
+
+## 接下来
+
+敬请期待更多关于以下内容的文章：
+
+- Web 开发
+- 我的项目
+- 经验教训
+
+感谢阅读！
+```
+
+## 查看你的文章
+
+保存文件后访问：
+
+```
+http://localhost:4321/posts/hello-world
+```
+
+你的文章应该会以完整的样式呈现！
+
+## 理解 Frontmatter
+
+`---` 标记之间的部分称为 **frontmatter**。它包含文章的元数据：
+
+```yaml
+---
+title: Hello World          # 必填 - 文章标题
+description: 我的第一篇文章  # 用于 SEO 和预览
+pubDate: 2025-01-15        # 发布日期
+author: 你的名字            # 作者名称
+tags:                      # 标签（数组）
+  - 介绍
+categories:                # 分类（数组）
+  - 个人
+draft: false               # true = 从列表中隐藏
+star: false                # true = 精选文章
+---
+```
+
+::: tip 必填与可选
+只有 `title` 是必填的。其他字段都是可选的，但建议填写以便更好地组织和优化 SEO。
+:::
+
+## 使用子目录
+
+使用子目录来组织相关文章：
+
+```
+content/posts/
+├── tutorials/
+│   ├── README.md        ← 显示在 /posts/tutorials
+│   ├── javascript.md    ← 显示在 /posts/tutorials/javascript
+│   └── css.md           ← 显示在 /posts/tutorials/css
+└── projects/
+    └── my-app.md        ← 显示在 /posts/projects/my-app
+```
+
+### 目录 README
+
+每个目录可以有一个 `README.md` 作为该目录的索引页面：
+
+```markdown
+---
+title: 教程
+description: 一步步学习 Web 开发
+---
+
+# 教程
+
+欢迎来到我的教程专区！
+
+- [JavaScript 基础](./javascript)
+- [CSS 技巧](./css)
+```
+
+## URL 路径规则
+
+你的文件路径决定了 URL：
+
+| 文件路径 | URL |
+|----------|-----|
+| `posts/hello.md` | `/posts/hello` |
+| `posts/tech/intro.md` | `/posts/tech/intro` |
+| `posts/tech/README.md` | `/posts/tech` |
+
+::: info 大小写不敏感
+URL 会自动转为小写。`Hello-World.md` 变成 `/posts/hello-world`。
+:::
+
+## 添加图片
+
+将图片放在 `public/images/` 目录并引用：
+
+```markdown
+![我的照片](/images/photo.jpg)
+```
+
+对于文章专用的图片，你可以创建一个文件夹：
+
+```
+public/
+└── images/
+    └── posts/
+        └── hello-world/
+            └── cover.jpg
+```
+
+然后使用：
+
+```markdown
+![封面](/images/posts/hello-world/cover.jpg)
+```
+
+---
+
+恭喜你发布了第一篇文章！接下来，让我们了解 [项目结构](./04-structure)。

package/templates/default/content/posts/blog_docs_zh/01.get-started/04-structure.md

@@ -0,0 +1,173 @@
+---
+title: 项目结构
+description: 了解文件和文件夹的组织方式
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 入门
+  - 结构
+---
+
+# 项目结构
+
+了解项目结构有助于你知道在哪里查找和放置文件。
+
+## 概览
+
+```
+your-blog/
+├── content/              # 你的内容
+│   ├── posts/           # 博客文章
+│   └── pages/           # 独立页面
+├── public/               # 静态资源
+│   ├── images/          # 图片
+│   └── videos/          # 视频
+├── src/
+│   ├── config/          # 配置文件
+│   │   ├── locales/     # 语言配置
+│   │   ├── site.ts      # 站点设置
+│   │   └── ...
+│   └── ...
+├── astro.config.mjs      # Astro 配置
+└── package.json          # 依赖
+```
+
+## 内容目录
+
+这是你的内容存放的地方：
+
+### posts/
+
+Markdown 或 MDX 格式的博客文章：
+
+```
+content/posts/
+├── hello-world.md         # 单篇文章
+├── tutorials/             # 分类文件夹
+│   ├── README.md         # 分类索引
+│   └── getting-started.md
+└── blog_docs_zh/          # 文档
+    └── ...
+```
+
+### pages/
+
+独立页面，如关于、联系：
+
+```
+content/pages/
+├── about.md              # /about
+└── contact.md            # /contact
+```
+
+## Public 目录
+
+直接提供的静态文件：
+
+```
+public/
+├── images/               # 图片
+│   ├── avatar.jpg       # /images/avatar.jpg
+│   └── posts/           # 文章图片
+├── videos/               # 视频
+├── favicon.svg           # 站点图标
+└── robots.txt           # SEO 文件
+```
+
+::: tip 直接访问
+`public/` 中的文件在根 URL 提供。
+`public/images/cat.jpg` → `https://yoursite.com/images/cat.jpg`
+:::
+
+## 配置目录
+
+站点配置文件：
+
+```
+src/config/
+├── locales/              # 语言特定配置
+│   ├── en/              # 英文
+│   │   ├── index.ts
+│   │   ├── site.ts
+│   │   ├── menu.ts
+│   │   ├── footer.ts
+│   │   └── sidebar.ts
+│   └── zh-CN/           # 中文
+│       └── ...
+├── site.ts               # 默认站点配置
+├── menu.ts               # 默认菜单
+├── sidebar.ts            # 侧边栏设置
+├── footer.ts             # 页脚设置
+└── social.ts             # 社交链接
+```
+
+## 关键配置文件
+
+### astro.config.mjs
+
+主要 Astro 配置：
+
+```javascript
+export default defineConfig({
+  integrations: [
+    astroBlog({ i18n: i18nConfig }),
+    vue(),
+    tailwind(),
+  ],
+  site: 'https://yourdomain.com',
+});
+```
+
+### src/config/site.ts
+
+站点元数据：
+
+```typescript
+export const siteConfig = {
+  title: '我的博客',
+  description: '一个关于...',
+  author: '你的名字',
+  avatar: '/images/avatar.jpg',
+};
+```
+
+### src/config/menu.ts
+
+导航链接：
+
+```typescript
+export const menu = [
+  { name: '首页', href: '/', icon: 'home' },
+  { name: '文章', href: '/posts', icon: 'posts' },
+  { name: '关于', href: '/about', icon: 'about' },
+];
+```
+
+## 文件命名规范
+
+| 类型 | 规范 | 示例 |
+|------|------|------|
+| 文章 | 小写加短横线 | `my-first-post.md` |
+| 配置 | camelCase 或 kebab | `site.ts`, `menu.ts` |
+| 图片 | 描述性名称 | `hero-banner.jpg` |
+
+::: warning 避免空格
+不要在文件名中使用空格。使用短横线代替：
+- ❌ `my first post.md`
+- ✅ `my-first-post.md`
+:::
+
+## 各文件夹的作用
+
+| 文件夹 | 用途 | 你应该... |
+|--------|------|-----------|
+| `content/posts/` | 博客文章 | 在这里添加你的文章 |
+| `content/pages/` | 静态页面 | 添加关于、联系页面 |
+| `public/` | 静态资源 | 放置图片、文件 |
+| `src/config/` | 设置 | 自定义你的站点 |
+
+---
+
+现在你了解了结构！让我们学习如何 [部署你的博客](./05-deploy)。

package/templates/default/content/posts/blog_docs_zh/01.get-started/05-deploy.md

@@ -0,0 +1,208 @@
+---
+title: 部署
+description: 构建并部署你的博客到 GitHub Pages
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 入门
+  - 部署
+---
+
+# 部署
+
+是时候与世界分享你的博客了！本指南介绍如何部署到 GitHub Pages。
+
+## 构建生产版本
+
+首先，创建生产构建：
+
+```bash
+npm run build
+```
+
+这会创建一个包含静态文件的 `dist/` 文件夹：
+
+```
+dist/
+├── index.html
+├── posts/
+│   └── hello-world/
+│       └── index.html
+├── assets/
+│   ├── styles.css
+│   └── scripts.js
+└── ...
+```
+
+## 本地预览
+
+部署前测试构建：
+
+```bash
+npm run preview
+```
+
+访问 `http://localhost:4321` 验证一切正常。
+
+## 部署到 GitHub Pages
+
+### 步骤 1: 配置 Astro
+
+更新你的 `astro.config.mjs`：
+
+```javascript
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  site: 'https://username.github.io',
+  base: '/repo-name/',  // 仅在不使用自定义域名时需要
+});
+```
+
+::: tip 自定义域名
+如果使用自定义域名（如 `myblog.com`），设置 `base: '/'` 或完全移除它。
+:::
+
+### 步骤 2: 创建 GitHub Actions 工作流
+
+创建 `.github/workflows/deploy.yml`：
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+### 步骤 3: 启用 GitHub Pages
+
+1. 在 GitHub 上打开你的仓库
+2. 导航到 **Settings** → **Pages**
+3. 在 "Build and deployment" 下，选择 **GitHub Actions** 作为来源
+4. 将代码推送到 `main` 分支
+
+你的站点将可在 `https://username.github.io/repo-name/` 访问
+
+### 步骤 4: 自定义域名（可选）
+
+要使用自定义域名：
+
+1. **添加 CNAME 文件**: 创建 `public/CNAME` 并写入你的域名：
+   ```
+   myblog.com
+   ```
+
+2. **配置 DNS**: 在你的域名注册商添加以下记录：
+   - **A 记录**（用于顶级域名如 `myblog.com`）：
+     ```
+     185.199.108.153
+     185.199.109.153
+     185.199.110.153
+     185.199.111.153
+     ```
+   - **CNAME 记录**（用于 `www` 子域名）：
+     ```
+     www -> username.github.io
+     ```
+
+3. **更新 Astro 配置**：
+   ```javascript
+   export default defineConfig({
+     site: 'https://myblog.com',
+     // 自定义域名不需要 base
+   });
+   ```
+
+4. **在 GitHub 中启用**: 在仓库 Settings → Pages 中，添加你的自定义域名
+
+::: info SSL 证书
+GitHub 会自动提供免费的 SSL 证书。可能需要最多 24 小时生效。
+:::
+
+## 部署清单
+
+部署前验证：
+
+- [ ] `npm run build` 无错误完成
+- [ ] `npm run preview` 正确显示站点
+- [ ] 所有链接正常工作（无断链）
+- [ ] 图片正确加载
+- [ ] Meta 标签已设置（标题、描述）
+- [ ] Favicon 已配置
+
+## 持续部署
+
+配置完成后，你的站点会自动更新：
+
+```bash
+git add .
+git commit -m "添加新博客文章"
+git push origin main
+# 站点在约 1-2 分钟内自动更新！
+```
+
+## 其他部署选项
+
+这个博客可以部署到任何静态托管平台：
+
+- **Vercel** - 零配置 Astro 支持，全球 CDN
+- **Netlify** - 简单设置，支持表单处理
+- **Cloudflare Pages** - 快速边缘网络，免费套餐
+- **AWS S3 + CloudFront** - 可扩展的云托管
+- **Firebase Hosting** - Google 的托管平台
+
+有关这些平台的详细说明，请参阅 [Astro 部署指南](https://docs.astro.build/en/guides/deploy/)。
+
+---
+
+恭喜！你已完成快速入门指南。
+
+继续学习 [写作指南](/posts/blog_docs_zh/02.guide) 来掌握内容创作。