跳转至

11 GitHub README 与文档规范

README.md 是什么

仓库根目录下的 README.md，是别人打开你项目看到的第一屏。GitHub / Gitee 会自动把它渲染在仓库首页。

💡 名字固定、大小写不敏感（README.md / readme.md 都认），扩展名必须是 .md。

一个标准 README 的结构

# 项目名

一句话介绍项目是干什么的。

![截图或 Logo](images/preview.png)

## ✨ 特性
- 特性一
- 特性二

## 📦 安装
```bash
git clone https://github.com/user/repo.git
cd repo
```

## 🚀 快速开始
1. 第一步
2. 第二步

## 📖 文档
详细文档见 [文档站](https://docx.ffsmcserver.top/)

## ❓ 常见问题
| 问题 | 解决 |

## 🤝 贡献
欢迎提 Issue / PR。

## 📄 许可证
GPL-3.0

顶部加徽章（Badge）

用 shields.io 生成的小图标，看起来很专业：

![License](https://img.shields.io/badge/license-GPL--3.0-blue)
![Java](https://img.shields.io/badge/Java-17-orange)
![Minecraft](https://img.shields.io/badge/Minecraft-1.20.1-green)

效果：

License Java Minecraft

格式：https://img.shields.io/badge/标签-内容-颜色（内容里的 - 要写成 --）

写代码块时注意语言标记

```bash
./gradlew build

写成 `bash` 而不是 `text`，GitHub 才会高亮命令行。

## 相对路径链接

README 里引用仓库内文件用相对路径：

```markdown
[开发文档](docs/development.md)
[截图](images/screenshot.png)
[更新日志](CHANGELOG.md)

这样在 GitHub 上点、在本地编辑器里点、clone 下来都能用。

目录（长 README 必备）

GitHub 不自动生成目录，可以手写锚点：

## 目录
- [特性](#-特性)
- [安装](#-安装)
- [快速开始](#-快速开始)
- [许可证](#-许可证)

⚠️ 锚点规则：标题里英文转小写、空格变 -、Emoji 和大多数符号会被去掉。 ## ✨ 特性 → #-特性（✨ 变成一个 -），所以要自己试出来。写完点一下链接验证。

Issue 与 PR 模板

在仓库建 .github/ISSUE_TEMPLATE/bug_report.md：

---
name: Bug 反馈
about: 报告一个 bug
---

## 问题描述
简要说明遇到的问题。

## 复现步骤
1. 
2. 

## 期望行为
本来应该怎么样。

## 环境信息
- 系统：
- 软件版本：

## 日志/截图

好处：别人提 Issue 时自动套用这个格式，信息不缺项。

项目文档目录规范

大一点的项目通常这样组织：

repo/
├── README.md            # 门面：介绍 + 快速开始
├── CHANGELOG.md         # 更新日志
├── LICENSE              # 许可证
├── CONTRIBUTING.md      # 贡献指南
├── docs/                # 详细文档
│   ├── index.md
│   ├── install.md
│   ├── usage.md
│   └── images/
└── .github/
    ├── ISSUE_TEMPLATE/
    └── workflows/       # CI

CHANGELOG 怎么写

# 更新日志

## [1.2.0] - 2026-09-20
### 新增
- 支持自定义队伍人数

### 修复
- 修复比赛结束后未重置计分的问题

### 变更
- 默认目标分值从 20 调整为 30

## [1.1.0] - 2026-09-01
### 新增
- 首个可用版本

推荐遵循 Keep a Changelog 规范：分「新增 / 变更 / 修复 / 移除」四类。

写 README 的几条经验

原则 说明
第一屏说清楚 别人只看 5 秒就决定要不要继续，项目是干什么的放最上面
图比字快 一张截图/演示 GIF 胜过三段描述
复制就能跑 安装命令要能直接粘贴执行，别写占位符
别太长 详细内容丢 docs/，README 保持精炼
跟上更新 版本变了记得同步 README 里的版本号和徽章

Git 提交信息也常写 Markdown

Commit message、PR 描述、Issue 评论都支持 Markdown：

fix: 修复比赛结束后计分未重置的问题

- 在 endGame() 里补上 resetScore()
- 影响范围：bst_tdm 玩法

Closes #42

本章练习

  1. 给你的任意一个项目写一份 README（含特性列表 + 安装命令）。
  2. 加三个 shields.io 徽章。
  3. 手写一个目录，并验证锚点跳转正确。

最后一章：速查表，随时查。