Hosting On Github

Typically, if you wanted to host something on GitHub Pages, you’d create a repository with the name my_github_username.github.io, write your Markdown or HTML documents as pages or posts, and then commit those changes and push them to the repository. When GitHub realizes the repository is a GitHub Pages repository, it runs some site-building procedures using its “continuous integration” (CI) to rebuild your website from those Markdown or HTML pages each time you push a new commit to the remote repository.

But I’m built different. I am not writing Markdown or HTML documents. I’m writing Org Mode documents and then exporting them to HTML documents. Because the Org Mode documents need to be exported by Emacs in order for GitHub Pages to render them as pages on the site, we need to explicitly tell GitHub pages what to do. Thankfully, SystemCrafters has a video that covers this.

What we need to do is provide GitHub’s continuous integration the specific steps required to build this site. This is done through the file .github/workflows/publish.yml stored in the repository’s root directory.

With this file, we can specify when want to perform this task. For a static website, I really only need to do this each time I update the remote repository, so we set that as the trigger for the workflow. Additionaly, we need to specify which Git branch triggers this task. In my case, this is master. GitHub is moving away from using master as the default branch name, but the default CI for GitHub pages expects a branch name “master”. We aren’t using the default CI, so we can actually afford to change this. I’ll handle that at a later stage. For now, I just want to make this work.

# Give the job a name
name: Publish to GitHub Pages

# Specify when to perform this task
on:
  push:
    branches:
      - master

Next, we need to specify how to run the workflow. First, we want to run the workflow on a virtual machine running the latest version of Ubuntu, which we accomplish by specifying runs-on as ubuntu-latest. We also need to check out the code for running on the VM, install a minimal Emacs that will run our script, run the build script that we built in the initial build set up, and then publish the pages using a community developed action. This community action will ultimate create a new branch, gh-pages, where our exported pages will live.

Note: These steps will likely change as new steps are added, like Jekyll integration. For now though, this will get our initial site published using GitHub Pages.

# Specify the steps, in sequential order, to perform
jobs:

  publish:

    # Use the latest version of Ubuntu for the VM
    runs-on: ubuntu-latest

    steps:

      # Check out the code to be run on the VM
      - name: Check out
        uses: actions/checkout@v1

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

      # Run the build script
      - name: Build the site
        run: ./build.sh

      # Publish the site using a community deploy action
      - name: Publish generated content to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@4.1.4
        with:
          branch: gh-pages
          folder: public

After we push a new commit with this new file added. GitHub will perform these tasks. There’s just one more requirement before this produces a published page. On the GitHub repository web page, go to Settings > Pages and then in the “Branch” section, change the branch to gh-pages. After this, the web page should show your published content. It may take a couple minutes to load, though.