Maxkore的文档站 · 完整使用指南
· 阅读需 4 分钟
恭喜你的个人文档站成功上线！这篇文章将带你全面了解如何使用和维护你的网站。
一、项目结构
你的网站主要包含以下目录：
blog/- 博客文章存放处docs/- 文档教程存放处src/- 源代码（一般不用动）static/- 图片等静态资源
二、写博客文章
2.1 创建新博客
在 blog/ 目录下创建文件，命名格式为：YYYY-MM-DD-标题.md
例如：2026-03-02-学习笔记.md
2.2 博客文件模板
---
title: 文章标题
description: 简短描述
date: 2026-03-02
author: Maxkore
tags: [标签1, 标签2]
---
# 文章标题
这里是正文内容...
## 二级标题
- 列表项1
- 列表项2
> 引用内容
**加粗文字** *斜体文字*
2.3 访问博客
- 博客列表页：
https://docs-site.bbroot.com/blog - 单篇文章：
https://docs-site.bbroot.com/blog/2026/03/02/文章标题
三、写技术文档
3.1 创建新文档
在 docs/ 目录下创建 .md 文件，例如：快速入门.md
3.2 文档文件模板
---
title: 快速入门
description: 5分钟上手
sidebar_position: 1
---
# 快速入门
这里是文档内容...
## 安装步骤
1. 第一步
2. 第二步
3. 第三步
## 代码示例
```javascript
function hello() {
console.log('Hello Maxkore!');
}
### 3.3 访问文档
- 文档首页：`https://docs-site.bbroot.com/docs`
- 单篇文档：`https://docs-site.bbroot.com/docs/快速入门`
---
## 四、日常操作流程
### 4.1 本地开发（可选）
```bash
npm start
# 访问 http://localhost:3000
4.2 提交更新（核心）
每次写完内容，只需要三步：
git add .
git commit -m "描述这次更新了什么"
git push
等待2-3分钟，网站自动更新！
4.3 常用Git命令
| 命令 | 作用 |
|---|---|
git status | 查看修改了哪些文件 |
git add . | 添加所有修改 |
git commit -m "说明" | 提交修改 |
git push | 推送到GitHub（自动部署） |
五、Markdown常用语法
5.1 标题
# 一级标题
## 二级标题
### 三级标题
5.2 列表
- 无序列表1
- 无序列表2
1. 有序列表1
2. 有序列表2
5.3 链接和图片
[链接文字](https://example.com)
5.4 代码块
```javascript
console.log('代码块');
```
5.5 提示框
markdown
:::tip
这是一个小提示
:::
:::warning
这是一个警告
:::
:::danger
这是一个危险提示
:::
:::info
这是一个信息提示
:::
:::note
这是一个普通注释
:::
5.6 表格
markdown
| 表头1 | 表头2 |
|-------|-------|
| 内容1 | 内容2 |
| 内容3 | 内容4 |
六、常见问题
Q1: 修改后网站没变化？
A: 检查三点：
是否执行了 git push
查看GitHub Actions状态：https://github.com/Maxkore-Geek/docs-site/actions
等待2-3分钟缓存刷新
Q2: 如何修改网站主题色？
编辑 src/css/custom.css：
css
:root {
--ifm-color-primary: #6366f1; /* 改为你喜欢的颜色 */
}
Q3: 如何修改网站图标？
替换 static/img/favicon.ico 文件。
Q4: 如何删除页面？
直接在GitHub上删除对应的 .md 文件即可。
七、进阶功能
7.1 文档分类
在 docs/ 下创建文件夹，例如：
text
docs/
├── 入门教程/
│ ├── 第一课.md
│ └── 第二课.md
└── 高级教程/
└── 进阶.md
在每个文件夹中创建 _category_.json：
json
{
"label": "入门教程",
"position": 1
}
7.2 添加搜索功能
注册 Algolia DocSearch，然后在 docusaurus.config.ts 中配置。
7.3 自定义页面
在 src/pages/ 下创建 .tsx 文件，例如 about.tsx：
tsx
import React from 'react';
import Layout from '@theme/Layout';
export default function About() {
return (
<Layout title="关于" description="关于本站">
<div style={{ padding: '2rem' }}>
<h1>关于本站</h1>
<p>这是Maxkore的个人文档站。</p>
</div>
</Layout>
);
}
访问：https://docs-site.bbroot.com/about
八、总结
记住核心工作流：
bash
git add .
git commit -m "更新说明"
git push
就这么简单！有任何问题随时在博客评论区或GitHub Issues中提问。
