推荐一个自用的开源项目 README 模板

内容目录

点我打开/关闭目录列表

1. README 部分
- 1.1 简介
- 1.2 效果展示
2. Issue/PR 模板部分
- 2.1 简介
- 2.2 效果展示
3. Github Actions CI 部分
- 3.1 简介
- 3.2 效果展示

声明：我是「米司特包」，本篇文章首发于「米司博客」，其他平台为同步推送，由于网站后续会升级重构，很有可能导致文章路径规则变动，所以就没贴详细链接，可以进入博客根据标签查找 🔍。

本来决定是要写一篇《如何写好开源项目的 README》的文章的，后来根据自己的一些项目的情况，就把 Issue、PR 和 CI 部分也加了进来，各位看官姥爷可以根据自己的需要查看。

由于作者本人也是一个常逛 Github 的人，偶尔也会在上面找一些别人实现好的轮子，在这中间发现有的一些项目质量很好，但是有的没有提供文档或者 README 写的很简陋，使用者要用的话，就需要自己去阅读源码，才知道怎么使用，我想这可能是很多技术人员的通病——不喜欢写文档，因为我自己是个强迫症，我自己的项目一般都会有 README 或者专门的文档，因为这个原因，我新建了一个 Github 仓库模板库，里面提供了基础的 README 要素和多语言范本，同时也提供了 Issue 和 PR 模板，以及基于 Github Actions 的 CI 脚本（目前只有 NodeJS 项目和 Hugo 项目的示例）。基本上将大部分开源项目需要的东西包含了进去。

代码仓库：

https://github.com/misitebao/standard-repository（Github）
https://gitee.com/misitebao/standard-repository（Gitee）

也可以直接点击链接在线上 VSCode 环境预览：VSCode 在线预览

1. README 部分

1.1 简介

README 是一个项目的简介，同时也是 Github 上别人访问你的项目第一眼要看的东西，所以写好 README 不仅能为项目加分，同时也显示出你的专业，让别人可以通过 README 文件，就能对你的项目有一个大致的了解。

本项目 README 文件提供以下内容：

项目——Logo 和标语如果你的项目有一个明显的 logo 标识，那么会增加人们的记忆，特别是工具类软件，标语通常是一句简短的话
国际化——因为 Github 为全球社区，所以英文文档是必须的，在此基础上可以加上简体中文，方便英文基础薄弱的人
文档目录——以列表的形式展示了目录索引，让人可以一眼找到自己需要内容
项目介绍——这里可以详细介绍项目的背景与相关信息
图形展示——通常是项目的截图、视频，让他人可以预览项目
特色功能——以列表的形式列出项目的亮点，方便他人了解项目
软件架构——这里一般写软件架构图或者目录结构图，方便用户深入理解项目
使用方法——告诉他人怎么使用你的项目
贡献者——写上作者、贡献者或者赞助项目的人
版权声明——告诉别人你的项目版权

以上列出了本项目 README 包含的元素，基本都是一些通用的元素，你可以根据自己的需要增加或者移除相关元素。项目里面带tmpl.md后缀的文件是两个模板文件，可以直接复制使用，里面有写详细的使用说明。

1.2 效果展示

2. Issue/PR 模板部分

Issue Template 部分，主要包含了 Bug 和 Features 两部分，也分别做了中英文双语支持，算是一个简单的模板。

PR 模板就是一个简单的描述和更新列表

2.1 简介

2.2 效果展示

3. Github Actions CI 部分

3.1 简介

Github Actions CI 部分，主要是我自己平时经常用的一套脚本， Github Actions 教程请参考官方文档，目录里面两个脚本分别是 Hugo 和 NodeJS 项目的配置。

Hugo 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


name: Deploy | 部署

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-deploy:
    name: Automatic deployment | 自动部署
    runs-on: ubuntu-latest
    if: github.repository == 'misitebao/standard-repository'

    steps:
      - name: Checkout | 切换到部署分支
        uses: actions/checkout@v2
        with:
          ref: "master"
          submodules: true
          fetch-depth: 0

      - name: Setup Hugo | 设置Hugo环境
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "0.81.0"
          extended: true

      - name: Build Site | 构建网站
        run: |
                    hugo

      - name: Deploy to Server | 部署到服务器
        uses: hengkx/ssh-deploy@v1.0.1
        with:
          HOST: ${{ secrets.DEPLOY_HOST }}
          USERNAME: ${{ secrets.DEPLOY_HOST_USER }} # 为了用户信息安全对敏感数据可以在secrets中配置
          PASSWORD: ${{ secrets.DEPLOY_HOST_PASSWORD }}
          SOURCE: "public"
          TARGET: "/www/wwwroot/yoursite.com"

NodeJS 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


name: Deploy | 部署

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-deploy:
    name: Automatic deployment | 自动部署
    runs-on: ubuntu-latest
    if: github.repository == 'misitebao/standard-repository'

    steps:
      - name: Checkout | 切换到部署分支
        uses: actions/checkout@v2

      - name: Build Site | 构建网站
        run: |
                    npm install && npm run build

      - name: Deploy to Server | 部署到服务器
        uses: hengkx/ssh-deploy@v1.0.1
        with:
          HOST: ${{ secrets.DEPLOY_HOST }}
          USERNAME: ${{ secrets.DEPLOY_HOST_USER }}
          PASSWORD: ${{ secrets.DEPLOY_HOST_PASSWORD }}
          SOURCE: "build"
          TARGET: "/www/wwwroot/yoursite.com"

目录

推荐的开源项目存储库目录结构