Skip to content

Latest commit

 

History

History
499 lines (420 loc) · 35.9 KB

CONTRIBUTING.md

File metadata and controls

499 lines (420 loc) · 35.9 KB

Contributing 贡献

感谢您对备忘清单贡献的兴趣👍👍,是像您这样的人使 Quick Reference 成为如此出色的网站 🎉🎉。随时提交问题和增强请求,还提供一个在线说明排版说明,所以各种使用技巧,都在这个排版说明中有预览和实现代码。

docs/{filename}.md 文件将被处理成备忘清单,让我们创建或编辑一个 markdown 文件:

前沿问题

备忘清单 标题
===

这是您可以在 Quick Reference 备忘清单上使用的样式参考!【备忘清单介绍】

只需要 标题<h1>介绍 (标题下面)。脚本会自动识别,通过 GitHub Actions 自动发布 Quick Reference 网站。

目录结构

.
├── CONTRIBUTING.md   # 贡献说明
├── Dockerfile
├── LICENSE
├── README.md         # Home(首页) 内容
├── dist              # 编译后的静态资源目录
├── docs              # Markdown 文档(快速参考备忘清单【速查表】)
│   ├── bash.md
│   ├── ....
│   └── yaml.md
├── package.json
└── scripts           # MD 转 HTML 的编译脚本
    ├── assets        # 存放首页 svg 图标文件资源,与 `dosc` 文件名对应
    ├── ....
    └── watch.mjs

CSS 类注释

Quick Reference 使用 @wcj/markdown-to-html 转换 Markdown,并使用 rehype-attr 插件让其支持通过其注释语法添加类和样式。此外,您可以在 Quick Reference 备忘清单上使用样式参考:https://jaywcjlove.github.io/reference/docs/quickreference.html

最后,参考现有备忘清单的源代码是一个好习惯!

首页导航

Quick Reference 的首页存放在仓库的根目录 README.mdQuick Reference 是通过这个 README.md 自动生成首页导航,下面是导航实例:

## Linux 命令

[Cron](./docs/cron.md)<!--rehype:style=background: rgb(239 68 68/var(\-\-bg\-opacity));-->
[Git](./docs/git.md)<!--rehype:style=background: rgb(215 89 62/var(\-\-bg\-opacity));-->
<!--rehype:class=home-card-->

首页导航图标存放在 scripts/assets 目录中,如果你的备忘清单定义为 docs/cron.md,那么你的图标就定义为 cron.svg 存放到 scripts/assets 目录中,重新编译首页当行菜单就拥有了图标。

  • 图标存放在 scripts/assets 目录中
  • 图片名称与清单名称保持一致 cron.md -> cron.svg (注意大小写)
  • SVG 图标尺寸 <svg height="1em" width="1em"
  • SVG 图标颜色使用继承颜色值 <svg fill="currentColor"

图标可以在 icongo 图标搜索 中搜索

提示配置

[Django](./docs/django.md)<!--rehype:style=background: rgb(12 75 51/var(\-\-bg\-opacity));&class=contributing-->

添加 contributing 类名,会在卡片下方添加 👆待完善需要您的参与,添加 data-info=👆看看还缺点儿什么?,更换默认提示文本。

[Django](./docs/django.md)<!--rehype:style=background: rgb(12 75 51/var(\-\-bg\-opacity));&class=tag&data-lang=Python-->

添加 class=tag&data-lang=Python 类名和参数,会在卡片右上角标记 Python

本地开发

$ git clone https://github.com/jaywcjlove/reference.git 
$ npm i          # 安装依赖
$ npm run build  # 编译输出 HTML
$ npm run start  # 监听 md 文件编译输出 HTML

或者你也可以使用 pnpm 或者 yarn 做为包管理器

快捷部署方法

由于中国国内访问,时常打不开,推荐您部署的镜像网站,大家可以在这里留言推荐您的镜像网站网址,我将放置在首页推荐

方法一,只需要克隆 gh-pages 分支代码到你的静态服务就可以了

$ git clone https://github.com/jaywcjlove/reference.git -b gh-pages

定时更新

