Softonic

README 生成器

步 1 / 4 README.md
下一步

空仓库会给人留下糟糕的第一印象。填写项目名称、一句话标语、功能列表、安装命令、快速开始代码、作者和许可证，这个生成器就会输出一份干净的 Markdown README，具有正确的标题层级和围栏代码块：也就是 GitHub 在你的项目页面上呈现的那些部分。复制它，保存为仓库根目录下的 README.md，然后推送。各部分的标题使用英文书写，这是开源 README 近乎通用的惯例；而你自己的文字则完全按你输入的样子显示，可用任何语言。

如何撰写 README

  1. 1

    添加基本信息

    项目名称、可选的仓库 URL 和一句话标语。名称会成为 `#` 标题；标语会成为其下方的引用块。

  2. 2

    列出功能和快速开始

    每行一个功能（每一个都会变成一个列表项），再加上一段简短的快速开始代码，它会被包进围栏代码块。

  3. 3

    安装、许可证和作者

    安装命令会放进「安装」下的 `bash` 代码块；添加许可证（MIT、Apache-2.0…）和一行可选的作者信息。

  4. 4

    复制 Markdown

    点击复制，将输出以 `README.md` 为文件名粘贴到仓库根目录。推送后，渲染版本就会显示在项目页面上。

一份优秀的 README 应包含哪些内容

GitHub 官方风格指南与广泛使用的 standard-readme 规范在排列顺序上是一致的。把便于快速浏览的部分放在顶部：访客打开你的仓库后，20 秒内就会决定是否继续读下去。

部分 位置 用途
标题 + 标语 第 1–2 行 # Project 后接一句说明其用途的话
徽章 第 3–5 行 CI 状态、npm 版本、许可证、覆盖率
安装 首屏以上 一条可直接复制的命令
用法 首屏以上 能产生输出的最小可用代码片段
API / 选项 中间 标志、配置键或端点的表格
贡献 接近结尾 指向 CONTRIBUTING.md、行为准则、PR 约定的链接
许可证 最后 SPDX 标识符及指向 LICENSE 的链接

真正有帮助的徽章

Shields.io 的 URL 遵循一个可预测的模式：https://img.shields.io/badge/<label>-<message>-<color>.svg。有用的实时徽章指向构建状态、软件包版本和下载次数，而不是虚荣指标。通常四个徽章就够了；再多就是噪音。

常见的 README 错误

  • 「安装」第一行没有安装命令。 读者会扫读寻找 npm install 或 pip install；如果把它藏在正文里，他们就会离开。
  • 3 MB 的截图。 将其缩放到 800 像素宽并压缩；GitHub 无论如何都会提供它们，但移动端读者要为带宽买单。
  • 过时的徽章。 红色的 CI 徽章会告诉访客项目已损坏。要么修好 CI，要么移除该徽章。
  • 缺少许可证。 没有许可证，你的代码默认是「保留所有权利」，企业无法使用它。

常见问题

是的。围栏代码块、无序列表和 ATX 风格的标题（# 前缀）都能在 GitHub、GitLab 和 Bitbucket 上原样呈现。安装命令会被标记为 bash 代码块；快速开始代码块则不加标签，方便你自己指定语言。

对于大多数生态系统，用 README.md。仅当你发布的 Python 包的文档托管在 Read the Docs 上，并希望 Sphinx 把该文件复用为着陆页时，才使用 .rst。

当你提供仓库 URL 时，生成器会添加一个静态的许可证徽章（https://img.shields.io/badge/license-<type>-blue.svg）。若需要实时徽章（构建状态、版本、下载量），请自行复制一个 shields.io 的 URL 模板并粘贴到输出中。

不会。README 由表单里的值组装而成，不保存任何内容。关闭标签页，数据就消失了。

相关工具

ASCII 表参考

完整 ASCII 表，覆盖 0 到 127；列出每个代码的十进制、十六进制、八进制、二进制值和 HTML 数字字符引用写法，包括 NUL、LF、DEL。

HTML 字符参考

可搜索的 HTML 实体列表，含命名代码与数值代码，并支持一键复制特殊字符和符号。

键盘快捷键参考

搜索 macOS、Windows 和 Linux 上 VS Code、Chrome 以及使用 GNU Readline 的 Bash 的文档默认快捷键。

邮箱验证器

验证邮箱地址：RFC 5322 语法检查、实时 MX 记录查询，并显示本地部分、域名和长度详情。不会发送任何邮件。

EditorConfig 生成器

按你的缩进、换行符和字符集规则生成 .editorconfig，再为仓库里的每种语言加上正确的区块：Python、Go、YAML、Makefile 等等。

证书解码器

粘贴一张 X.509 PEM 证书，并查看解码后的字段：主体、颁发者、序列号、签名算法、有效期及主体备用名称（SAN）。

此工具还提供其他语言版本