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

时间 2020-02-08

标签如何写出优雅且有意义 readme.md readme 繁體版

原文原文链接

原文地址：How to Write Beautiful and Meaningful README.md

原文做者：Divyansh Tripathi [SilentLad]

译文出自：掘金翻译计划

本文永久连接：github.com/xitu/gold-m…

译者：Jessica

校对者：Vito,Hsu Zilin

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

写出一个超棒的 Readme 文件的小技巧（以及为何 README 很重要）

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

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

我但愿大家大多数人已经知道 README 文件是什么，它是用来作什么的。可是对于萌新来讲，我仍是会尽量地来解释它究竟是什么。android

什么是 Readme.md？

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

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

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

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

若是你想要深刻了解这门语言，这里有一个官方的 Github Markdown 备忘录。markdown

为何要在 Readme 上花时间？

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

如今你已经意识到这个问题了，让咱们看看如何解决这个问题。app

为你的组件生成文档

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

团队共享可重用的代码组件 · Bit

描述你的项目！（技巧说白了就是）

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

标题（若是能够的话，提供标题图像。若是你不是平面设计师，请在 canva.com 上进行编辑）；
描述（用文字和图片来描述）；
Demo（图片、视频连接、在线演示 Demo 连接)；
技术栈；
你项目中须要注意的几个陷阱（你遇到的坑、项目中的独特元素）；
项目的技术说明，如：安装、启动、如何贡献；

让咱们深刻探讨技术细节

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

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

1. 添加图片！拜托!

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

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

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

…咱们可使用 GIF

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

2. 荣誉勋章

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

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

3. 增长一个在线演示 Demo

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

您能够在 Readme 中使用超连接。好比在标题图片下面提供一个在线演示连接。

4. 使用代码样式

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

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

```{代码语言}<space>{代码块}```

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

使用代码高亮：

不使用代码高亮：

5. 使用 HTML

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

6. 有创造性

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

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

了解更多

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

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