实战场景

Markdown 写 GitHub README 与项目文档:从入门到规范

GitHub 全站用 Markdown,而 README.md 是别人认识你项目的第一眼。这篇讲清它该写什么、GitHub 的专属语法,以及一份不丢人的文档清单。

一、README 到底要写什么

一份合格的 README 通常按这个顺序:

  • 一句话简介:这项目是干嘛的,解决什么问题。
  • 截图 / 演示:一张图顶千句话。
  • 安装与运行:复制即用的命令。
  • 用法示例:最小可跑的例子。
  • 特性列表:用任务清单勾出亮点。
  • 贡献方式与许可证:欢迎谁、怎么参与、能怎么用。

黄金法则:把“别人第一次打开这个项目会问什么”逐条回答掉,README 就成功了八成。

二、GitHub 专属 Markdown 语法

GitHub 在标准 Markdown 上扩展了一些好用的东西:

效果写法
任务清单- [x] 已完成 · - [ ] 待办(方框可勾选)
提及人或仓库@用户名 · owner/repo
表情图标:rocket: 显示 🚀,:warning: 显示 ⚠️
代码块(带高亮)```python ... ```(见 代码块与高亮)
自动链接直接写网址就会变成链接

还有折叠块,用来收起大段日志或长输出:

<details>
<summary>点击展开安装日志</summary>

这里放很长的内容……
</details>

三、目录锚点与跳转

长 README 顶部常放一个目录,用标题自动生成的锚点跳转:

- [安装](#安装)
- [用法](#用法)

GitHub 会把 ## 安装 自动变成 #安装 锚点(中文标题同样适用,空格转成 -)。点一下就跳到对应章节。

四、写好文档的检查清单

  1. 标题层级清晰,从 # 到 ### 不跳级。
  2. 命令块都标注了语言,方便高亮和复制。
  3. 图片用相对路径或图床,仓库里能正常显示。
  4. 有“如何运行”的最小示例,新手照做能跑通。
  5. 许可证和贡献指引齐全。

五、多语言与 CONTRIBUTING

面向国际用户时,可加 README.en.md 或建 docs/ 目录分语言存放。配套放一份 CONTRIBUTING.md 说明“怎么提 Issue、怎么发 PR”,能大幅减少沟通成本。

这些 .md 文件在 GitHub 上都是实时渲染的 Markdown——本地用 365Lab 在线编辑器 先写好预览,再提交,排版心里有数。

六、常见问题

Q:README 不写行不行?
A:能跑,但别人一眼看不出项目是啥,下载量和贡献都会少。花 10 分钟写简介 + 安装 + 用法,回报很高。

Q:emoji 在 README 里显示成代码了?
A:用 GitHub 支持的短代码如 :sparkles: 才会渲染成图标;自己打的文字 emoji 直接显示即可。

Q:本地预览和 GitHub 不一致?
A:GitHub 对部分扩展语法(如某些 HTML 标签)有限制。提交前在仓库里看一眼渲染结果最稳妥。

Q:想系统学 Markdown 基础?
A:先看 Markdown 语法速查表,再回来写 README 会顺很多。


写代码块见 Markdown 代码块与语法高亮;挑顺手工具见 免费 Markdown 编辑器怎么选。想把仓库变成公开站点,看 Markdown + GitHub Pages 免费建站。

边写 README 边看预览

免注册、实时预览、内容本地保存。把 README 粘进 365Lab,排版确认无误再提交。

免费开始写作 →