AstroWind 知识库完全指南

本指南将帮助你快速掌握 AstroWind 知识库的使用，从文章编写到发布，再到布局自定义，让你能够轻松维护自己的知识库网站。

快速开始

项目结构

你的知识库文章存放在 gocode-context/wiki/ 目录下，采用分类目录结构：

gocode-context/wiki/
├── ai/                    # AI 相关文章
│   └── 2025-01/
│       ├── claude-code-guide.md
│       └── ai-fundamentals.md
├── frontend/              # 前端开发文章
│   └── 2025-01/
│       ├── react-tutorial.md
│       └── astro-vs-nextjs.md
├── backend/               # 后端开发文章
│   └── 2025-01/
│       └── kotlin-tutorial.md
├── devops/                # DevOps 文章
│   └── 2025-01/
│       └── docker-tutorial.md
├── tools/                 # 工具教程
│   └── 2025-01/
│       └── markdown-guide.md
├── career/                # 职业发展
│   └── 2025-01/
│       └── interview-guide.md
└── general/               # 通用文章
    └── 2025-01/
        └── welcome-to-gocode.md

为什么这样组织？

内容与代码分离：gocode-context/wiki/ 是唯一的内容源，便于管理和备份
分类清晰：按主题分类，方便查找和维护
时间归档：使用 YYYY-MM 格式的子目录，便于追踪文章创建时间
自动识别：Astro 会自动扫描所有 .md 文件并生成页面

文章发布流程

步骤 1：创建文章文件

根据文章主题，在对应的分类目录下创建 Markdown 文件：

# 示例：创建一篇关于 TypeScript 的前端文章
cd gocode-context/wiki/frontend/2025-01/
touch typescript-guide.md

命名规范：

使用小写字母和连字符（kebab-case）
文件名要简洁且描述性强
例如：react-hooks-guide.md、docker-compose-tutorial.md

步骤 2：编写文章头部（Front Matter）

每篇文章必须以 YAML 格式的头部开始，包含文章的元数据：

---
title: "文章标题"
description: "文章简短描述，会显示在列表页和 SEO 中"
category: "分类名称"
tags: ["标签1", "标签2", "标签3"]
publishDate: 2025-01-20
author: "作者名"
---

字段说明：

字段	必填	说明	示例
`title`	✅	文章标题	”React Hooks 完全指南”
`description`	✅	文章描述（150字以内）	“深入理解 React Hooks 的原理和最佳实践”
`category`	✅	文章分类	”前端开发”
`tags`	✅	标签数组（3-5个）	[“react”, “hooks”, “前端”]
`publishDate`	✅	发布日期	2025-01-20
`author`	推荐	作者名称	”goCode”
`draft`	可选	是否为草稿	true（草稿不会显示）
`updateDate`	可选	更新日期	2025-01-25

步骤 3：编写文章内容

使用 Markdown 语法编写文章内容：

# 文章主标题

文章简介段落...

## 第一部分

内容...

### 子章节

更多内容...

## 第二部分

继续内容...

Markdown 语法支持：

标题（# 到 ######）
粗体（**文本**）和斜体（*文本*）
列表（有序和无序）
代码块（支持语法高亮）
引用块
表格
链接和图片
任务列表

步骤 4：预览文章

启动开发服务器预览文章：

# 在项目根目录执行
pnpm --filter=@gocode/site-astro dev

访问 http://localhost:4321/wiki 查看文章列表，点击文章标题查看详情。

步骤 5：发布文章

文章编写完成后，只需保存文件即可。Astro 会自动：

✅ 扫描 gocode-context/wiki/ 目录
✅ 读取所有 .md 文件
✅ 生成文章列表页（/wiki）
✅ 生成文章详情页（/wiki/文章名）
✅ 更新搜索索引（Pagefind）

无需额外配置！ 文章会立即出现在知识库中。

步骤 6：构建和部署

# 构建生产版本（包含搜索索引）
pnpm --filter=@gocode/site-astro build

# 预览构建结果
pnpm --filter=@gocode/site-astro preview

文章格式规范

标题层级

# 一级标题（文章主标题，只用一次）

## 二级标题（主要章节）

### 三级标题（子章节）

#### 四级标题（细节说明）

建议：

一级标题只在文章开头使用一次
使用二级标题划分主要章节
避免跳级（如从二级直接到四级）

代码块

使用三个反引号包裹代码，并指定语言：

```javascript
function hello() {
  console.log("Hello, World!");
}
```

```typescript
interface User {
  name: string;
  age: number;
}
```

```bash
npm install astro
```

支持的语言：javascript, typescript, python, go, rust, java, kotlin, bash, shell, json, yaml, markdown, html, css, sql 等。

引用块

> 这是一段引用文字。
> 可以跨多行。

> **提示**：这是一个重要提示。

表格

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |

列表

**无序列表**：
- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2
- 项目 3

**有序列表**：
1. 第一步
2. 第二步
3. 第三步

