使用 github 或 SourceHut 自动化 Org Mode 网站发布

一旦您开始使用 Org Mode 的发布系统生成静态网站,您下一个想知道的事情可能是如何发布网站,以便其他人可以查看它。

在此视频中,您将学习如何在每次将提交推送到 Git 存储库时自动发布 Org Mode 网站。

要开始,请确保您有以下我们今天要讨论的网站之一的帐户:GitHub 或 SourceHut。

在 GitHub 上,创建帐户和我们在此视频中要讨论的所有内容都是免费的。您可以在这里创建帐户:

https://github.com/join

在 SourceHut 上创建帐户也是免费的,但 他们最近不得不要求支付 才能使用他们的构建服务,因为加密货币矿工让每个人的派对变得糟糕。 幸运的是,您可以以每月至少2美元的价格注册“维护人”帐户:

https://meta.sr.ht/register/step2

有其他方法可以在 SourceHut 上获得免费服务,请查看 这个条目中的计费常见问题解答。

这两个选项都很好,在每个选项上发布网站的难易程度大致相同。

GitHub 是知名的主流选项,拥有一个帐户无伤大雅。

SourceHut 是一个更注重黑客的网站,采用完全不同的哲学,您可能会欣赏。您可以通过查看他们的网站http://sourcehut.org|sourcehut.org了解更多信息。请注意,在 SourceHut 页面上发布的内容有一些限制!

无论在哪个托管网站上,您都需要一个存储库来存储您的 Org Mode 网站的内容文件和我们在此系列视频的上一段中创建的构建脚本。如果您还没看过,可以在这里查看:

• 使用Org Mode构建您的网站

我们将从该视频中的org-website-example repository中的代码开始,所以您可能需要克隆该存储库,在文件系统上创建一个新文件夹,并将这些网站文件复制到其中以做为起点。

我不会在此集中深入讨论如何使用 Git,但我会简要概述您需要了解的命令,以将您的网站文件转化为 Git 存储库并“提交”更改:

# 复制起点文件
git clone https://github.com/SystemCrafters/org-website-example

