DEV Community

daniel orihuela
daniel orihuela

Posted on Originally published at danielorihuela.dev on

Deploy blog written with org-mode on GitHub Pages

Context

I have been using emacs to write in org-mode for some time now. I love it. So, I decided to start writing a personal blog with it. However, I did not have the tool to create the blog and the means to publish it. I selected a static site generator (SSG) called Hugo for my first problem. It is well known for its simplicity and speed of building sites. For my second issue, I selected GitHub Pages + Github Actions. It seemed the easiest way to have a repository with my code and CI/CD pipelines to generate and deploy the site.

Goal (expected final workflow)

The final workflow should eliminate the need to: manually generate the site and deploy it. We should only focus on the content. That is, writing the posts with org-mode.

After following this guide, we will deploy our site with the following steps:

  1. Write a post in org-mode
  2. Push the new posts to the repository
  3. Nothing. Wait until GitHub Actions automagically generates and deploys your site

Steps

Create GitHub repository

First, we need to create a GitHub repository for our site. In the following list, we can see the configuration.

  • The repository name must be user.github.io
  • The repository visibility must be public
  • Branch for the generated site, โ€œmainโ€ in our case
  • Branch for the source code and org-mode files, โ€œdevelopmentโ€ in our case

Upload Hugo configuration

Once the repository is ready, we can upload our Hugo configuration to the development branch. The Hugo directory structure looks like the tree below. However, we do not need the content folder. It will be auto-generated with ox-hugo. Instead, we will have a folder named posts with the org-mode files.

.
+-- archetypes
+-- config.toml
+-- posts
+-- data
+-- layouts
+-- static
+-- themes
Enter fullscreen mode Exit fullscreen mode

Create GitHub Action workflow

Now, with the Hugo configuration and org-mode posts in the repository, we only have left to create the deployment workflow. We need a GitHub Action that performs the steps below. The code you will find in this section is a modified version of the code athttps://github.com/ayrat555/braindump. The creator of the repo wrote a post explaining how he deploys the notes he takes with org roam.

  1. Checkout repository code

  2. Install emacs

  3. Transform org-mode files to markdown with ox-hugo

  4. Build site with hugo

  5. Publish the site to GitHub Pages

Once we have created the three files, we can upload them to thedevelopment branch. From now on, every time you push new org-mode files to the posts folder of the development branch. The GitHub Actions workflow will publish them.

Conclusion

We presented an easier way to deploy your posts with org-mode , hugo , GitHub Actions and GitHub Pages. With that workflow, we only need to focus on writing org-mode files. Lastly, we know this workflow works because we used it to deploy this post!!!

I hope you liked it and that you have learned something!

Top comments (0)