**任务列表**：
- [x] 已完成任务
- [ ] 待完成任务

链接和图片

**内部链接**：
[查看 React 教程](/wiki/react-tutorial)

**外部链接**：
[访问 Astro 官网](https://astro.build)

**图片**：
![图片描述](https://example.com/image.jpg)

布局自定义

知识库列表页自定义

列表页位于 gocode-apps/site-astro/src/pages/wiki/index.astro。

修改页面标题和描述

const metadata = {
  title: '知识库 - GoCode',  // 修改这里
  description: '探索我们全面的知识库...',  // 修改这里
  robots: {
    index: true,
    follow: true,
  },
};

修改页面布局

<Headline
  subtitle="探索我们全面的知识库..."  // 修改副标题
>
  知识库  // 修改主标题
</Headline>

调整文章卡片布局

找到这一行：

<div class="grid gap-6 md:grid-cols-2 lg:grid-cols-3">

修改列数：

md:grid-cols-2：中等屏幕显示 2 列
lg:grid-cols-3：大屏幕显示 3 列

例如，改为 4 列布局：

<div class="grid gap-6 md:grid-cols-2 lg:grid-cols-4">

自定义文章卡片样式

找到文章卡片的 <article> 标签：

<article class="group relative overflow-hidden rounded-lg border border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900 shadow-sm hover:shadow-md transition-shadow">

修改圆角：

rounded-lg：大圆角
rounded-xl：超大圆角
rounded-md：中等圆角

修改阴影：

shadow-sm：小阴影
shadow-md：中等阴影
shadow-lg：大阴影

知识库详情页自定义

详情页位于 gocode-apps/site-astro/src/pages/wiki/[slug].astro。

修改面包屑导航

<nav class="mb-8 text-sm">
  <ol class="flex items-center space-x-2 text-gray-600 dark:text-gray-400">
    <li><a href="/" class="hover:text-blue-600 dark:hover:text-blue-400">首页</a></li>
    <li>/</li>
    <li><a href="/wiki" class="hover:text-blue-600 dark:hover:text-blue-400">知识库</a></li>
    <li>/</li>
    <li class="text-gray-900 dark:text-white">{entry.data.title}</li>
  </ol>
</nav>

修改文章标题样式

<h1 class="text-4xl md:text-5xl font-bold text-gray-900 dark:text-white mb-4">
  {entry.data.title}
</h1>

调整字体大小：

text-3xl：小标题
text-4xl：中等标题
text-5xl：大标题
text-6xl：超大标题

自定义文章内容样式

文章内容使用 Tailwind Typography 插件，样式定义在 <article> 标签的 class 中：

<article class="prose prose-lg dark:prose-invert max-w-none
  prose-headings:font-bold prose-headings:text-gray-900 dark:prose-headings:text-white
  prose-p:text-gray-700 dark:prose-p:text-gray-300
  prose-a:text-blue-600 dark:prose-a:text-blue-400
  ...
">

修改链接颜色：

prose-a:text-blue-600  // 改为其他颜色，如 prose-a:text-green-600

修改代码块背景：

prose-pre:bg-gray-900  // 改为其他颜色，如 prose-pre:bg-slate-900

修改引用块样式：

prose-blockquote:border-l-blue-500  // 改为其他颜色
prose-blockquote:bg-blue-50  // 改为其他背景色

首页知识库区域自定义

首页位于 gocode-apps/site-astro/src/pages/index.astro。

修改”最新文章”数量

找到这一行：

.slice(0, 3);  // 显示 3 篇最新文章

改为显示 6 篇：

.slice(0, 6);

修改文章卡片布局

找到：

<div class="grid gap-6 md:grid-cols-3">

改为 2 列或 4 列：

<div class="grid gap-6 md:grid-cols-2">  // 2 列
<div class="grid gap-6 md:grid-cols-4">  // 4 列

高级功能

1. 草稿功能

在文章头部添加 draft: true 可以将文章标记为草稿：

---
title: "未完成的文章"
description: "这是一篇草稿"
category: "前端开发"
tags: ["react"]
publishDate: 2025-01-20
draft: true  # 草稿不会显示在网站上
---

2. 文章更新日期

使用 updateDate 字段记录文章更新时间：

---
title: "文章标题"
publishDate: 2025-01-10
updateDate: 2025-01-20  # 更新日期
---

3. 自定义分类

你可以创建新的分类目录：

# 创建新分类
mkdir -p gocode-context/wiki/database/2025-01

然后在该目录下创建文章，分类会自动出现在网站上。

4. 全文搜索

网站集成了 Pagefind 全文搜索功能：

自动索引：构建时自动生成搜索索引
中文支持：完美支持中文搜索
实时搜索：输入即搜索，无需点击按钮

重新生成搜索索引：

pnpm --filter=@gocode/site-astro build

5. 添加目录导航（TOC）

虽然当前模板没有内置 TOC，但你可以手动添加：

## 目录

- [第一部分](#第一部分)
- [第二部分](#第二部分)
- [第三部分](#第三部分)

## 第一部分

内容...

## 第二部分

内容...

6. 代码高亮主题

代码高亮使用 Shiki，默认主题为深色。

要修改主题，编辑 astro.config.ts：

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: 'github-dark',  // 改为其他主题
    },
  },
});

可用主题：

github-dark
github-light
dracula
nord
monokai
one-dark-pro

常见问题

Q1: 文章没有显示在网站上？

检查清单：

✅ 文件是否在 gocode-context/wiki/ 目录下？
✅ 文件扩展名是否为 .md？
✅ 文章头部是否包含必填字段（title, description, category, tags, publishDate）？
✅ 是否设置了 draft: true？
✅ 是否重启了开发服务器？

Q2: 搜索功能不工作？

搜索索引只在构建时生成，开发模式下需要先构建一次：

pnpm --filter=@gocode/site-astro build

Q3: 如何修改文章 URL？

文章 URL 由文件名决定。例如：

文件：react-tutorial.md
URL：/wiki/react-tutorial

要修改 URL，只需重命名文件。

Q4: 如何添加图片？

方法 1：使用外部图片

![图片描述](https://example.com/image.jpg)

方法 2：使用本地图片

将图片放在 gocode-apps/site-astro/public/images/ 目录
在文章中引用：

![图片描述](/images/my-image.jpg)

Q5: 如何修改网站配色？

编辑 gocode-apps/site-astro/tailwind.config.js：

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',  // 修改主色调
        accent: '#10b981',   // 修改强调色
      },
    },
  },
};

