# Contributing to 知境 / Contributing to Zhijing

> 🇨🇳 感谢你有兴趣为知境贡献！请阅读以下指南。
> 🇬🇧 Thank you for your interest in contributing to Zhijing! Please read the guide below.

---

## 📋 目录 / Contents

- [准备工作 / Prerequisites](#准备工作--prerequisites)
- [如何添加新知识点 / Adding a Topic](#如何添加新知识点--adding-a-topic)
- [文件结构 / File Structure](#文件结构--file-structure)
- [设计规范 / Design Standards](#设计规范--design-standards)
- [提交流程 / Submission](#提交流程--submission)
- [行为准则 / Code of Conduct](#行为准则--code-of-conduct)

---

## 准备工作 / Prerequisites

**中文：** 你只需要一个文本编辑器和基础 HTML/CSS/JS 知识，无需安装任何构建工具。

**English:** You only need a text editor and basic HTML/CSS/JS knowledge. No build tools required.

```bash
git clone https://github.com/chenweilie/learning-lab.git
cd learning-lab
# Open any .html file in your browser directly
```

---

## 如何添加新知识点 / Adding a Topic

**中文：** 每个知识点是一个独立的 HTML 文件，放在对应学科目录下。

**English:** Each topic is a standalone HTML file placed in the corresponding subject directory.

### 1. 复制模板 / Copy Template

```bash
cp template.html physics/my-new-topic.html
```

> ⚠️ **Important:** Use the `template.html` in the root as your starting point. It includes all required scripts (KaTeX, GA, bookmark, theme toggle, wrong-answer tracking).

### 2. 修改内容 / Edit Content

Replace the placeholder content in these sections:

| 区域 / Section | 说明 / Description |
|---|---|
| `<title>` | `主题名 Topic Name — 知境` |
| `#topNav h1` | Topic name (Chinese) |
| `#topNav .subtitle` | Short English subtitle |
| `--primary-gradient` | Subject color (see table below) |
| `quizzes` array | 5+ multiple-choice questions with explanations |
| Three.js scene | Your interactive 3D visualization |
| Sidebar formulas | Key formulas in KaTeX syntax |

### 3. 学科颜色 / Subject Colors

| 学科 | CSS Gradient |
|------|------|
| 物理 Physics | `linear-gradient(135deg, #3B82F6, #0EA5E9)` |
| 数学 Math | `linear-gradient(135deg, #8B5CF6, #A78BFA)` |
| 化学 Chemistry | `linear-gradient(135deg, #06B6D4, #0EA5E9)` |
| 生物 Biology | `linear-gradient(135deg, #10B981, #34D399)` |
| 历史 History | `linear-gradient(135deg, #F59E0B, #FBBF24)` |
| 地理 Geography | `linear-gradient(135deg, #84CC16, #A3E635)` |
| 政治 Politics | `linear-gradient(135deg, #EC4899, #F472B6)` |
| 语文 Chinese | `linear-gradient(135deg, #F97316, #FB923C)` |
| 英语 English | `linear-gradient(135deg, #6366F1, #818CF8)` |

---

## 文件结构 / File Structure

```
learning-lab/
├── index.html          # Homepage (subject grid, search, progress)
├── about.html          # About page
├── review.html         # Wrong answer notebook
├── graph.html          # Knowledge graph (D3.js)
├── paths.html          # Study paths by grade
├── manifest.json       # PWA manifest
├── service-worker.js   # Offline caching
├── graph-data.json     # Knowledge graph data
├── sitemap.xml         # SEO sitemap
├── template.html       # ⭐ START HERE for new topics
├── physics/            # Physics topics
├── math/               # Math topics
├── chemistry/          # Chemistry topics
├── biology/            # Biology topics
├── history/            # History topics
├── geography/          # Geography topics
├── politics/           # Politics topics
├── chinese/            # Chinese Language topics
└── english/            # English topics
```

---

## 设计规范 / Design Standards

### 必须包含 / Required

- ✅ A Three.js or D3.js interactive visualization
- ✅ 5+ quiz questions in the `quizzes` array with answer explanations
- ✅ Key formulas rendered with KaTeX
- ✅ Chinese (`zh-CN`) content, English subtitle welcome
- ✅ `← 返回首页` back button in nav
- ✅ `☆ 收藏` bookmark button (from template)
- ✅ Google Analytics script (use the ID from template)

### 禁止 / Prohibited

- ❌ External images without fallback
- ❌ Backend API calls (must be fully static)
- ❌ jQuery or other large frameworks not already used
- ❌ Content that violates Chinese education standards

### 性能 / Performance

- Page size < 200KB (HTML + inline CSS/JS, excluding CDN scripts)
- Three.js scene: max 50k vertices
- Must render in < 3 seconds on average connection

---

## 提交流程 / Submission

```bash
# 1. Fork the repo on GitHub
# 2. Create a branch
git checkout -b feat/add-moment-of-inertia

# 3. Add your file
# physics/moment-of-inertia.html

# 4. Update index.html — add your topic to the subjects data array
# Find the correct subject's chapters array and add:
# { name: '转动惯量', file: 'physics/moment-of-inertia.html', done: true }

# 5. Update graph-data.json — add your node and any edges

# 6. Commit and push
git add .
git commit -m "feat(physics): add moment of inertia interactive visualization"
git push origin feat/add-moment-of-inertia

# 7. Open a Pull Request on GitHub
```

**PR checklist / PR 自查清单：**
- [ ] Page works offline (open as `file://` in browser)
- [ ] KaTeX formulas render correctly
- [ ] Quiz answers are correct
- [ ] No console errors
- [ ] Added to `index.html` subjects data with `done: true`
- [ ] Added to `graph-data.json` nodes (and edges if applicable)

---

## 行为准则 / Code of Conduct

- 内容必须符合高中教学标准 / Content must align with high school curriculum standards
- 保持友好、开放的讨论态度 / Maintain a friendly, open attitude in discussions
- 学术诚信：引用来源 / Academic integrity: cite your sources
- 语言：中英双语优先 / Language: Chinese + English preferred

---

*由 Bowen @北大附中 维护 ❤️ / Maintained by Bowen @PKUHS*
*[xingzhilearn.com](https://xingzhilearn.com) · [GitHub](https://github.com/chenweilie/learning-lab)*