@jet-w/astro-blog 0.2.0 → 0.2.1

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) 来掌握内容创作。

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

@@ -0,0 +1,52 @@
+---
+title: 快速入门
+description: 从安装到部署，开始你的 Astro 博客之旅
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 入门
+  - 教程
+---
+
+# 快速入门
+
+欢迎！本指南将引导你从零开始设置你的 Astro 博客。
+
+::: tip 适合谁？
+本教程专为初学者设计。即使你是 Astro 或静态站点生成器的新手，也可以按照步骤轻松完成。
+:::
+
+## 学习路径
+
+按顺序学习以下章节：
+
+| 步骤 | 章节 | 你将学到 |
+|------|------|----------|
+| 1 | [介绍](./01-intro) | Astro 博客是什么及其特性 |
+| 2 | [安装](./02-install) | 设置 Node.js 并安装项目 |
+| 3 | [第一篇文章](./03-create-post) | 编写并发布你的第一篇文章 |
+| 4 | [项目结构](./04-structure) | 了解文件的组织方式 |
+| 5 | [部署](./05-deploy) | 构建并部署到网络 |
+
+## 前置要求
+
+在开始之前，请确保你已具备：
+
+- **Node.js 18+** 已安装在你的电脑上
+- 一个**代码编辑器**（推荐 VS Code）
+- 基本的**命令行**使用能力
+
+::: info 没有 Node.js？
+从 [nodejs.org](https://nodejs.org) 下载安装。选择 LTS（长期支持）版本。
+:::
+
+## 所需时间
+
+- **快速设置**：约 5 分钟
+- **完整教程**：约 30 分钟
+
+---
+
+准备好了吗？让我们从 [介绍](./01-intro) 开始！

package/templates/default/content/posts/blog_docs_zh/02.guide/02-containers.md

@@ -0,0 +1,245 @@
+---
+title: 容器
+description: 使用标注框来突出提示、警告和重要信息
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - Markdown
+  - 容器
+---
+
+# 容器
+
+容器是特殊的标注框，用于突出显示重要信息。
+
+## 基本语法
+
+```markdown
+::: type
+内容放在这里
+:::
+```
+
+## 容器类型
+
+### 提示 (Tip)
+
+用于有用的建议：
+
+```markdown
+::: tip
+这是给读者的一个有用提示。
+:::
+```
+
+<div class="container-tip custom-container" data-container-type="tip">
+<div class="container-title">Tip</div>
+<div class="container-content">
+<p>这是给读者的一个有用提示。</p>
+</div>
+</div>
+
+### 信息 (Info)
+
+用于补充说明：
+
+```markdown
+::: info
+这里是一些额外的信息。
+:::
+```
+
+<div class="container-info custom-container" data-container-type="info">
+<div class="container-title">Info</div>
+<div class="container-content">
+<p>这里是一些额外的信息。</p>
+</div>
+</div>
+
+### 警告 (Warning)
+
+用于需要注意的事项：
+
+```markdown
+::: warning
+请小心这个操作。
+:::
+```
+
+<div class="container-warning custom-container" data-container-type="warning">
+<div class="container-title">Warning</div>
+<div class="container-content">
+<p>请小心这个操作。</p>
+</div>
+</div>
+
+### 危险 (Danger)
+
+用于严重警告：
+
+```markdown
+::: danger
+此操作无法撤销！
+:::
+```
+
+<div class="container-danger custom-container" data-container-type="danger">
+<div class="container-title">Danger</div>
+<div class="container-content">
+<p>此操作无法撤销！</p>
+</div>
+</div>
+
+### 备注 (Note)
+
+用于一般性说明：
+
+```markdown
+::: note
+给读者的一个旁注。
+:::
+```
+
+<div class="container-note custom-container" data-container-type="note">
+<div class="container-title">Note</div>
+<div class="container-content">
+<p>给读者的一个旁注。</p>
+</div>
+</div>
+
+## 自定义标题
+
+在类型后添加自定义标题：
+
+```markdown
+::: tip 专业建议
+这个容器有一个自定义标题。
+:::
+```
+
+<div class="container-tip custom-container" data-container-type="tip">
+<div class="container-title">专业建议</div>
+<div class="container-content">
+<p>这个容器有一个自定义标题。</p>
+</div>
+</div>
+
+```markdown
+::: warning 安全提醒
+始终验证用户输入！
+:::
+```
+
+<div class="container-warning custom-container" data-container-type="warning">
+<div class="container-title">安全提醒</div>
+<div class="container-content">
+<p>始终验证用户输入！</p>
+</div>
+</div>
+
+## 丰富内容
+
+容器内支持完整的 Markdown：
+
+```markdown
+::: info 功能特性
+这个博客支持：
+- **Markdown** 格式
+- `代码` 片段
+- [链接](https://example.com)
+:::
+```
+
+<div class="container-info custom-container" data-container-type="info">
+<div class="container-title">功能特性</div>
+<div class="container-content">
+<p>这个博客支持：</p>
+<ul>
+<li><strong>Markdown</strong> 格式</li>
+<li><code>代码</code> 片段</li>
+<li><a href="https://example.com">链接</a></li>
+</ul>
+</div>
+</div>
+
+## 折叠面板 (Details)
+
+创建可展开的区域：
+
+```markdown
+::: details 点击展开
+这些内容默认是隐藏的。
+你可以在这里放很多内容。
+:::
+```
+
+<details class="container-details custom-container" data-container-type="details">
+<summary class="container-title">点击展开</summary>
+<div class="container-content">
+<p>这些内容默认是隐藏的。</p>
+<p>你可以在这里放很多内容。</p>
+</div>
+</details>
+
+### 折叠面板中的代码
+
+```markdown
+::: details 查看解决方案
+function solve() {
+  return 42;
+}
+:::
+```
+
+<details class="container-details custom-container" data-container-type="details">
+<summary class="container-title">查看解决方案</summary>
+<div class="container-content">
+
+```javascript
+function solve() {
+  return 42;
+}
+```
+
+</div>
+</details>
+
+## 最佳实践
+
+<div class="container-tip custom-container" data-container-type="tip">
+<div class="container-title">何时使用容器</div>
+<div class="container-content">
+<ul>
+<li><strong>tip</strong> - 有用的建议、最佳实践</li>
+<li><strong>info</strong> - 背景信息、上下文</li>
+<li><strong>warning</strong> - 潜在问题、需要注意的事项</li>
+<li><strong>danger</strong> - 严重错误、数据丢失风险</li>
+<li><strong>note</strong> - 一般性说明</li>
+<li><strong>details</strong> - 可选内容、长示例</li>
+</ul>
+</div>
+</div>
+
+<div class="container-warning custom-container" data-container-type="warning">
+<div class="container-title">不要过度使用</div>
+<div class="container-content">
+<p>太多容器会分散注意力。谨慎使用，只用于真正重要的信息。</p>
+</div>
+</div>
+
+## 快速参考
+
+| 类型 | 语法 | 用途 |
+|------|------|------|
+| tip | `::: tip` | 有用的建议 |
+| info | `::: info` | 额外信息 |
+| warning | `::: warning` | 注意事项 |
+| danger | `::: danger` | 严重警告 |
+| note | `::: note` | 旁注 |
+| details | `::: details` | 可折叠内容 |
+
+---
+
+下一步：掌握 [代码块](./03-code-blocks) 来展示精美的代码片段。