在贡献指南添加图形化描述

Author: northword

src/contributing/build.md

@@ -2,7 +2,7 @@
 title: 构建指南
 icon: build
 date: 2023-07-21 11:08:04
-updated: 2023-07-21 17:20:22
+updated: 2023-09-22 15:23:36
 ---
 
 # 构建指南
@@ -15,15 +15,23 @@ updated: 2023-07-21 17:20:22
 
 以下介绍了一次完整修改所需的步骤。
 
+::: tip
+
+为了降低操作门槛，本指南所述操作步骤均尽可能使用了图形化界面。对于熟悉 Git 的同学，仍可使用自己喜欢的方式进行操作。
+
+:::
+
 ## 环境配置
 
 ### 所需软件安装
 
 本文的需要 Node.js 和 Git 安装在你的电脑上，后续步骤假定你已经安装这些程序且可以简单使用，若没有安装这些软件请跟随本小节指引完成安装。
 
+为了方便编辑和提交，我们还推荐安装 `VS Code` 和 `GitHub Desktop` 两个软件。
+
 :::: details 安装 Git
 
-地震“学”所有文档均使用 `Git` 进行版本控制。以下步骤假定
+所有文档均使用 `Git` 进行版本控制。以下步骤假定
 
 用户已安装 git。若未安装，可以使用以下命令安装或更新 git：
 
@@ -69,8 +77,6 @@ $ cat ~/.gitconfig
     email = zotero-user@gmail.com
 ```
 
-::::
-
 ::: details Git 和 GitHub 学习资料
 
 以下修改文档并提交的步骤中使用了 Git 的一些常用选项，可以参考以下资料学习更多用法：
@@ -87,39 +93,47 @@ GitHub 相关资料：
 - [Understanding the GitHub flow](https://guides.github.com/introduction/flow/)
 :::
 
+::::
+
 ::: details 安装 Node.js
 
 安装 Node. js
 
 :::
 
-### 克隆和复制仓库
+::: details 安装 VS Code
+
+安装
+
+:::
 
-:::info
+::: details 安装 GitHub Desktop
 
-以下内容假定读者的 GitHub 账号为 `zotero-user`，实际的命令将用户名替换即可。
+安装 <https://desktop.github.com/>
 
 :::
 
-1. 复制仓库至个人 GitHub 帐号
+### 克隆和复制仓库
+
+1. 复制 (fork) 仓库至个人 GitHub 帐号
 
-   点击项目主页 < <https://github.com/zotero-chinese/wiki/> 右上角的 Fork 按钮，将该项目复刻到个人 GitHub 账户下。
+   点击项目主页 <https://github.com/zotero-chinese/wiki/> 右上角的 Fork 按钮，将该项目复刻到个人 GitHub 账户下。
 
    ![复刻仓库](../assets/image-fork-repo-1.png)
 
    ![复刻仓库2](../assets/image-fork-repo-2-1.png)
 
    复制完成后，个人 GitHub 帐号下便有了 <https://github.com/zotero-user/wiki/> 仓库。
 
-2. 克隆个人 GitHub 帐号下的复刻仓库到本地（复刻仓库默认是本地克隆仓库的远程 origin）:
+2. 克隆个人 GitHub 帐号下的复刻仓库到本地（复刻仓库默认是本地克隆仓库的远程 origin）
 
-   ```bash
-   # Clone repo
-   git clone https://github.com/zotero-user/wiki.git
+   打开 VS Code，点击 `欢迎页面` 的 `克隆 Git 仓库…`，在弹出窗口中选中 `从 GitHub 克隆`，然后选择自己账户下的 fork 仓库，确认，克隆完成后根据提示打开文件夹。
 
-   # 进入仓库目录
-   cd wiki/
-   ```
+   ![克隆Git仓库](../assets/8c581efa5ed9f3ac9d5771b89204bd6b_MD5.png)
+
+   ![从GitHub克隆](../assets/741b873973ac5df93faf93cd1a195db2_MD5.png)
+
+   ![选择仓库](../assets/28f02608aa879ed189ecfecfcab57d16_MD5.png)
 
    ::: tip
 
@@ -135,6 +149,8 @@ GitHub 相关资料：
 npm install
 ```
 
+![安装依赖](../assets/image-build-安装依赖-1.png)
+
 ::: info
 
 上述“环境配置”步骤只需在第一次修改代码时执行一次，一旦复制或克隆某仓库后，就无需再次复制或克隆。
@@ -145,14 +161,7 @@ npm install
 
 1. 在本地创建并切换至新分支，假定新分支名为 `pr-workflow`（分支名需简短、描述性且独特）:
 
-   ```bash
-   # 若不在 main 分支，需先切换至该分支
-   # 若已有一段时间没有更新，请切换到 main 分支后 pull 上游仓库中的更改
-   $ git checkout main
-
-   # 创建并切换至 pr-workflow 分支
-   $ git checkout -b pr-workflow
-   ```
+   ![创建新分支](../assets/image-build-创建新分支-1.png)
 
 2. 启动开发服务器
    使用以下命令启动开发服务器，如下图，开发服务器启动后，会给出几个本地链接，访问任一链接（通常为 Local）即可得到预览。
