@jet-w/astro-blog 0.2.0 → 0.2.2

package/templates/default/content/posts/blog_docs_zh/03.config/01-site.md

@@ -0,0 +1,208 @@
+---
+title: 站点设置
+description: 配置站点的标题、描述和元数据
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 配置
+  - 站点
+---
+
+# 站点设置
+
+配置博客的基本信息和元数据。
+
+## 站点配置
+
+### 基本设置
+
+编辑 `src/config/site.ts`：
+
+```typescript
+export const siteConfig = {
+  // 站点标题（显示在浏览器标签和头部）
+  title: '我的超棒博客',
+
+  // 站点描述（用于 SEO）
+  description: '一个关于 Web 开发和技术的博客',
+
+  // 作者名称
+  author: '张三',
+
+  // 作者头像（显示在头部和页脚）
+  avatar: '/images/avatar.jpg',
+
+  // 站点 URL（用于 SEO 和 RSS）
+  url: 'https://myblog.com',
+};
+```
+
+### 多语言设置
+
+对于多语言站点，在语言文件夹中配置：
+
+```typescript
+// src/config/locales/en/site.ts
+export const site = {
+  title: 'My Blog',
+  description: 'A tech blog about web development',
+};
+
+// src/config/locales/zh-CN/site.ts
+export const site = {
+  title: '我的博客',
+  description: '关于 Web 开发的技术博客',
+};
+```
+
+## 导航菜单
+
+### 菜单配置
+
+```typescript
+// src/config/locales/zh-CN/menu.ts
+export const menu = [
+  { name: '首页', href: '/', icon: 'home' },
+  { name: '文章', href: '/posts', icon: 'posts' },
+  { name: '标签', href: '/tags', icon: 'tags' },
+  { name: '关于', href: '/about', icon: 'about' },
+];
+```
+
+### 可用图标
+
+| 图标 | 名称 |
+|------|------|
+| 首页图标 | `home` |
+| 文章图标 | `posts` |
+| 标签图标 | `tags` |
+| 分类图标 | `categories` |
+| 归档图标 | `archives` |
+| 幻灯片图标 | `slides` |
+| 关于图标 | `about` |
+
+### 外部链接
+
+```typescript
+{
+  name: 'GitHub',
+  href: 'https://github.com/username',
+  icon: 'github',
+  external: true  // 在新标签页打开
+}
+```
+
+## 社交链接
+
+在 `src/config/social.ts` 中配置社交媒体链接：
+
+```typescript
+export const socialLinks = [
+  {
+    type: 'github',
+    url: 'https://github.com/username',
+    label: 'GitHub',
+  },
+  {
+    type: 'twitter',
+    url: 'https://twitter.com/username',
+    label: 'Twitter',
+  },
+  {
+    type: 'email',
+    url: 'mailto:hello@example.com',
+    label: '邮箱',
+  },
+];
+```
+
+### 支持的平台
+
+| 类型 | 平台 |
+|------|------|
+| `github` | GitHub |
+| `twitter` | Twitter/X |
+| `linkedin` | LinkedIn |
+| `email` | 邮箱 |
+| `youtube` | YouTube |
+| `discord` | Discord |
+| `rss` | RSS 订阅 |
+
+## 页脚配置
+
+```typescript
+// src/config/locales/zh-CN/footer.ts
+export const footer = {
+  quickLinksTitle: '快速链接',
+  quickLinks: [
+    { name: '首页', href: '/' },
+    { name: '文章', href: '/posts' },
+    { name: '关于', href: '/about' },
+  ],
+  contactTitle: '联系方式',
+};
+```
+
+## Astro 配置
+
+`astro.config.mjs` 中的主要配置：
+
+```javascript
+export default defineConfig({
+  // 你的站点 URL（RSS 和站点地图必需）
+  site: 'https://myblog.com',
+
+  // 如果不在根路径的基础路径
+  base: '/',
+
+  integrations: [
+    astroBlog({ i18n: i18nConfig }),
+    vue(),
+    tailwind(),
+  ],
+});
+```
+
+## SEO 设置
+
+SEO 通过以下方式配置：
+
+1. **站点配置** - 默认标题和描述
+2. **Frontmatter** - 每篇文章的标题和描述
+3. **自动生成** - Meta 标签、Open Graph、Twitter 卡片
+
+### 默认 SEO
+
+```typescript
+// src/config/site.ts
+export const defaultSEO = {
+  title: '我的博客',
+  description: '页面的默认描述',
+  image: '/images/og-default.jpg',
+};
+```
+
+### 文章 SEO
+
+```yaml
+---
+title: 文章标题
+description: 搜索结果中显示的文章描述
+image: /images/post-cover.jpg
+---
+```
+
+## 最佳实践
+
+::: tip 配置技巧
+1. **保持 URL 一致** - 使用或不使用尾部斜杠，但要保持一致
+2. **优化图片** - 头像和 OG 图片应该优化压缩
+3. **写好描述** - SEO 描述控制在 150-160 字符
+4. **更新社交链接** - 保持链接最新且有效
+:::
+
+---
+
+下一步：[侧边栏配置](./02-sidebar)

package/templates/default/content/posts/blog_docs_zh/03.config/02-sidebar.md

