メインコンテンツまでスキップ

📚 个人博客项目协作完整指南

· 約12分
朱超凡

这是一份面向 零基础新手 的详细指南，帮助你参与到这个多语言技术博客项目的维护中来。即使你对 GitHub 和 Markdown 完全陌生，按照这个指南也能快速上手！

🎯 项目概览​

项目地址：https://github.com/chaofan920/my-website
线上网站：https://www.zhuchaofan.online/
技术栈：Docusaurus 2.3.1 + React + Markdown

这是一个多语言（日语、中文、英语）的个人技术博客，主要包含：

  • 🔧 后端技术分享（Java、Python、数据库等）
  • 🇯🇵 日语学习资料（N2/N3 语法和词汇）
  • 🛠️ 开发工具使用指南
  • 📝 其他技术文档

📋 准备工作清单​

1️⃣ 必需软件安装​

注意：请按顺序安装，每个软件安装完成后重启终端/命令提示符再进行下一步。

Windows 用户：​

  1. Node.js：

    • 访问 nodejs.org
    • 下载 LTS 版本（必须 ≥16.14）
    • 安装时勾选所有选项
    • 验证：打开命令提示符，输入 node --version

  2. Git：

    • 访问 git-scm.com
    • 下载 Windows 版本
    • 安装时保持默认设置
    • 验证：输入 git --version

  3. 代码编辑器：

    • 推荐 VS Code
    • 安装后推荐插件：Chinese Language Pack、Markdown All in One

macOS 用户：​

# 如果没有 Homebrew，先安装：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js 和 Git
brew install node git

# 验证安装
node --version
git --version

2️⃣ GitHub 账号设置​

  1. 注册 GitHub 账号：访问 github.com 注册
  2. 配置 Git 用户信息：
    git config --global user.name "你的姓名"
    git config --global user.email "你的邮箱@example.com"

🤝 获取项目访问权限​

方式一：成为协作者（推荐）​

  1. 将你的 GitHub 用户名提供给项目维护者
  2. 维护者会邀请你成为协作者
  3. 检查邮箱，接受邀请

方式二：Fork 项目​

  1. 访问项目页面：https://github.com/chaofan920/my-website
  2. 点击右上角 "Fork" 按钮
  3. 等待 Fork 完成

💻 本地环境搭建​

1️⃣ 克隆项目到本地​

如果你是协作者：

# 选择一个工作目录（比如桌面）
cd Desktop

# 克隆项目
git clone https://github.com/chaofan920/my-website.git

# 进入项目目录
cd my-website

如果你使用 Fork：

# 克隆你的 Fork（替换 YOUR_USERNAME）
git clone https://github.com/YOUR_USERNAME/my-website.git
cd my-website

# 添加原始仓库为上游
git remote add upstream https://github.com/chaofan920/my-website.git

2️⃣ 安装项目依赖​

# 安装依赖（这一步可能需要几分钟）
npm install

3️⃣ 启动开发服务器​

# 启动开发环境
npm start

成功后，你会看到类似输出：

Local:            http://localhost:3000/

在浏览器中打开 http://localhost:3000/ 就能看到网站了！

📁 项目结构详解​

my-website/
├── docs/                    # 文档内容
│   ├── backEnd/            # 🔧 技术分享
│   │   ├── Java/           # Java 相关
│   │   ├── Python/         # Python 相关
│   │   └── Database/       # 数据库相关
│   ├── frontEnd/           # 🇯🇵 日语学习
│   │   ├── N2/             # N2 级别内容
│   │   │   └── grammar/    # N2 语法
│   │   └── N3/             # N3 级别内容
│   │       └── grammar/    # N3 语法
│   ├── Tool/               # 🛠️ 工具指南
│   └── Others/             # 📝 其他内容
├── blog/                   # 博客文章
├── src/                    # 网站源代码
└── i18n/                   # 多语言翻译文件

✍️ 内容创作指南​

🎯 最常见：添加日语语法内容​

这是最频繁的操作，让我们详细说明：

1️⃣ 确定添加位置​

  • N2 语法：docs/frontEnd/N2/grammar/
  • N3 语法：docs/frontEnd/N3/grammar/

2️⃣ 查找下一个编号​

# 查看 N2 语法的最大编号
grep -r "sidebar_position:" docs/frontEnd/N2/grammar/ | sort -t: -k3 -n | tail -5

# 查看 N3 语法的最大编号  
grep -r "sidebar_position:" docs/frontEnd/N3/grammar/ | sort -t: -k3 -n | tail -5

3️⃣ 创建新文件​

文件命名规则：编号-语法点名称.md 例如：23-nagara.md

4️⃣ 文件内容模板​

---
sidebar_position: 23
---

# 〜ながら

## 🌟 基本用法

**意思**：一边...一边...；同时进行两个动作

**接续**：动词ます形（去掉ます）+ ながら

## 🌟 例句

### 基本例句
- 音楽を**聞きながら**勉強します。
  - （一边听音乐一边学习。）

