思源笔记一键发布至 Hexo、Hugo、Jekyll、Vitepress、Vuepress 博客（github）并通过 github action 构建 page 并同步 gitee page

先决条件：思源笔记、一键发布工具、Hexo\Hugo\Jekyll\Vitepress\Vuepress 相关主题

　　以 Hugo 的 hugo-theme-next 主题示例，其他的同理，构建文件不同

　　注意事项：Hugo 使用无序和有序列表尽量不要超过 3 层

　　部署和配置时长：1 小时 +

　　部署流程：克隆 Hugo 主题至自己仓库-> 创建主页仓库-> 获取 github 个人访问令牌 token->github action 构建并输出至主页主页->gitee 导入 github 仓库并配置镜像仓库-> 开通 gitee page-> 配置 hugo-theme-next

　　使用流程：思源笔记一键发布插件配置-> 使用一键发布插件发布文章并选择 hugo

　　部署详情：

• 克隆 Hugo 主题至自己仓库

  • ⏬ 克隆主题

    点击右上角的 Use this template 绿色按钮然后填写代码仓库的相关信息，参考如下：

    https://camo.githubusercontent.com/0031520ad9bb551333a37cf756fbfb3f538e6f33638cd3318e5d70f94aae28e8/68747470733a2f2f696d67732e6c6973656e6875692e636e2f6875676f2d6e6578742f7573652d6875676f2d6e6578742d737461727465722e706e67

    最后点击 Create repository from template 绿色按钮，会直接在你的空间中生成站点代码，再使用 git clone 命令把它克隆到本地进行创作。

    记得首次完全克隆后，需要在根目录中使用如下的 Git 子模块更新命令拉取 hugo-theme-next 主题的最新版本。

• 创建主页仓库

  • 自定义首页，首先需要创建一个与你 Github ID 同名的仓库

    

    创建完成

• 获取 github 个人访问令牌 token

  当您需要在 GitHub Action 中执行需要身份验证的操作时，例如推送到另一个仓库或访问私有仓库，您需要提供身份验证凭据。GitHub 提供了一种安全的方式来存储这些凭据，即使用 Personal Access Token（个人访问令牌）并将其添加到仓库的 Secrets 中。

  以下是如何生成 Personal Access Token 并将其添加到 GitHub 仓库的 Secrets 中的详细步骤：

  1. 生成 Personal Access Token：

  - 登录到您的`GitHub`账户。
  
  - 点击右上角的头像，然后选择`Settings`（设置）。
  
  - 在左侧导航栏中，点击`Developer settings`（开发者设置）。
  
  - 在下拉菜单中，选择`Personal access tokens`（个人访问令牌）。
  
  - 点击右上角的`Generate token`（生成令牌）按钮。
  ​

  

  2. 配置 Personal Access Token 的权限：

  当您生成`Personal Access Token`时，需要为其分配适当的权限。根据您的需求，可以为其分配不同的权限，例如访问仓库、读取用户资料等。请谨慎选择权限，最小化所需的权限以提高安全性。
  ​

  

  3. 生成令牌：

  在配置了权限后，滚动到页面底部，然后单击`Generate token`（生成令牌）。`GitHub`将生成一个令牌，并将其显示在屏幕上。请务必将此令牌复制到安全的地方，因为在生成后，您将无法再次查看完整的令牌。
  ​

  4. 将令牌添加到 GitHub 仓库的 Secrets：

  - 转到包含您的博客源文件的GitHub仓库。
  
  - 在仓库顶部导航栏中，单击`Settings`（设置）。
  
  - 在左侧导航栏中，选择`Secrets`（密码）。
  
  - 单击`New repository secret`（新存储库密码）按钮。
  
  - 在`Name`字段中，输入`PERSONAL_TOKEN`（或您选择的名称）。
  
  - 在`Value`字段中，粘贴您在第3步中生成的`Personal Access Token`。
  
  - 单击`Add secret`（添加密码）按钮。
  ​

  

  

  

  现在，您的 Personal Access Token 已经以安全的方式存储在 GitHub 仓库的 Secrets 中，并可以在 GitHub Action 的工作流程中使用。

  在上文中提到的 PERSONAL_TOKEN 将会被引用并传递给 GitHub Action 中的相关步骤，以便执行需要身份验证的操作。这个过程确保了敏感凭据的安全性，并且不会将它们直接硬编码到工作流程文件中，从而保护了您的 GitHub 仓库的安全性。

