Cloud Artisan Blog

Personal blog and project showcase for David Taylor (Cloud Artisan).

Technology

This site is built with:

• Hugo - A fast and modern static site generator
• Congo Theme - A powerful, lightweight theme for Hugo

The theme is vendored under _vendor/, so day-to-day builds do not need Go or a live module download.

Local Development

1. Clone this repository:

   git clone https://github.com/cloudartisan/cloudartisan.github.io.git
   cd cloudartisan.github.io
   

2. Install the Hugo extended binary:

   • macOS (Homebrew): brew install hugo
   • Linux: download the extended release from gohugo.io or install it via your preferred package manager

   The site is pinned to Hugo 0.160.1 via .hugo-version.

3. Build or run the site through the wrapper script:

   ./scripts/hugo.sh server -D
   

   The wrapper keeps Hugo's cache inside the repository (.hugo_cache/), which avoids permission and path quirks on both macOS and Linux.

4. View the site at http://localhost:1313/

Production Build

./scripts/hugo.sh --minify --buildFuture

Updating Theme Dependencies

Normal builds do not require Go. You only need Go when you want to refresh vendored Hugo modules, for example when updating Congo.

1. Install a recent Go toolchain.
2. Refresh the module dependency:

   hugo mod get github.com/jpanther/congo/v2@v2.12.2
   

3. Re-vendor the module:

   ./scripts/hugo.sh mod vendor
   

4. Re-run the build:

   ./scripts/hugo.sh --minify --buildFuture
   

Creating Content

New Posts

hugo new content posts/YYYY-MM-DD-post-name.md

A new post will be created with the following template:

---
title: "Post Name"
date: YYYY-MM-DDT00:00:00+00:00
draft: true
description: ""
tags: []
categories: []
series: []
---

# Post Name

## Introduction

<!-- Write your introduction here -->

## Main Content

<!-- Main content starts here -->

## Conclusion

<!-- Wrap up your post here -->

Draft Post Guidelines

1. File naming: Use the format YYYY-MM-DD-post-name.md (kebab-case)

2. Frontmatter:

   • title: Clear, descriptive title in title case
   • date: Publication date in ISO format
   • draft: Set to true until ready to publish
   • description: 1-2 sentences summarising the post (used for SEO)
   • tags: Array of relevant keywords (use existing tags where possible)
   • categories: Optional grouping (e.g., "Tutorials", "Cloud Computing")
   • series: Optional series name if part of a multi-post series

3. Content Structure:

   • Use Markdown for content with ## (H2) and ### (H3) for sections
   • Store images in /static/images/YYYY/MM/ directory
   • Reference images with absolute paths (e.g., /images/2025/04/example.png)
   • Use UK English spelling and grammar

4. Testing:

   • Preview with hugo server -D to see drafts locally
   • Drafts will not be published to the live site

New Projects

hugo new content projects/project-name/index.md

Create a project directory to include additional assets like images and thumbnails.

Maintenance Scripts

The repository includes several maintenance scripts in the scripts/ directory:

• fix_backticks.py - Fixes inline code formatting issues in markdown files
• fix_twitter_links.py - Updates Twitter links from HTTP to HTTPS
• fix_links.py - Template for fixing various broken links

To run a script:

python3 -m venv venv                # Create virtual environment (first time only)
source venv/bin/activate            # Activate virtual environment
pip3 install -r requirements.txt    # Install dependencies (first time only)
python3 scripts/script_name.py      # Run the script

Building for Production

./scripts/hugo.sh --minify --buildFuture

This will generate the static site in the public directory.

Deployment

The site is automatically deployed to GitHub Pages using GitHub Actions when changes are pushed to the main branch. The workflow:

1. Builds the Hugo site using Hugo modules
2. Deploys the generated files to the gh-pages branch
3. GitHub Pages then serves the content from the gh-pages branch

To configure GitHub Pages:

1. Go to repository Settings > Pages
2. Set the source to "Deploy from a branch"
3. Select the "gh-pages" branch and "/" (root) folder
4. Save the settings

Note: The site uses two workflows - "Deploy Hugo site" builds the site, and "pages-build-deployment" handles the GitHub Pages publishing.

License

Shield:

My blog content, posts, etc are licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.