很棒的自述文件的提示(以及为什么这很重要)

作为开发人员,我们非常擅长代码和项目的所有细节。但是我们中的一些人(包括我在内)即使在在线社区中也缺乏软技能。

开发人员会花费一个小时来调整单个按钮的内边距和边距。但不会花 15 分钟来阅读项目描述自述文件。

我希望你们中的大多数人已经知道什么是 readme.md 文件以及它的用途。但是对于这里的新手,我将尝试解释它到底是什么。

什么是 Readme.md?

README(顾名思义:“read me”)是开始一个新项目时应该阅读的第一个文件。它是关于项目的一组有用信息和一种手册。这是当有人打开您的存储库时,Github 或任何 Git 托管站点将显示的第一个文件。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--7ZktNpFg--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to- uploads.s3.amazonaws.com/uploads/articles/jwj38ggnwcjb1bh91tpp.png)

正如您在这里可以清楚地看到的 Readme.md 文件位于存储库的根目录中,并由 github 自动显示在项目目录下方。

而.md的扩展来自一个词:markdown。它是一种用于文本格式化的标记语言。就像 HTML 一样,它是一种标记语言,可以使我们的文档看起来像。

这是一个 Markdown 文件的示例,以及它实际上是如何在 github 上呈现的。我在这里使用 VSCode 进行预览,它同时显示 Markdown 文件的预览。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--3VAcq7gm--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to- uploads.s3.amazonaws.com/uploads/articles/4aydo7k98iix3a01v9s7.png)

这是官方 _ Github 备忘单 _ 用于 Markdown 格式,如果您需要深入了解该语言。

为什么要花时间阅读自述文件?

现在让我们谈谈生意。你花了几个小时在一个项目上,你在 GitHub 上公开了它,你希望人们/招聘人员/同事/(例如?)看到你的项目。你真的认为他们会进入root/src/app/main.js来查看你的美丽逻辑吗?严重地?

既然我已经引起了你的注意,让我们看看如何解决这个问题。

描述你的项目! (TL;DR)

为您的项目写一个好的描述。仅作为指导,您可以将您的描述格式化为以下主题:-

• 标题(如果可能,也可以使用标题图像......如果您不是平面设计师,请在 canva.com 上编辑它们。)

• 描述(用文字和图像描述)

• 演示(图片、视频链接、现场演示链接)

• 使用的技术

• 项目的特殊陷阱(您面临的问题,项目的独特元素)

• 项目的技术描述,如安装、设置、如何贡献。

让我们深入了解技术细节

我将使用我的这个项目作为参考,我认为它是我编写甚至遇到的最漂亮的自述文件之一。您可以在此处查看 Readme.md 文件的代码:-

沉默的小伙子/VueSolitaire

单人纸牌

使用铅笔图标显示降价代码:-

