1. Dotnet9首页
  2. 更多分享
  3. 最佳实践
  4. 技术分享

如何编写 GitHub 仓库文档?

如何编写 GitHub 仓库文档?

给 GitHub 仓库写文档好处多多。如果你在找工作,你可以把你的项目地址发给 HR 团队,他们就能好地知道你的项目是干什么的。此外,文档也可以帮助其他人给你的项目提交贡献。在仓库里添加文档其实很简单,在仓库的根目录下创建 README.md 文件就行了。

README.md 会作为 markdown 文件被解析,我之前还写过一篇 Markdown 入门指南 [1],详细介绍了 Markdown 的用法。Markdown 不能完全控制页面样式,比如将图像居中、调整宽度和高度等。此外,你还可以在 README .md 里使用 HTML(内联 CSS 样式),例如:

<div align="center">
 <br>
 <img alt="logo" src="/image.png" width="200px">
 <h1>Your headline</h1>
</div>
<br>

README.md 文件要包含哪些信息?

这完全取决于你的项目,关乎于你介绍项目的方式。但我下面列出了几个点,你可以在你的文档中作参考:

  • 包含图片或徽标
  • 介绍如何运行
  • 入门指南
  • 运行环境
  • 如何贡献(通过编写 CONTRIBUTING.md)
  • 关于团队的介绍
  • 相关项目
  • 贡献者、支持者或赞助者
  • 许可证

添加目录(TOC)

如果你的 README.md 内容很长,那么最好给它加个目录,比如:

- [How it Works](#how-it-works)
- [Getting started](#get-started)
- [Contributing](#contributing)
- [Core team](#core-team)
- [License](#license)

点击目录中的链接,页面就会滚动到对应的标题下。

## How it Works
your explanation...

## Getting started](#get-started)
your explanation...

## [Contributing](#contributing)
your explanation...

## [Core team](#core-team)
your explanation...

## [License](#license)
your explanation...

添加 Badge/Shields

Badge/Shields 会让你的文档变得漂亮,它们是 SVG 和栅格格式的小方块,可以包含在 GitHub 自述文件(README.md)或其他任意网页上。你可以通过它们快速了解项目的状态,比如代码大小、提交状态或部署情况等。下面是一个例子。

如何编写 GitHub 仓库文档?

如何添加这些 Badges

如果你使用 Netlify 部署代码,你可以在他们家的 dashboard 页面上获得 Badge,这个 Badge 可以展示代码的部署状态。你也可以在 shields.io 或 codetriage.com 上找到一些漂亮的 Badge 资源,然后把它们添加到 README.md 里:

<img src="https://img.shields.io/github/languages/code-size/taimoorsattar7/underlinejobs" alt="GitHub Code Size in Bytes">

进一步改进文档结构

README.md 文件描述了你项目的基本信息。如果你的信息很长,你可以把部分内容从自述文件里拿出来,放在一些专门的文件中,比如 CODE_OF_CONDUCT.mdCONTRIBUTING.md,分别包含项目的行为守则和介绍如何为项目组贡献等,这样一来文档就更有条理了。

你文档的语法要正确,以便其他人能正确理解。你可以用 hemingwayapp(http://www.hemingwayapp.com/)或 grammarly(https://www.grammarly.com/)之类的工具检查语法错误。

如果你喜欢这篇文章,你可以常来我推特坐坐,我的推特是 @taimoorsattar7。

原题:How to Document your repository in GitHub?

原文:https://dev.to/taimoorsattar7/how-to-document-your-repository-in-github-59f2

作者:Taimoor Sattar

[1] Markdown 入门指南:https://taimoorsattar.dev/blogs/markdown-guide-getting-started-20200304

如何编写 GitHub 仓库文档?

原文出处:微信公众号【AlexLEWIS NCC开源社区】

原文链接:https://mp.weixin.qq.com/s/UE0vEjzMutvCuqXG_bmWYA

本文观点不代表Dotnet9立场,转载请联系原作者。

发表评论

登录后才能评论