在 Linux 服务执行创建 git-down-pages.sh 脚本,将脚本放置在 /opt/cron/ 目录下

注意:⚠️ 脚本会根据线上 pages 的 commit 和 本地 commit 比较。如果不一致才会同步更新,否则跳过

下面是脚本 git-down-pages.sh 的源码

#!/bin/bash
PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:~/bin
export PATH

#author: 南宫乘风

DATA_DIR="/data"
REPO_URL="https://gitee.com/jaywcjlove/reference.git"
BRANCH="gh-pages"
MAX_BACKUPS=3

# 函数:备份旧版本
backup_old_version() {
    echo "备份旧版本..."
    mv ../reference ../reference_backup_$(date +%Y%m%d%H%M%S)
    if [ $? -eq 0 ]; then
        echo "备份完成。"
        remove_old_backups
    else
        echo "备份时出现错误。"
        exit 1
    fi
}

# 函数:删除多余备份,保留最近的三个
remove_old_backups() {
    echo "删除多余备份,保留最近的三个..."
    ls -1d ../reference_backup_* | head -n -${MAX_BACKUPS} | xargs -r rm -r
}

# 函数:拉取最新代码
clone_latest_code() {
    echo "拉取最新代码..."
    # 进入 /data 目录
    cd $DATA_DIR
    git clone $REPO_URL -b $BRANCH
    if [ $? -eq 0 ]; then
        echo "拉取最新代码完成。"
    else
        echo "拉取最新代码时出现错误。"
        exit 1
    fi
}

# 检查是否存在 DATA_DIR 目录,不存在则创建
if [ ! -d "$DATA_DIR" ]; then
    echo "目录 $DATA_DIR 不存在,创建中..."
    mkdir -p "$DATA_DIR"
    if [ $? -eq 0 ]; then
        echo "目录创建成功。"
    else
        echo "目录创建失败。"
        exit 1
    fi
fi

# 进入 /data 目录
cd $DATA_DIR

# 检查是否存在 reference 目录
if [ -d "reference" ]; then
    # 进入 reference 目录
    cd reference
    
    # 获取远程和本地的 commit 哈希值
    REMOTE_COMMIT=$(git ls-remote $REPO_URL $BRANCH | cut -f1)
    LOCAL_COMMIT=$(git rev-parse HEAD)
    
    # 比较远程和本地的 commit
    if [ "$REMOTE_COMMIT" == "$LOCAL_COMMIT" ]; then
        echo "本地 'reference' 目录已经是最新版本,无需拉取。"
    else
        echo "本地 'reference' 目录不是最新版本,开始拉取最新代码..."
        backup_old_version
        clone_latest_code
    fi
else
    # 如果目录不存在,直接克隆
    clone_latest_code
fi

echo "----------------------------------------------------------------------------"
endDate=`date +"%Y-%m-%d %H:%M:%S"`
echo "★[$endDate] Successful"
echo "----------------------------------------------------------------------------"

创建定时任务

注意:请把脚本放在 /opt/cron/ 目录下 (时间可以根据自己需求设定),下面案例:每十分钟同步线上的 pages 的内容

crontab  -e 

*/10 * * * *  /opt/cron/git-down-pages.sh >>  /opt/cron/git-down.log 2>&1

添加 NGINX 配置:

listen 80;
listen 443 ssl http2;
server_name xxx.xxx.top; #配置你的域名
index index.php index.html index.htm default.php default.htm default.html;
root /data/reference;  # 文件存放的位置 

方法二,使用 docker 快捷部署 web 版

$ docker pull wcjiang/reference

$ docker run --name reference --rm -d -p 9667:3000 wcjiang/reference:latest
# Or
$ docker run --name reference -itd -p 9667:3000 wcjiang/reference:latest

方法三,克隆仓库自己编译,添加导航菜单

$ git clone https://github.com/jaywcjlove/reference.git 
$ npm install    # 安装依赖
$ npm run build  # 编译输出静态页面
$ npm run start  # 开发模式,监听实时编译输出静态页面

文件被输出到 dist 目录,将 dist 目录静态页面部署到静态服务就可以了

image