# 创建本地存储库文件夹
mkdir my-org-site
cd my-org-site
cp -R ../org-website-example/* .

# 初始化Git存储库并执行第一次提交
git init
git add -A
git commit -m "我的第一个提交!"

现在,每次对网站进行更改,您都可以转到 my-org-site 文件夹并运行以下命令:

git add -A
git commit -m "更新网站文件"

# 我们将在稍后讨论此步骤
# git push origin master

如果您是 Git 的初学者并想了解更多如何使用它的信息,我建议阅读 Git Book。

要使用 GitHub Pages 发布网站,您需要创建一个具有特定名称的存储库:

yourusername.github.io 您可以转到 https://github.com/new 并使用您的实际 GitHub 用户名创建此名称的公共存储库!不要选择任何复选框,我们将在创建 GitHub 存储库后推送我们自己的存储库。

现在存储库已创建,您可以复制他们提供的链接,以便您可以配置本地存储库以推送到那里:

# 使用HTTPS
git remote add origin https://github.com/yourusername/yourusername.github.io.git

# 如果您设置了公钥,请使用SSH
git remote add origin git@github.com:yourusername/yourusername.github.io.git

如果您以前从未尝试过,向 GitHub 验证身份可能有点棘手,请参阅此文档页面以获取更多详细信息! https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-command-line

创建存储库后,您可以使用 git push 将本地存储库推送到那里:

git push origin master

每次提交更改后,您都需要运行此命令,以便更改提交到托管存储库!

在 SourceHut 上,您可以通过转到以下链接来创建一个新存储库。它不需要特定的名称!

https://git.sr.ht/create

只需要确保首先设置SSH 密钥,因为这是向 git.sr.ht 验证身份的唯一方式。

创建存储库后,您可以将其配置为本地存储库的远程存储库:

git remote add origin git@git.sr.ht:~yourusername/my-org-site
git push origin master

SourceHut 允许您为个人网站(yourusername.srht.site)或使用简单的HTTP API的任何自定义域发布页面。

可以在 快速入门说明 和 文档 中找到更多详细信息。

现在我们可以设置一个构建配置,以便每次向其存储库推送提交时,它都会自动发布您的网站!

这是通过使用像 GitHub Actions 或 SourceHut Builds 这样的“持续集成”服务实现的。此类型的服务使您能够在云中的计算机上为存储库运行构建脚本,以便您可以执行诸如对代码运行测试或发布网站之类的操作。

我将向您展示 GitHub 和 SourceHut 的示例构建配置,您可以复制和粘贴以开始使用,如果决定使用 SourceHut,只需要做几个细微调整。

此文件应放置在存储库中的 .github/workflows/publish.yml 。它做的事情如下:

• 配置构建以在 master 分支上触发提交(如果您的分支名称为 main,请更改分支名称)!
• 设置 Ubuntu VM 来运行构建
• 检出此存储库的代码
• 安装 emacs-nox (没有图形界面)- 视频录制时的26.3版本
• 运行我们的 build.sh 脚本来构建网站
• 使用自定义操作将网站发布到 gh-pages 分支

name: Publish to GitHub Pages

on:
  push:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Check out
        uses: actions/checkout@v1

      - name: Install Emacs
        run: sudo apt install emacs-nox --yes

      - name: Build the site
        run: ./build.sh

      - name: Publish generated content to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@4.1.4
        with:
          branch: gh-pages
          folder: public

将此文件添加到存储库文件夹,提交并使用我之前向您展示的命令将其推送到 GitHub 存储库。

您可以从存储库的 Actions 选项卡监视 “Publish to GitHub Pages” 操作的进度。 完成后,网站仍不会发布,因为我们需要采取最后一步来配置网站!单击存储库上的 Settings 选项卡,单击设置页面左侧的 Pages 选项卡,然后将源分支更改为 gh-pages 并单击 Save 。

一两分钟后,您的网站现已上线!

此文件应放置在存储库中的 .build.yml 。它做的事情如下:

• 设置 Arch Linux VM来运行构建
• 运行VM后安装 emacs-nox 软件包
• 使用 oauth 字段自动获取发布网站的令牌
• 指定要克隆的源存储库(可以有多个)
• 设置包含网站名称的环境变量

您必须更改这些内容:

• sources: 使用存储库的正确URL
• site: 更新URL以使用您的用户名
• build: 更新 cd my-org-site 以引用存储库的名称

image: archlinux
packages:
  - emacs-nox
oauth: pages.sr.ht/PAGES:RW
sources:
  - https://git.sr.ht/~username/my-org-site
environment:
  site: username.srht.site
tasks:
  - build: |
      # 生成网站文件(请确保更新文件夹名称!)
      cd my-org-site
      ./build.sh

      # 捆绑网站
      cd public
      tar -czf /home/build/html.tar.gz .
  - upload: |
      tar -ztvf html.tar.gz
      acurl --fail-with-body https://pages.sr.ht/publish/$site -Fcontent=@html.tar.gz

提交此文件并将其推送到 SourceHut 存储库后,您可以通过转到帐户的构建页面来监视构建:

https://builds.sr.ht

构建完成后,您可以在https://yourusername.sr.ht.site 访问您的网站!它可能需要一分钟左右才会显示。

如果构建失败,请仔细检查 .build.yml 文件中的所有信息,确保您没有遗漏任何内容!

我不会在这里详细介绍,因为 GitHub 和 SourceHut 的文档页面已经很好地介绍了这一点。

可以为这两个平台上的网站设置自定义域名!

• GitHub Pages 的说明
• SourceHut 的说明

如果您的网站还没有域名,可以使用我的Namecheap的推广链接同时获得域名和支持该频道!

希望这些说明能帮助您使用 Emacs、Org Mode 和 Git 运行新的网站。

在本系列的未来视频中,我们将学习如何定制 Org Mode 网站的样式,并添加有用的功能,例如RSS种子和网站地图!