Skip to content

04-what-is-readme.md

Latest commit

 

History

History
134 lines (81 loc) · 2.56 KB

04-what-is-readme.md

File metadata and controls

134 lines (81 loc) · 2.56 KB
Raw

04. README.md 是什么？为什么它很重要？

学习目标

读完本章，你应该能够：

  • 理解 README.md 的作用
  • 知道一个基础 README 应该包含哪些内容
  • 修改并提交自己的 README

适合人群

适合已经创建仓库，但不知道首页应该写什么的新手。

README.md 是什么

README.md 是 GitHub 仓库首页默认展示的说明文件。

它通常用 Markdown 编写，所以文件名是 README.md。

生活化比喻：

README 像一本书的封面、简介和目录。别人打开你的仓库，第一眼通常不是看代码，而是看 README。

README 为什么重要

一个好的 README 可以回答这些问题：

  • 这个项目是做什么的？
  • 它适合谁？
  • 怎么开始使用？
  • 有哪些主要功能？
  • 遇到问题怎么办？
  • 如何参与贡献？
  • 使用时要遵守什么 License？

如果没有 README，别人可能不知道你的项目价值，也不知道如何使用。

一个基础 README 模板

# 项目名称

一句话介绍这个项目。

## 项目简介

用几句话说明这个项目解决什么问题。

## 如何使用

1. 第一步
2. 第二步
3. 第三步

## 示例

这里放截图、代码示例或使用说明。

## 常见问题

记录新手容易遇到的问题。

## License

本项目使用 MIT License。

实际操作步骤：在 GitHub 网页上修改 README

  1. 打开你的仓库
  2. 点击 README.md
  3. 点击右上角铅笔图标
  4. 修改 README 内容
  5. 滚动到页面底部
  6. 在 commit message 中写：
Improve README
  1. 点击 Commit changes

小练习

给你的 hello-github 仓库写一个 README，至少包含：

  • 项目名称
  • 一句话介绍
  • 我正在学习什么
  • 下一步计划

示例：

# Hello GitHub

这是我的第一个 GitHub 练习仓库。

## 我正在学习

- 创建仓库
- 修改 README
- 提交 commit

## 下一步计划

我准备学习 Markdown 和 Pull Request。

常见错误提醒

错误 1：README 只写项目名。

项目名不等于项目说明。至少写清楚项目用途和使用方式。

错误 2：把所有内容堆在一起。

使用标题、列表和表格，让 README 更容易阅读。

错误 3：README 内容和项目实际情况不一致。

如果项目还没完成，不要写成已经完成。可以写“计划中”。

错误 4：忘记提交修改。

在 GitHub 网页编辑文件后，需要点击 Commit changes 才会保存到仓库。

延伸阅读

  • Make a README
  • GitHub Flavored Markdown
  • Awesome README