编写开源项目README文件

编写开源项目的README文件

1. 说明

每一个代码托管平台，当创建好仓库，如果上传代码，目录下有README文件，里面的内容就会显示在项目下面，主要是写一些项目的说明，安装，使用等等。但是具体有哪些内容呢？著名的开源项目，还都很大好看的图标，比如build pass等等，这些都是怎么弄的？带的这些疑问，利用这次hexo静态网站的部署，学习一下，也好让自己的项目看起来更像专业的开源项目。

主要的代码托管平台

GitHub

GitLab

CODING

Gitee

CODE-aliyun

那些图标，可以通过这个网站生成

https://shields.io/

2. 开始编写

主要目录结构

## 国际化 
 - 【一般最外层写英文的，然后可以链接到中文日文等等不同语言版本的README】
## 项目背景 
 - 【主要是描述一下项目】
 - 用什么语言？
 - 什么用途？
 - 最新版本是什么？
 - 构建/测试结果等信息，主要是travis，coverage，npm等等Badge，就是那些图标 shield.io
 - DEMO演示地址或者官网是什么？
 - 【还可以放特性的列表】
## 安装及快速开始
 - 【告诉用户怎么用，很重要，要清晰干净，按步骤要完全可复现，降低用户使用难度】
 - 可以放一些动图
## 项目具体介绍及相关项目
 - 【可以放项目的整体框架图】
 - 如果有相关的类似或者参考项目，也可以在这里提一下
## 主要项目负责人
 - 【介绍负责人，可以直接艾特标注】
## 参与贡献方式
 - 【填写怎么样参与到项目，比如提issue，提pr等】
## 版本更新日志
 - 【安版本更新日志填写】
## 待办事宜
 - 【如果有后续计划开发项，可以在这里列出来，也好让大家有个期待】
## 鸣谢和协议
 - 【主要可以放比如打赏二维码等，鸣谢主要贡献】
 - 【开源协议许可】

Badge图标怎么加

其他都是项目具体相关的，只要按照正常逻辑写即可，主要看看travis/coverage/npm等图标，这样看起来更加有安全感。

Github徽标官方网站：

https://shields.io/

添加动态徽标

动态徽标是如果项目状态发生变化，会自动更新状态的徽标，它就是当前项目的真是状态。

常用的有：

• 持续集成状态
• 项目版本信息
• 代码测试覆盖率
• 项目下载量
• 贡献者统计等

我们以Travis CI持续集成状态为例。具体涉及的搭建方法使用TravisCI持续集成

1. 进入Travis CI, 到构建过的项目中，可以看到最上面有build passing或者build failing徽标

2. 点击它，在弹出来的对话框中，有各种语言的徽章地址。

3. 根据自己需要进行选择， 我这里选择了Makdown格式

   [![Build Status](https://travis-ci.com/lmwings/hexo-source.svg?token=yoTY1CXWQpQKsuGEijQk&branch=master)](https://travis-ci.com/lmwings/hexo-source)

4. 复制到README中，然后git push到仓库，过一会可以看到这个徽标。

5. 这个是动态加载的，所以需要过一会才能刷新。

自定义徽标

通过shields.io网站，可以自定义徽标

徽标图标格式

https://img.shields.io/badge/{徽标标题}-{徽标内容}-{徽标颜色}.svg

带链接的微标

[![](https://img.shields.io/badge/{徽标标题}-{徽标内容}-{徽标颜色}.svg)]({linkUrl})

变量说明

• 徽标标题：徽标左边的文字

• 徽标内容： 徽标右边的文字

• 徽标颜色： 徽标右边的背景颜色， 可以是颜色的16进制值，也可以是颜色英文。

  （brightgreen/green/yellowgreen/yellow/orange/red/blue/lightgrey/success/important/critical/informational/inactive/blueviolet/ff69b4/9cf）

变量之间用-连接。按上面规则体会为需要的内容即可自定义一个徽标

进阶用法

除了上面的用法，网站还提供了query string来控制徽标样式。使用方法和浏览器URL的query string一致

徽标图标地址？{参数名}={参数值}， 多个参数用&连接

https://img.shields.io/badge/{徽标标题}-{徽标内容}-{徽标颜色}.svg?{参数名1}={参数值1}&{参数名2}={参数值2}

常用的query string参数有：

• style: 控制徽标主题样式， 可以为plastic|flat|flat-square|social
• label: 用来强行覆盖原有徽标的标题文字
• colorA: 控制左半部分背景颜色，只能用16进制颜色值作为参数，不能用颜色英文
• colorB: 控制右半边部分背景颜色。

举例

flat扁平化效果

![](https://img.shields.io/badge/blog-@champyin-yellow.svg?style=flat)