• github action 构建并输出至主页主页

  • 配置 GitHub Action，首先需要在博客源文件的仓库中创建一个 .github/workflows 目录，并在该目录下创建一个 .yml 配置文件。我们将其命名为 deploy.yml。

    以下是本人改进过的自动化部署 Hugo 博客的示例 deploy.yml 配置文件：

  • .github/workflows/deploy.yml

    name: deploy
    
    on:
      push:
        branches:
          - main  # 或者是你的源代码分支
    
    jobs:
      deploy:
        runs-on: ubuntu-latest
    
        steps:
        - name: Checkout repository
          uses: actions/checkout@v4
          with:
              submodules: true
              fetch-depth: 0
    
        - name: Set up Hugo
          uses: peaceiris/actions-hugo@v2.6.0
          with:
            hugo-version: "latest"
            extended: true
    
        - name: Build and Deploy
          run: |
            hugo -F --cleanDestinationDir  # 生成静态文件
            mkdir -p public  # 确保public文件夹存在
            cp -r public/* ./  # 复制生成的静态文件到仓库根目录
    
        - name: Deploy to GitHub Pages
          uses: peaceiris/actions-gh-pages@v3.9.3
          with:
            PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}  # 你的个人访问令牌
            EXTERNAL_REPOSITORY: szhiku/szhiku.github.io  # 你的GitHub Pages仓库
            PUBLISH_BRANCH: main  # 或者是你的GitHub Pages分支
            PUBLISH_DIR: ./
            commit_message: ${{ github.event.head_commit.message }}
    ​

  • 之后点右上角的 commit（提交），会自动触发构建，构建详情如下图

    

  • 正常的话，github pages 已经可以了

    点击设置，再点击右边栏上的 Pages

    

    5. 设置 main 分支，root 根文件夹，并点击保存

    

    6. 可以看到 Actions 中已经在构建和部署页面了

    

    7. 构建完成后，重新回到 设置的 Pages 页，可以看到多了如下的提示，点击查看即可

    

• gitee 导入 github 仓库并配置镜像仓库

  • 登录 gitee 导入 github 仓库

    

  • 添加 Pull 方向的镜像

    Pull 方向的镜像用于将 GitHub 的仓库镜像到 Gitee 。

    你可以根据自身需求选择 自动镜像 或 手动镜像。

    你可以通过以下方式配置 Pull 方向的镜像：

    1. 进入需要使用镜像功能的仓库，进入「管理」找到「仓库镜像管理」选项，点击「添加镜像」按键；

       如果你还没有绑定 GitHub 帐号，请根据弹窗提示绑定 GitHub 帐号；

       

    2. 添加镜像；

       1. 在「镜像方向」中选择 Pull 方向；

       2. 在「镜像仓库」下拉列表中选择需要镜像的仓库；

       3. 在「个人令牌」中输入你的 GitHub 私人令牌；

          • 私人令牌中必须包含对 repo 的访问授权，否则添加后镜像不可用；

       4. 根据自身需求选择是否勾选「自动从 GitHub 同步仓库」；

          • 勾选后，我们将会在镜像仓库中自动生成 webhook 用于实现自动镜像；
          • 此功能需要你的个人令牌中包含对 admin:repo_hook 的访问授权，否则会添加失败；

       5. 点击「添加」保存镜像配置；

          • 如果添加失败，请根据 如何申请 GitHub 私人令牌 提供的流程重新申请私人令牌；
          • 如果重新申请私人令牌后仍然添加失败，请取消勾选「自动从 GitHub 同步仓库」后点击「添加」保存镜像，并 手动配置 webhook。

    配置完成后，可以通过以下方式触发镜像操作（Gitee 从 GitHub 同步仓库）：

    • 推送代码到 GitHub 镜像仓库
    • 手动更新镜像

    镜像触发的最短间隔时间为 5 分钟。

    如果只配置了 Pull 方向的镜像，建议你将最新的代码提交到 GitHub 镜像仓库；

    Gitee 会自动从 GitHub 同步仓库（分支/Branches、标签/Tags、提交记录/Commits）。

• 开通 gitee page

  • A.新建仓库 test_pages

    

    点击创建完成仓库的创建

    B.添加文件 index.html (注意名称是 index.html 哦！)

    点击新建文件

    

    文件名输入 index.html，内容就是简单的 html

    

    点击提交，将文件提交到仓库

    C.选择 pages 服务

    

    D.选择需要部署的分支，这里选择 Master 启动服务。

    

    E.访问生成的网站地址，即可以查看你部署的静态页面啦！

    

    3. 已经有 Pages 仓库如何部署到 Gitee 的 Pages

    以 jQuery-File-Upload 仓库为例，仓库地址：https://github.com/blueimp/jQuery-File-Upload

    它在 Github 上的 Pages 地址是：https://blueimp.github.io/jQuery-File-Upload/

    如果想把它转移到 Gitee Pages，只需要登录你的 Gitee 账户，点击右上角的 + 号，选择新建仓库

    

    

    

    然后点击创建，仓库会在后台自动导入，导入成功后，点击菜单栏的服务下拉 Gitee Pages

    

    

    这里我们默认的 Pages 服务分支是仓库的默认分支，但是你也已选择自己静态页面所在的分支，这里 jQuery-File-Upload 仓库的静态页面分支是 gh-pages，选择 gh-pages 并点击启动服务。

    至此，静态网页已经部署成功，访问提供的地址：https://frech.gitee.io/jquery-file-upload/ 即可查看到 jQuery-File-Upload 仓库的静态官网。

    

• 配置 hugo-theme-next

  • 来到这个文件夹

    

  • 按照备注说明依次修改配置文件 config.yaml、menus.yaml、params.yaml，修改后记得点击右上角绿色的 commt，之后会自动构建

    

　　使用详情：

• 思源笔记一键发布插件配置

  

  

  

• 使用一键发布插件发布文章并选择 hugo

  

  

　　参考资料：

　　教你如何自定义 Github 首页_设置github 主页-CSDN 博客

　　【Hugo 网站搭建】GitHub Action 自动化部署 Hugo 博客 - 知乎

　　仓库镜像管理(Gitee<->Github 双向同步) | Gitee 产品文档

　　Gitee Pages | Gitee 产品文档

　　‍