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.md，Quick 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 目录静态页面部署到静态服务就可以了

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

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

国内镜像

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

quickref.cn
ecdata.cn
aibk.cn
jgeek.cn
laoleng.vip
liujiapeng.com
dbyun.net
dc6.fun
if010.com
pipecraft.net
isteed.cc
1han.wiki
linzhe.top
xushanxiang.com
winnerzr01.github.io
quickref.hestudio.net
surcode.cn
cms.im
nuomiphp.com
eryajf.net
kjchmc.cn
likeadmin.cn
qiubit.cc
aoh.cc
reference.code05.com
kyoma.top
quickreference.pages.dev
code05.com
xhfun.cn
ownit.top

感谢🙏

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

在仓库添加 .github/workflows/update-ref.yml 文件 Github Actions 配置，感谢 @eryajf jaywcjlove#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

贡献

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CONTRIBUTING.md

CONTRIBUTING.md

Contributing 贡献

前沿问题

目录结构

CSS 类注释

首页导航

提示配置

本地开发

快捷部署方法

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

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

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

国内镜像

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

贡献

License

Files

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing 贡献

前沿问题

目录结构

CSS 类注释

首页导航

提示配置

本地开发

快捷部署方法

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

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

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

国内镜像

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

贡献

License