[译] 如何写出优雅且有意义的 README.md

作为开发人员，我们对代码以及项目中的所有细节都信手拈来。然而我们中的一些人（包括我在内）就连在网络社区中的软技能都缺乏。

一个开发人员会花一个小时来调整一个按钮的 padding 和 margin。却不会抽出 15 分钟的来完善项目的 Readme 文件。

我希望你们大多数人已经知道 README 文件是什么，它是用来做什么的。但是对于萌新来说，我还是会尽可能地来解释它到底是什么。

README（顾名思义：“read me“）是启动新项目时应该阅读的第一个文件。它既包含了一系列关于项目的有用信息又是一个项目的手册。它是别人在 Github 或任何 Git 托管网站点，打开你仓库时看到的第一个文件。

你可以清楚地看到，Readme.md 文件位于仓库的根目录中，在 Github 上的项目目录下它会自动显示。

.md 这个文件后缀名来自于单词：markdown。它是一种用于文本格式化的标记语言。就像 HTML 一样，可以优雅地展示我们的文档。

下面是一个 markdown 文件的例子，以及它在 Github 上会如何渲染。这里，我使用 VSCode 预览，它可以同时显示 markdown 文件渲染后的预览。

如果你想要深入了解这门语言，这里有一个官方的 Github Markdown 备忘录。

现在我们谈正事吧。你花了几个小时在一个项目上，你在 GitHub 上发布了它，并且你希望游客、招聘人员、同事、（或者前任？）看到这个项目。你真的认为他们会进入 root/src/app/main.js 来查看你的代码的逻辑吗？真的会吗？

现在你已经意识到这个问题了，让我们看看如何解决这个问题。

除了项目的 Readme 之外，记录组件对于构建易于理解的代码库也很重要。这使得重用组件和维护代码变得更加容易。比如，使用像Bit (Github) 这样的工具，来为在 bit.dev 上共享的组件自动生成文档。（译者注：这里是作者在打广告）

为你的项目写一个好的描述。仅出于建议，您可以将描述的格式设置为以下主题：

我将使用我的这个项目作为参考，我认为它是我写过甚至遇到过的的最漂亮的 Readme 文件之一。你可以在这里查看它的 Readme.md 文件的代码: silent-lad/VueSolitaire

使用铅笔图标来显示 markdown 代码：

你可能对你的项目记忆犹新，但是你的读者可能需要一些项目演示的实际图片。

例如，我制作了一个纸牌项目，并在 Readme 文件中添加了图像作为描述。

现在你可能想要添加一个视频描述您的项目。就像我项目里那样。但是，Github 不允许在 Readme 文件中添加视频。那…该怎么办呢？

GIF 也是一种图片，Github 支持我们将它放在 Readme 文件中。

Readme 文件上的徽章会使游客有一定的真实感。您可以从下面的网址，为您的仓库设置自定义或者常规使用的盾牌（徽章）：https://shields.io

你还可以设置个性化的盾牌，如仓库的的星星数量和代码百分比指标。

如果可以的话，请托管你的项目，并开启一个正在运行的演示 demo。之后，将这个演示链接到 Readme 文件。你也不知道可能会有多少人来“把玩”你的项目。另外，招聘人员只喜欢可以在线演示的项目。它表明你的项目不仅仅是放在 Github 上的代码，而是确实跑起来业务。

您可以在 Readme 中使用超链接。比如在标题图片下面提供一个在线演示链接。

Markdown 提供了将文本渲染为代码样式的选项。因此，不要以纯文本形式编写代码，应该使用 `（反单引号）将代码包裹在代码样式中，例如 var a = 1;。

Github还提供了指定代码编写语言的选项，这样它就可以使用特定的文本高亮来提高代码的可读性。你只需要这样使用：

```{代码语言}{代码块}```

{ ``` } —— 三个反单引号用于多行代码，同时它还允许你指定代码块的语言。

使用代码高亮：

不使用代码高亮：

是的，你可以在 Readme 里使用 HTML。尽管并不是 HTML 里所有的功能都可以使用，但大部分可以。虽然你最好是只包含 markdown 的语法，但一些功能，如居中图像和居中文本是只能用 HTML 实现的。

剩下的就交给你了，每个项目都需要不同的 Readme.md 文件和不同类型的描述。但是请记住，你在 Readme 文件上花费的 15 —— 20 分钟可能会对你 Github 的访问者数量产生巨大的影响。

仅供参考，这里有一些带 Readme 的项目：

如果发现译文存在错误或其他需要改进的地方，欢迎到 掘金翻译计划 对译文进行修改并 PR，也可获得相应奖励积分。文章开头的 本文永久链接 即为本文在 GitHub 上的 MarkDown 链接。

掘金翻译计划 是一个翻译优质互联网技术文章的社区，文章来源为 掘金 上的英文分享文章。内容覆盖 Android、iOS、前端、后端、区块链、产品、设计、人工智能等领域，想要查看更多优质译文请持续关注 掘金翻译计划、官方微博、知乎专栏。