@@ -161,7 +170,9 @@ npm install
    npm run docs:dev
    ```
 
-   开发服务器会监听所有 `.md` 文件的修改，当有文件发生保存是，服务器会自动更新预览并刷新网页。
+   ![启动开服务器](../assets/image-build-启动开发服务器-1.png)
+
+   开发服务器会监听所有 `.md` 文件的修改，当有文件发生保存时，服务器会自动更新预览并刷新网页。
 
    ![开发服务器](../assets/image-build-dev-server-1.png)
 
@@ -171,93 +182,62 @@ npm install
 
 4. 提交 commit
 
-   ::: details Git commit 的命令
+   在左侧 " 源代码管理 " 选项卡中，输入一个简短的提交描述，点击提交，然后将修改推送到线上。
 
-   ```bash
-   # 查看仓库当前的状态
-   $ git status
-   # 添加所有修改
-   $ git add --all
-
-   # 查看仓库当前的状态
-   $ git status
-   # 提交添加的修改
-   $ git commit -m "此处填写本次提交的注释信息"
-   ```
+   ![提交修改](../assets/image-build-提交修改-1.png)
 
-   :::
+   ![推送修改](../assets/image-build-推送修改-1.png)
 
    ::: tip
 
-   如前所述，提交命令也可以在 GitHub Desktop 或 VS Code 中完成。
+   如前所述，提交命令也可以在 GitHub Desktop 中完成。
 
    :::
 
    ::: warning
 
    不建议直接在 main 分支中进行修改和提交，这可能会给你自己造成麻烦。
 
-   :::
-
-## 提交并开始 PR
+   仓库对 main 分支开启了推送保护，对 main 分支的修改只能通过 Pull Request 进行，无法直接 Push。
 
-1. 推送 pr-workflow 分支至个人 GitHub 帐号下的复制仓库:
+   :::
 
-   ```bash
-   git push origin pr-workflow
-   ```
+## Pull Request
 
-2. 提交 PR
+1. 提交 PR
 
-   进入个人 GitHub 帐号下的复制仓库（即 <https://github.com/zotero-user/wiki/>）。
+   进入个人 GitHub 帐号下的复制仓库（即 <https://github.com/你的名字/wiki/>）。
 
    一般 GitHub 会自动提示有可提交的 PR，点击 “Compare & pull request”，输入此 PR 的标题和具体描述，
 
    最后点击 “Create pull request” 即可。
 
-3. 审核、评论以及修改 PR
+2. 审核、评论以及修改 PR
 
    文档维护者收到 PR 后，会对代码进行审核、评论以及修改，并决定是否接受（merge）或结束该 PR。
 
-   提交的 PR 在接收前可能需要读者多次修改。这种情况并不要创建新 PR，只需继续本地 pr-workflow 分支中修改并提交，然后再次推送 pr-workflow 分支至远程 origin 即可，修改将自动添加到已提交的 PR 中。
-
-   推送新的修改后，可以选择在该 PR 中留言，以通知维护者已提交新的修改。
-
-4. PR 被接受并合并至官方 main 分支后，则可以更新 main 分支，并删除 pr-workflow 分支
-
-   ::: details
+   PR 发起后，Netlify 机器人会自动部署一个预览版本，可以在这里查看预览。
 
-   更新本地和个人 GitHub 中的 main 分支:
+   ![netlify预览pr](../assets/image-build-pr预览-1.png)
 
-   ```bash
-   # 切换回本地 main 分支
-   $ git checkout main
-
-   # 获取官方 main 分支，并合并到本地 main 分支
-   $ git pull upstream main
-
-   # 更新个人 GitHub 中的 main 分支
-   $ git push origin main
-   ```
-
-   删除本地和个人 GitHub 中的 pr-workflow 分支:
+   提交的 PR 在接收前可能需要读者多次修改。这种情况并不要创建新 PR，只需继续本地 pr-workflow 分支中修改并提交，然后再次推送 pr-workflow 分支至远程 origin 即可，修改将自动添加到已提交的 PR 中。
 
-   ```bash
-   # 删除本地 pr-workflow 分支
-   $ git branch -D pr-workflow
+   推送新的修改后，可以选择在该 PR 中留言，以通知维护者已提交新的修改。
 
-   # 删除个人 GitHub 上的远程 pr-workflow 分支，也可以在 GitHub 上点击按钮删除分支
-   $ git push origin :pr-workflow
-   ```
+3. PR 被接受并合并至官方 main 分支后，则可以更新 main 分支，并删除 pr-workflow 分支
 
-   :::
+   ![更新main分支](../assets/image-build-更新main分支-1.png)
 
 ## 其他的脚本
 
 ### npm run docs:build
 
-构建
+构建脚本，用于将 markdown 构建为网页。
+
+贡献者可以在提交前运行一次，查看是否有报错。
+
+一般情况下，图片路径错误、链接错误会导致报错。
 
 ### npm run lint
 
-Markdown Lint
+运行 Markdown Lint。

src/contributing/contributing.md

@@ -60,7 +60,7 @@ Zotero 中文文档接受多种形式的贡献，请阅读这一份指南，以
 
    如果提示需要 fork 才能继续则点击即可。
 
-   编辑需要修改的地方，Markdown 语法请参阅 [Markdown 语法](markdown-demo.md)。
+   编辑需要修改的地方，文档风格和 Markdown 语法请参阅 [文档风格指南 #Markdown 语法](markdown.md#文档语法风格)。
 
 2. 提交修改
 
@@ -78,10 +78,14 @@ Zotero 中文文档接受多种形式的贡献，请阅读这一份指南，以
 
 ### 稍微大量修改
 
-请参考 [使用 vscode.dev 指南](vscode-dev.md)
+例如你需要添加一篇文章，上传一些图片等，且对 Git 不甚了解，那么可以使用这种方式在线修改，这可以避免你下载很多软件。
+
+请参考 [使用 vscode.dev 指南](vscode-dev.md)。
 
 ### 大量修改
 
+如果你需要做较大量修改，例如增加几篇文章，或长期贡献/维护仓库，可以采用这种方式：完全本地修改，可以在本地预览修改的效果，修改后再推送到 GitHub。
+
 请参考 [完全构建指南](build.md)。
 
 ### 注意事项