Q6: 如何添加评论功能？

可以集成第三方评论系统，如 Giscus（基于 GitHub Discussions）：

访问 giscus.app
配置你的 GitHub 仓库
获取嵌入代码
在 wiki/[slug].astro 中添加评论组件

最佳实践

1. 文章组织

按主题分类：使用清晰的分类目录（ai, frontend, backend, devops, tools, career, general）
时间归档：使用 YYYY-MM 格式的子目录
命名规范：使用 kebab-case 命名文件
一文一事：每篇文章专注一个主题

2. 内容编写

清晰的标题：使用描述性强的标题
简洁的描述：description 控制在 150 字以内
合理的标签：每篇文章 3-5 个标签
代码示例：提供完整可运行的代码
图文并茂：适当使用图片和图表

3. SEO 优化

唯一的标题：每篇文章标题不重复
关键词优化：在标题、描述、标签中使用关键词
内部链接：文章之间相互引用
更新日期：定期更新文章内容

4. 性能优化

图片优化：使用 WebP 格式，压缩图片大小
代码分割：避免单个文章过长（建议 5000 字以内）
懒加载：大图片使用懒加载

5. 维护流程

日常维护：

定期检查文章是否需要更新
修复失效的外部链接
更新过时的技术内容
回复用户评论和反馈

版本控制：

# 提交新文章
git add gocode-context/wiki/
git commit -m "docs: 添加 TypeScript 教程"
git push

# 更新文章
git add gocode-context/wiki/frontend/2025-01/react-tutorial.md
git commit -m "docs: 更新 React 教程"
git push

快速参考

创建新文章模板

---
title: "文章标题"
description: "文章简短描述"
category: "分类名称"
tags: ["标签1", "标签2", "标签3"]
publishDate: 2025-01-20
author: "goCode"
---

# 文章标题

文章简介...

## 第一部分

内容...

## 第二部分

内容...

## 总结

总结内容...

常用命令

# 启动开发服务器
pnpm --filter=@gocode/site-astro dev

# 构建生产版本
pnpm --filter=@gocode/site-astro build

# 预览构建结果
pnpm --filter=@gocode/site-astro preview

# 检查类型错误
pnpm --filter=@gocode/site-astro check

文件路径速查

功能	文件路径
文章内容	`gocode-context/wiki/`
列表页	`gocode-apps/site-astro/src/pages/wiki/index.astro`
详情页	`gocode-apps/site-astro/src/pages/wiki/[slug].astro`
首页	`gocode-apps/site-astro/src/pages/index.astro`
配置文件	`gocode-apps/site-astro/src/content/config.ts`
导航栏	`gocode-apps/site-astro/src/navigation.ts`
网站配置	`gocode-apps/site-astro/src/config.yaml`
样式配置	`gocode-apps/site-astro/tailwind.config.js`

总结

通过本指南，你已经掌握了：

✅ 如何创建和发布文章 ✅ 文章格式规范和 Markdown 语法 ✅ 如何自定义页面布局和样式 ✅ 高级功能的使用方法 ✅ 常见问题的解决方案 ✅ 最佳实践和维护流程

现在，你可以轻松维护自己的知识库网站了！如果遇到问题，可以：

查看本指南的常见问题部分
查阅 Astro 官方文档
查阅 AstroWind 文档
在 GitHub 上提交 Issue

祝你使用愉快！🚀