提供自定义菜单,在项目的根目录建立 .env 文件,添加下面内容

REF_URL=http://ref.xxx.cn/
REF_LABEL=网站首页

国内镜像

由于中国国内访问,时常打不开,你可以访问下面镜像网站。

感谢🙏

利用 Github Actions 定时任务来完成自动更新

在仓库添加 .github/workflows/update-ref.yml 文件 Github Actions 配置,感谢 @eryajf #102 (comment) 提供方法

name: 每8个小时更新一次reference
on:
  schedule:
    - cron: '21 */8 * * *' # 定时任务
  workflow_dispatch:       # 手动运行

env: # 设置环境变量
  TZ: Asia/Shanghai # 时区(设置时区可使页面中的`最近更新时间`使用时区时间)

jobs:
  build: # 自定义名称
    runs-on: ubuntu-latest
    steps:
      - name: 🚜 拉取最新代码
        uses: actions/checkout@v3
        with:
          ref: 'main'
          repository: 'jaywcjlove/reference'

      - name: ♻️ 编译静态文件
        run: |
          echo -e 'REF_URL=https://refs.xxx.net/\nREF_LABEL=网站首页' > .env
          npm install
          npm run build

      - name: 🚁 部署到服务器
        uses: wlixcc/SFTP-Deploy-Action@v1.0
        with:
          username: 'root'   #ssh user name
          port: '22' # 远程服务器ssh端口,默认22
          server: 'prod.refs.xxx.net' # 远程服务器IP
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }} # 认证服务器秘钥对的私钥
          local_path: './dist/*'  # 对应我们项目打包后的静态文件路径
          remote_path: '/data/www/refs.xxx.net' # 服务器上的路径
          delete_remote_files: true

贡献

请参阅贡献指南了解如何开始。一如既往,感谢我们出色的贡献者!

小弟调调

fwqaaq zhangym mofelee Maylon Jefferson Huang Steve Hartwell h7ml 南宫乘风 砹小翼 Alex LufsX baoer expoli k23223 二丫讲梵 undefined Darkiiiiiice Kim同学 雨落 Blossom Yuan Liu Willxup YuRuiH chaos richuff 萌新杰少 魏 老大哥 buyfakett 小武Alan 王叨叨 ryanhex53 佐博 pangxiaoli mancuoj kjch infanx Albert Amos Apin Da Da Jack Liu Jason Zhuang Jovins Kisa-Dong Small Long SuperDiscovery XYZ Zhang findnr greyhao gzttcydxx hua03 hupilan hweining irony J.Chen joyfully-W jqzhao jussker Evan-k kdxcxs kubernetes for me yujian(larry) xue leauny Xudong Guo gowshwah godot42 Gavin fjqz177 fakevn cool9203 CoderDuan cizai chyok bgbgPang _lmmmmmm Zyj 都一样 Zheng Nai Bin 行者 芦荟柚子茶 看彩虹的人 焕晨HChen 落叶乌龟 小枫 子斗子 夜未央 吹衣轻飏 无聊波波 zxx457 zhouhw0306 yms xing133 Hudson Alen tmen swift-fs suyangzuo nexo phygerr openapphub onewesong miclon-dev lykjjj lozhu liliangrong777 Mao Wang Lve Lvee likeadmin通过管理后台-likeshop全开源商城 Lihuagreek Light_Quanta JetSquirrel Jeremy Jone JavaZero HooinKyoma GONGYE Heyu Foozi Fan EEEEE DemigodLiu Dasferco Damao DEEMO101 Choo hanchZ chentong Joe BobH Blanket58 BlacAmDK Aze dousha0w0 ANDY 花殇 ZinkCas zhucong yikuaibro Zephyr He Zech Yogurt 李李李 While True: learn() Happy-Engineer Wafer Terry Young TRDSCSH Xiwin Sacabambaspis Ryan Zhou RivailleF QDelta Poirot Hercule Pipecraft Perzch PILIHU2022 Noryu NianwenDan Monet Lee Moeyuuko Minghao Yu Mieriki Mariusz Michalowski

上图贡献者列表,由 contributors 自动生成贡献者图片。

License

MIT © Kenny Wong