Moving the blog to a new technology, setting up pipeline and deploy.

Why change at all?

TLDR - I want to read my blog in a text only way

When I started writing the blog, I wanted make a serverless application running on AWS. That worked just fine and the application did almost everything that I wanted it to do. Some details needed to be finished, but the base was there: upload a markdown document, compile it to html page and display in a Vue.js responsive webpage.

Since then I got a new computer. Not exactly my main pc, but I love working on it - you can read more about it [here](/page/2023-11-17_A_cli_only_setup_for_my notes_pc/).

What does it have to do with the blog? As I run the computer in terminal only mode, I was not able to display the content of my blog in a browser in terminal, since the page needs client side javascript to render the page.

Configuring Hugo

The static site generator of my choice is Hugo. It is fast and simple enough to use.

Installation

The setup is as easy as snap install hugo or on macOS brew install hugo and I am pretty sure that windows has some almost as simple way of installing it too.

Creating a project

Creating a project is done using the command line tool we just installed:

hugo new site . --force

--force is needed to allow creating the site in current folder

You can find more options using hugo help new:

Create a new content file and automatically set the date and title.
It will guess which kind of file to create based on the path provided.

You can also specify the kind with `-k KIND`.

If archetypes are provided in your theme or site, they will be used.

Ensure you run this within the root directory of your site.

Usage:
  hugo new [command]

Available Commands:
  content     Create new content for your site
  site        Create a new site (skeleton)
  theme       Create a new theme (skeleton)

Flags:
  -h, --help   help for new

Global Flags:
      --clock string               set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
      --config string              config file (default is hugo.yaml|json|toml)
      --configDir string           config dir (default "config")
      --debug                      debug output
  -d, --destination string         filesystem path to write files to
  -e, --environment string         build environment
      --ignoreVendorPaths string   ignores any _vendor for module paths matching the given Glob pattern
      --logLevel string            log level (debug|info|warn|error)
      --quiet                      build in quiet mode
  -s, --source string              filesystem path to read files relative from
      --themesDir string           filesystem path to themes directory
  -v, --verbose                    verbose output

After creating the project, the next steps are clearly listed to you:

Congratulations! Your new Hugo site was created in /Users/username/folder/hugo-project.

Just a few more steps...

1. Change the current directory to /Users/username/folder/hugo-project.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

Installing a theme from https://themes.gohugo.io/

I choose the hugo-PaperMod template from https://github.com/adityatelange/hugo-PaperMod.

The installation is documented in the repo itself, so I will mention just the commands I needed to get going.

  1. Clone the template repo into themes folder:
git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

Add this repo as submodule to your main repo

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically)
  1. To specify the template in your hugo.toml file, append this line:
theme = "PaperMod"

Serving the page

Finally to see the page work, run

hugo server

Then navigate to http://localhost:1313 and see your page working. The server reloads automatically when you change the sources of your webiste.

Creating some content

Create a new page

hugo new content ./page/article.md

Creates article.md in content/page directory.

Building the page

Build your first sample page just by running the command:

hugo

This commands builds the site and places in into ./Public directory.

Add some markdown content to this file to test if everything works as expected.

Setting up a pipeline with github actions

As before I am going to use azure static web sites for the deployment. It can generate the whole pipeline automatically with preset for Hugo, but where is the fun in that…

My pipeline looks like this:

name: Pubild and publish Hugo app to Azure Static Web Apps  
  
on:  
  push:  
    branches:  
      - main  
  
jobs:  
  build_and_deploy_job:  
    runs-on: ubuntu-latest  
    name: Build and Deploy Job  
    steps:  
      - uses: actions/checkout@v4  # Clone the repository
        with:  
          submodules: true  # this is important to fetch your theme submodule
  
      - name: Install dependencies  
        run:  
          sudo apt update && sudo apt install -y snapd  
  
      - name: Install Hugo  
        run:  
          sudo snap install hugo  # Install Hugo
  
      - name: Build  
        run:
          hugo --minify  # Build the page
  
      - name: Build And Deploy 
        id: builddeploy  
        uses: Azure/static-web-apps-deploy@v1  
        with:  
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}  
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: "upload"
          app_location: "/public" # Specify location of built webisite

TIP: If you specify / instead of /public in app_location, the static-web-apps-deploy will detect that it is a Hugo project and build it for you.