如何编写优雅而有意义的 .md 文件编写出色文件的技巧（以及它为何重要）

作为开发人员，我们精通代码和项目中的所有细节。但是，我们中的一些人（包括我）缺乏加入在线社区的软技能。

开发人员会花一个小时来调整一个按钮，但不会花15分钟来完善项目的文档。

我希望你们大多数人已经知道文件是什么以及它是用来做什么的，但对于新手，我会尽可能详细地解释它是什么。

什么是 .md？

该文件（字面意思是“自述”）是您在开始新项目时应该阅读的第一个文件。它包含大量有关项目的有用信息，是项目的手册。它是人们在 Git 或任何 Git 托管网站上打开您的存储库时看到的第一个文件。

您可以清楚地看到.md 文件位于存储库的根目录中，并且它会自动显示在上面的项目目录中。

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

下面是一个文件示例以及它将如何在 上呈现。这里，我使用预览，它显示文件呈现后的预览。

如果你想了解有关该语言的更多信息，这里有一个官方的备忘单。

为什么要花时间在这上面？

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

既然您已经意识到了问题，让我们看看如何解决它。

为您的组件生成文档

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

在您的团队中共享可重复使用的代码组件 Bit 描述您的项目！（技巧就是说得简单一点）

为您的项目写一个好的描述。建议您可以将描述格式化为以下主题：

让我们深入了解技术细节

我将以我的这个项目作为参考，我认为这是我写过甚至见过的最漂亮的文件之一。你可以在这里查看其 .md 文件的代码：-lad/

使用铅笔图标显示代码：

1. 请添加图片！

您可能对您的项目有着美好的记忆，但您的读者可能想要一些项目实际运行的图片。

例如，我制作了一个扑克牌项目，并在文件中添加了一张图片作为描述。

现在您可能想添加一个视频来描述您的项目。就像我在我的项目中所做的那样。但是，不允许将视频添加到文件。那么...该怎么办？

…我们可以使用 GIF

GIF也是一种图片，允许我们将它放在文件中。

2.荣誉勋章

文件上的徽章可让访问者感受到真实性。您可以从以下 URL 为您的存储库设置自定义或常规盾牌（徽章）：

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

3.添加在线演示

如果可以的话，托管你的项目并启动一个可运行的演示。之后，将此演示链接到文件。你不知道会有多少人来“玩”你的项目。此外，招聘人员只喜欢可以在线演示的项目。这表明你的项目不仅仅是放在页面上的代码，而是实际在运行的业务。

您可以在内容中使用超链接。例如，在标题图片下方提供现场演示的链接。

4. 使用代码样式

提供了一个选项来将文本呈现为代码样式。因此，您不应以纯文本形式编写代码，而应使用 `（反引号）将代码包装为代码样式，例如 var a = 1;。

它还提供了指定代码所用语言的选项，以便可以使用特定的文本突出显示来提高代码的可读性。你只需要像这样使用它：

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

{```} — 三重反引号用于多行代码，还允许您指定代码块的语言。

使用代码高亮：

没有代码高亮显示：

5.使用 HTML

是的，您可以在 中使用 HTML。虽然并非所有 HTML 功能都可以使用，但大多数功能都可以。虽然最好只包含语法，但某些功能（例如居中图像和居中文本）只能通过 HTML 实现。

6. 发挥创造力

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

仅供参考，以下是随附的一些物品：