[](https://res.cloudinary.com/practicaldev/image/fetch/s--aFicnYCw--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to- uploads.s3.amazonaws.com/uploads/articles/tcqw1fb4ig7i78yjsxn7.png)

1\。添加图片!请!

您可能有过目不忘的记忆,但您的读者可能需要一些项目演示的实际照片。

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

[](https://res.cloudinary.com/practicaldev/image/fetch/s--xQ63WC7m--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to- uploads.s3.amazonaws.com/uploads/articles/qnxazcdujqhecrbh9g7x.png)

现在您可能还想为您的项目添加视频描述。就像我一样。但是......Github 不允许你在自述文件中添加视频......所以......那又怎样?

...我们使用 GIFS

[](https://res.cloudinary.com/practicaldev/image/fetch/s--8efFifVq--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_66%2Cw_880/https://dev-to- uploads.s3.amazonaws.com/uploads/articles/kt64pi0hub69ffnjrl1i.gif)

哈哈......知道了 Github。

Gif 属于图像类别,github 允许您将它们放在自述文件中。

2\。荣誉徽章

您的自述文件上的徽章会给观众一些真实的感觉。您可以从以下位置为您的存储库获取自定义/常规使用的盾牌(徽章):-https://shields.io

[](https://res.cloudinary.com/practicaldev/image/fetch/s--I3Dz5QCD--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads .s3.amazonaws.com/uploads/articles/7t95dwhnv217mukjn2yh.png)

您还可以获得个性化的盾牌,例如 repo 上的星数和代码百分比指标。

3\。添加现场演示

如果可能,托管您的项目并设置运行演示。在那之后 将此演示链接到您的自述文件。 您不知道最终有多少人可能会玩弄您的项目。招聘人员只是喜欢现场项目。 这表明您的项目不仅仅是放在 github 上的代码转储,而且您实际上是在做生意。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--CgMjfAVO--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to- uploads.s3.amazonaws.com/uploads/articles/32fmrpsdelwdzwir3cav.png)

您可以在自述文件中使用超链接。因此,请在标题 Image 下方提供一个 Live Demo 链接。

4\。使用代码格式

Markdown 为您提供了将文本格式化为代码的选项。所以不要将代码写成纯文本,而是使用(Tilde) to wrap the code inside code formatting as such-var a u003d 1;`

Github 还为您提供了 specify 编写代码 的语言的选项,以便它可以使用特定的文本突出显示来使代码更具可读性。为此使用

_ @182@183@184 _

{ @185` }- 三重波浪号用于多行代码,它还允许您指定代码块的语言。

带有语言突出显示:-

[](https://res.cloudinary.com/practicaldev/image/fetch/s--UqEuR_Ux--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads .s3.amazonaws.com/uploads/articles/5e8xwjzjeg7vsy4wvy18.png)

没有语言突出显示:-

[](https://res.cloudinary.com/practicaldev/image/fetch/s--NGkrlG5w--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads .s3.amazonaws.com/uploads/articles/2tf926ne7mjxxlkwo6ql.png)

5\。使用 HTML

是的,你可以在里面使用 HTML。虽然不是所有的功能。但是大部分。尽管您应该只坚持使用降价,但是某些功能(例如在自述文件中居中图像和文本)只能通过 HTML 实现。

[](https://res.cloudinary.com/practicaldev/image/fetch/s--NGkrlG5w--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads .s3.amazonaws.com/uploads/articles/2tf926ne7mjxxlkwo6ql.png)

6\。有创意

现在剩下的就交给你了,每个项目都需要不同的 Readme.md 和不同类型的描述。但请记住,您花在自述文件上的 15 到 20 分钟最终可能会对您的 github 个人资料的访问者产生巨大影响。

仅供参考,这里有一些带有自述文件的项目

沉默的小伙子/Vue2BaremetricsCalendar

Vue Baremetrics 日历

[](https ://camo.githubusercontent.com/5dfc7586c358ea5d1b3f64dc7066ff68a8552c066afc173ddc38fc8f8fe8fe9b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7675652d322e362e31302d677265656e2e737667) [](https://camo.githubuser content.com/378c5bb3161f389c2c85a9eb340f6fc8579895f3128632e875aea9b0bb125b5/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f73696c656e742d6c61642f56756532426172656d65747269637343616c656e6461722e7376673f7374796c653d666c6174)

由 Baremetrics 团队制作的漂亮日期范围选择器的 Vue.js 包装器。

---

Vue-Baremetrics 日期范围选择器是一种简化的解决方案,用于从单个日历视图中选择日期范围和单个日期。经过改良的简约重新设计。

Divyansh Tripathi 为 Vue.js 重新设计和包装

查看演示

NPM 包

安装

npm i --save vue2-baremetrics-calendar

用途

全球使用情况

通过 Vue.use() 方法进行全局注册。

// main.js

从“视图”导入视图;

从“./App.vue”导入应用程序;

从“./router”导入路由器;

// 导入插件

从“vue2-baremetrics-calendar”导入日历;

Vue.config.productionTip \u003d false;

// 使用插件

Vue.use(日历);

新视图({

路由器,

渲染:h \u003d> h(App)

}).$mount("#app");

进入全屏模式 退出全屏模式

注册后,您可以在其默认设置中使用该组件,如...

在 GitHub 上查看

---

进一步阅读

如何让你的简历成为 NPM 包

Javascript 中 this 的范围

A 到 Z 的 NPM 包

💌 如果您想在收件箱中收到更多教程,您可以在此处注册时事通讯。