Effortless Web Publishing with Emacs

<< Back

Tools I use for this:

Emacs, Org Mode, S3, GitHub Actions, Git

What I will cover

How I use the same tools I use to create software for publishing notes and documents. This will involve some brief discussions on:

  1. S3 Website Hosting
  2. Web Publishing with Emacs and Org Mode
  3. Publishing the Site to S3 with GitHub Actions
  4. Summing Up: Change Publishing Workflow

S3 Website Hosting

Why?

I have been publishing content on the Internet since I first started using a computer as a teenager in the 90s. Suffice to say, I have seen quite a few ways of doing this. The last way that I attempted came at about the time it was fashionable to learn web development using Ruby on Rails. I learned from this that I didn't value anything I had to say enough to:

  • Make a trivial blog web application
  • Host this application on a VPS
  • Install security patches on the VPS
  • Ensure the VPS would withstand daily cyber attacks
  • Ensure the front end is responsive and adheres to some accessibility standards

How?

Enter S3 Web hosting. By the time I learned you could host static content on an S3 bucket I was beyond ready to move away from my half-hearted foray into "blogging". By just granting public access to the S3 bucket, I was already well on my way to solving quite a few of the above problems.

I used this guide to setup my domain and the s3 bucket.

Web Publishing with Emacs and Org Mode

Why?

At around the time I discovered hosting static content on S3, AWS Lambda functions were becoming a thing. I wanted to hop on the Lambda band wagon so desperately that I concocted a scheme to update my static content "dynamically" using a Lambda. It worked, but I have doubts about whether or not the results are worth discussing.

After all, shouldn't there be a way to organize and publish web content without all the trappings of a CMS or a "blog" or a Substack (or a Lambda!)? Don't computers already allow people to store and organize content via these things called files and directories?

How?

I used this guide from System Crafters for creating the site. Also, I would be remiss if I didn't mention that System Crafters provide a wealth of a great material for learning and getting your work done with Emacs.

All in all, I think it took roughly an hour to follow along and customize some aspects of it to my liking.

Publishing the Site to S3 with GitHub Actions

I want publishing content to be as easy clicking some sort of publish button in a CMS. The developer's equivalent of that is pushing my content to a GitHub repository. I can setup a GitHub Action to detect that my content has been updated and then publish it to S3.

How?

If you are new to GitHub Actions, I would recommend reviewing one of several introductions on YouTube. I say this because I think it is important to have some grounding in what GitHub Actions is and isn't. For example, it is not really just CI for GitHub. Rather, I like to think of it as a set of templates and tooling for doing automation in response to code changes.

In order to get the publishing to happen, I create a GitHub action like below: 

  # This is a basic workflow to help you get started with Actions
permissions:
  id-token: write # required to use OIDC authentication
  contents: read # required to checkout the code from the repo

name: Publish

# Controls when the workflow will run
on:
  # Triggers the workflow on push or pull request events but only for the "main" branch
  push:
    branches: [ "main" ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v3

      # This is likely not necessary as awscli is probably
      # pre-installed on the runner.
      # I added it because I didn't feel like tinkering with it if
      # something didn't work as expected
      - name: Install aws cli
        run: sudo apt update && sudo apt install --assume-yes awscli

      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::12345678:role/GithubActionsOIDC-Role-1G9876DP
          role-duration-seconds: 900 # the ttl of the session, in seconds.
          aws-region: us-east-1 # use your region here.

      - name: Run S3 Sync
        run:
          aws s3 sync ./public/ s3://yoursitesbucket.com/ --acl public-read

The use of the aws-actions/configure-aws-credentials@v1 action should stand out. Something felt a little clunky about using an S3 Access Key directly in the action. As it turned out, someone else agreed. I followed that link's guide to setup a way of accessing my S3 bucket without needing to paste credentials into the above yaml.

Now whenever I push to the main branch of my site's GitHub repository, my site is published via the S3 sync command.

Summing Up: Change Publishing Workflow

Ok. If you have made it this far, you might be wondering what steps I take to publish content. 

# Makes changes
./build.sh
git add .
git commit -m "My exciting changes"
git push origin main

Emacs 29.0.50 (Org mode 9.5.4)