- テレビを**見ながら**食事をします。
  - （一边看电视一边吃饭。）

### 进阶例句
- 彼は歩き**ながら**電話をしています。
  - （他一边走路一边打电话。）

## 🌟 使用注意点

1. **主语必须相同**：两个动作的主语必须是同一个
2. **同时性**：强调两个动作同时进行
3. **主次关系**：ながら前面的动作通常是次要的

## 🌟 相似语法比较

| 语法 | 用法 | 例句 |
|------|------|------|
| 〜ながら | 同时进行 | 歌いながら踊る |
| 〜て | 顺序动作 | 歌って踊る |

## 🌟 一句话总结
一边做A，一边做B的时候用「Aながら」。

5️⃣ 预览和测试​

# 启动开发服务器查看效果
npm start

# 检查构建是否成功
npm run build

📝 添加技术博客文章​

1️⃣ 在 blog 目录创建文件​

文件名格式：YYYY-MM-DD-标题.md 例如：2024-01-15-spring-boot-tutorial.md

2️⃣ 博客文章模板​

---
slug: spring-boot-tutorial
title: Spring Boot 快速入门教程
authors: [你的用户名]
tags: [Java, Spring Boot, 后端]
---

# Spring Boot 快速入门教程

这篇文章将介绍如何快速上手 Spring Boot...

<!-- truncate -->

## 什么是 Spring Boot

Spring Boot 是...

## 快速开始

### 1. 创建项目
...

🔧 添加技术文档​

在对应的 docs/ 子目录下创建 .md 文件，参考现有文件的格式。

🔄 Git 工作流程​

📚 基本概念​

  • Repository (仓库)：项目的存储空间
  • Clone (克隆)：下载项目到本地
  • Commit (提交)：保存更改的快照
  • Push (推送)：上传本地更改到 GitHub
  • Pull (拉取)：下载 GitHub 的最新更改

🔄 标准工作流程​

# 1. 开始工作前，获取最新代码
git pull origin master

# 2. 查看当前文件状态
git status

# 3. 添加你修改的文件到暂存区
git add .
# 或者添加指定文件
git add docs/frontEnd/N3/grammar/新文件.md

# 4. 提交更改（必须写清楚做了什么）
git commit -m "添加N3语法：〜ながら的详细用法说明"

# 5. 推送到 GitHub
git push origin master

🚨 常见问题解决​

问题1：推送被拒绝​

# 错误信息：Updates were rejected...
# 解决方法：先拉取远程更改
git pull origin master
git push origin master

问题2：合并冲突​

# 如果出现冲突，编辑冲突文件，然后：
git add .
git commit -m "解决合并冲突"
git push origin master

问题3：撤销本地更改​

# 撤销未提交的更改
git checkout -- 文件名

# 撤销所有未提交的更改
git checkout -- .

🧪 测试和验证​

本地测试​

# 启动开发服务器，检查页面效果
npm start

# 构建项目，检查是否有错误
npm run build

# 本地服务构建后的网站
npm run serve

提交前检查清单​

  • 新文件包含正确的 sidebar_position
  • Markdown 语法正确
  • 本地 npm start 能正常显示
  • npm run build 没有错误
  • Git commit 信息描述清楚

🎨 Markdown 语法速查​

基础语法​

# 一级标题
## 二级标题
### 三级标题

**粗体文字**
*斜体文字*

- 列表项 1
- 列表项 2
  - 嵌套列表项

1. 有序列表 1
2. 有序列表 2

> 引用文字

[链接文字](https://example.com)

`行内代码`

​```javascript
// 代码块
console.log("Hello World");
​```

| 表头1 | 表头2 |
|-------|-------|
| 内容1 | 内容2 |

常用 Emoji 表情​

  • 🌟 重点强调
  • 💡 提示技巧
  • ⚠️ 注意警告
  • 🔧 技术相关
  • 📝 文档说明
  • 🇯🇵 日语相关
  • 🎯 目标重点

📞 获取帮助​

遇到技术问题时​

  1. 查看错误信息：仔细阅读终端的错误提示
  2. 检查网络连接：确保能访问 GitHub
  3. 重启开发服务器：Ctrl+C 停止后重新 npm start
  4. 清理缓存：npm run clear 然后重新启动

联系方式​

  • GitHub Issues：在项目页面提交问题
  • 实时沟通：通过项目维护者提供的联系方式

📚 学习资源推荐​

Git 学习​

Markdown 学习​

Docusaurus 学习​

🎉 开始你的第一次贡献​

现在你已经掌握了所有必要的知识，可以开始你的第一次贡献了！

建议的第一个任务：

  1. 添加一个简单的 N3 语法点
  2. 练习完整的 Git 工作流程
  3. 观察网站的变化

记住：

  • 不要害怕出错：所有更改都可以撤销
  • 小步快跑：从简单的内容开始
  • 及时沟通：遇到问题随时询问

欢迎加入项目维护团队！🎊