Easy blogging with Hugo, CircleCi and Surge


Once I’d decided to start this blog, I wanted to make sure that it was as simple as possible to look after. So, having used Hugo on a couple of other projects it was the first point of call. Hugo is an open source static site generator that uses markdown as its content source and then applies a theme to create the site. I love this separation of the content and styling, it has allowed me to easily transform the look of a site without reworking the content and its great to be able to write a web page without really thinking too much about the formatting. Markdown doesn’t really get in the way as much as WYSIWYG editors or raw HTML, giving you a chance to get a good flow going. Another attribute I like is that all the complexity is at build time, meaning no pesky serverside to take care of, once hugo has worked its magic your left with a totally static html site. Previously, I’d deployed things using ftp up to some personal webspace but in 2019 there are a couple of better options.

Firstly, having been saved a few times by the power of source control I thought this site should get the same protection as my other projects. So each time I’m happy with a post I commit it and push it up to bitbucket. I’ve hooked up CircleCi so that it triggers the hugo build and the deploys that using surge, a brilliant command line tool for publishing static sites.

One of the great things about CircleCi and there are many, is that it uses docker images as part of its build infrastructure, for many environments these images do exactly what you need out of the box but while you can get an image that will build a site using Hugo and get an image that you can run node on (surge is an npm module) there isn’t an image that does both. Being a brilliant tool CircleCi allows you to upload your own custom images, but being a lazy developer I thought I’d tryout CircleCi’s other trick workspaces. Workspaces allow you to share data between jobs, you can read about them here. Using workspaces I was able to attach two prebuilt docker images and remove that potential work from the maintenance of the site, it was a bit tricky to get everything attached together the first time I tried but in case you want to give it a go here’s an extract of the circle config.

version: 2
references:
  workspace_root: &workspace_root
    /tmp/workspace
  attach_workspace: &attach_workspace
    attach_workspace:
      at: *workspace_root
jobs:
  deploy-job:
      docker:
        # specify the version you desire here
        - image: circleci/node:7.10
      working_directory: /tmp/workspace
      steps:
        - *attach_workspace
        # Download and cache dependencies
        - restore_cache:
            keys:
            - v1-dependencies-{{ checksum "package.json" }}
            # fallback to using the latest cache if no exact match is found
            - v1-dependencies-
        - save_cache:
            paths:
              - node_modules
            key: v1-dependencies-{{ checksum "package.json" }}
        # deploy the build
        - run: ls
        - run: sudo npm install --global surge
        - run: surge --project out --domain thebrownbagblog.com
  build-job:
    docker:
      - image: cibuilds/hugo:0.41
    working_directory: /tmp/workspace
    steps:
      - *attach_workspace
      - checkout
      - run: git submodule sync
      - run: git submodule update --init
      - run: hugo --destination out
      - persist_to_workspace:
          root: /tmp/workspace
          paths:
            - out
workflows:
  version: 2
  production:
    jobs:
      - build-job
      - deploy-job:
          requires:
            - build-job
          filters:
            branches:
              only: master

Hugo, CircleCi and Surge are all great tools on their own but can come together to make blogging all about the content.

comments powered by Disqus