@@ -0,0 +1,240 @@
+---
+title: 侧边栏配置
+description: 配置导航树和文档组织
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 配置
+  - 侧边栏
+---
+
+# 侧边栏配置
+
+侧边栏为你的博客提供导航和文档组织功能。
+
+## 基本配置
+
+编辑 `src/config/sidebar.ts`：
+
+```typescript
+export const sidebarConfig = {
+  enabled: true,
+  showSearch: true,
+  showRecentPosts: true,
+  recentPostsCount: 5,
+  showPopularTags: true,
+  popularTagsCount: 8,
+  showArchives: true,
+  archivesCount: 6,
+  groups: [],
+};
+```
+
+## 配置选项
+
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `enabled` | boolean | `true` | 显示/隐藏侧边栏 |
+| `showSearch` | boolean | `true` | 显示搜索框 |
+| `showRecentPosts` | boolean | `true` | 显示最近文章 |
+| `recentPostsCount` | number | `5` | 最近文章数量 |
+| `showPopularTags` | boolean | `true` | 显示标签云 |
+| `popularTagsCount` | number | `8` | 标签数量 |
+| `showArchives` | boolean | `true` | 显示归档 |
+| `archivesCount` | number | `6` | 归档月份数 |
+| `groups` | array | `[]` | 文档树分组 |
+
+## 文档树分组
+
+分组可以为特定区域创建有组织的导航。
+
+### 自动扫描分组
+
+从文件夹自动生成导航：
+
+```typescript
+// src/config/locales/zh-CN/sidebar.ts
+export const sidebar = {
+  groups: [
+    {
+      type: 'scan',
+      title: '文档',
+      icon: 'ri:book-open-line',
+      scanPath: 'blog_docs_zh',
+      collapsed: false,
+      showForPaths: ['/zh-CN/posts/blog_docs_zh/**'],
+    },
+  ],
+};
+```
+
+| 选项 | 描述 |
+|------|------|
+| `type` | `'scan'` 表示自动扫描 |
+| `title` | 分组标题 |
+| `icon` | Remix 图标名称 |
+| `scanPath` | `content/posts/` 中要扫描的文件夹 |
+| `collapsed` | 默认折叠 |
+| `showForPaths` | 仅在匹配的 URL 显示 |
+
+### 手动分组
+
+手动定义导航：
+
+```typescript
+{
+  type: 'manual',
+  title: '资源',
+  icon: 'ri:links-line',
+  items: [
+    { title: 'API 参考', slug: 'api-reference' },
+    { title: '示例', link: 'https://examples.com' },
+  ],
+  showForPaths: ['/posts/api/**'],
+}
+```
+
+## 路径匹配
+
+使用 `showForPaths` 控制分组何时显示：
+
+```typescript
+showForPaths: [
+  '/posts/docs/**',     // 所有文档页面
+  '/posts/tutorials/*', // 仅直接子页面
+  '/about',            // 精确匹配
+]
+```
+
+### 模式语法
+
+| 模式 | 匹配 |
+|------|------|
+| `/posts/docs` | 精确路径 |
+| `/posts/docs/*` | 直接子页面 |
+| `/posts/docs/**` | 所有后代页面 |
+
+## 多语言侧边栏
+
+为每种语言配置不同的侧边栏：
+
+```typescript
+// src/config/locales/en/sidebar.ts
+export const sidebar = {
+  groups: [
+    {
+      type: 'scan',
+      title: 'Documentation',  // 英文
+      scanPath: 'blog_docs_en',
+      showForPaths: ['/posts/blog_docs_en/**'],
+    },
+  ],
+};
+
+// src/config/locales/zh-CN/sidebar.ts
+export const sidebar = {
+  groups: [
+    {
+      type: 'scan',
+      title: '文档',  // 中文
+      scanPath: 'blog_docs_zh',
+      showForPaths: ['/zh-CN/posts/blog_docs_zh/**'],
+    },
+  ],
+};
+```
+
+## 完整示例
+
+```typescript
+// src/config/locales/zh-CN/sidebar.ts
+export const sidebar = {
+  groups: [
+    // 文档区域
+    {
+      type: 'scan',
+      title: '文档',
+      icon: 'ri:book-open-line',
+      scanPath: 'blog_docs_zh',
+      collapsed: false,
+      showForPaths: ['/zh-CN/posts/blog_docs_zh/**'],
+    },
+    // 教程区域
+    {
+      type: 'scan',
+      title: '教程',
+      icon: 'ri:graduation-cap-line',
+      scanPath: 'tutorials',
+      collapsed: true,
+      showForPaths: ['/zh-CN/posts/tutorials/**'],
+    },
+    // 外部资源
+    {
+      type: 'manual',
+      title: '资源',
+      icon: 'ri:links-line',
+      items: [
+        { title: 'Astro 文档', link: 'https://docs.astro.build' },
+        { title: 'Tailwind CSS', link: 'https://tailwindcss.com' },
+      ],
+    },
+  ],
+};
+```
+
+## 侧边栏小部件
+
+侧边栏还显示：
+
+### 最近文章
+
+显示最新发布的文章：
+
+```typescript
+showRecentPosts: true,
+recentPostsCount: 5,
+```
+
+### 热门标签
+
+显示使用最多的标签：
+
+```typescript
+showPopularTags: true,
+popularTagsCount: 8,
+```
+
+### 归档
+
+按月显示文章：
+
+```typescript
+showArchives: true,
+archivesCount: 6,
+```
+
+## 隐藏侧边栏
+
+在 frontmatter 中为特定页面禁用侧边栏：
+
+```yaml
+---
+title: 全宽页面
+showSidebar: false
+---
+```
+
+或全局禁用：
+
+```typescript
+export const sidebarConfig = {
+  enabled: false,
+  // ...
+};
+```
+
+---
+
+下一步：[多语言支持](./03-i18n)