@Summitt Dweller’s Personal Blog - Hugo

Rebranding CV to HAT with Pagefind

Mark McFate — Sat, 25 Jan 2025 08:43:21 -0600

Today I’m rebranding the Tama-Toledo Community Visioning (CV) site to Hometown Action Team (HAT) and adding Pagefind.

When doing so I get this build error…

Warning: Running in pre-1.0 compatibility mode. Pagefind 1.0 changes the default output directory from /_pagefind/ to /pagefind/ but references to the /_pagefind/ URL were found on your site, and the output directory is unconfigured. To preserve your setup, the search files have been written twice, to both /_pagefind/ and /pagefind/

To remove this warning, either update your script and style references to the new /pagefind/ URL or run Pagefind with --output-subdir _pagefind to ensure pre-1.0 behaviour

So, I am going to try changing all _pagefind references to just ‘pagefind’. Wish me luck

A Newer Pagefind Enabled Blog!

Mark McFate — Sun, 22 Dec 2024 10:43:32 -0600

It’s deja vu all over again. My timeline module doesn’t work with the current rendition of https://blog.SummittDweller.com and I can’t figure out what’s broken. So, I’ve resurrected my old personal blog project and updated with the meager content it was missing. That project has a working timeline but no Pagefind search, yet.

So, how might I ONCE AGAIN approach combining Hugo with Pagefind in the cloud? Well, A Powerful Blog Setup with Hugo and NPM* by Tom Hombergs looked like a promising place to start. The process that Tom advocates leverages a neat little package called hugo-bin.

*The links provided above and below are to a Wayback Machine capture of the original post.

Once Again…That Was Too Easy!

Wrapping this Hugo blog site in an NPM package was so easy that I forgot to document it… and maybe I really didn’t need too. Time to catch up, so here’s a brief sysnopsis of what I did…

Following Tom’s Excellent Advice

I started by studying A Powerful Blog Setup with Hugo and NPM and quickly found that I could easily follow it almost verbatim. Since I already had npm and Hugo installed I skipped ahead to the section titled “Setting Up a Hugo Project” and then to the npx and git commands there. My experience, mostly in commands, looked like this on my Mac Mini workstation.

  cd ~/GitHub/
  # Named the new project npm-blog-SummittDweller so it would not confilct with any of my existing `blog...` directories
  mkdir npm-blog-SummittDweller
  cd npm-blog-SummittDweller
  npx hugo new site . --force
  # Copied the contents of my old project into the new one and then removed whatever I no longer needed
  cp -fr ~/GitHub/blogs-SummittDweller/. .  
  # Installed Pagefind...
  npm install pagefind
  git init
  # I created a new empty repo in GitHub called npm-blog-SummittDweller, then...
  git remote add origin https://github.com/SummittDweller/npm-blog-sd 
  git add . 
  git commit -m "Initial commit of new npm-wrapped Hugo project"
  git push

Having secured a new repo I moved to running Hugo locally, then polishing my package.json scripts as Tom did. I now have a package.json that reads like this:

{
  "name": "npm-blog-sd",
  "version": "1.0.0",
  "description": "My personal (SummittDweller) blog built with Hugo inside an NPM package.  December 2024.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "npm run hugo:build && npx pagefind --site public",
    "do:build": "hugo -d public && npx pagefind --site public",
    "azure:build": "hugo -d public --baseURL=\"https://azure-static-web-apps-ashy-rock-0f18efc0f\" && npx pagefind --site public",
    "clean": "npm run hugo:clean",
    "serve": "npm run hugo:build && npx pagefind --site public --output-subdir ../static/_pagefind && npm run hugo:serve",
    "hugo:build": "hugo -d public",
    "hugo:serve": "hugo server",
    "hugo:clean": "rm -rf build resources public"
  },
  "author": "Mark A. McFate",
  "license": "ISC",
  "dependencies": {
    "hugo-bin": "^0.137.0",
    "pagefind": "^1.2.0"
  }
}

It Works!

Now I just use npm run serve to build the Hugo site, index it with Pagefind, and serve it locally at http://localhost:1313.

A Staging Site in Azure

I can simply push changes to the main branch of the npm-blog-sd repo to trigger an Azure (aka GitHub Actions) rebuild, indexing and deployment of the site to this address.

Errors?

So, it took lots of trial-and-error to get the Azure configuration straight. First there were issues with deployment tokens, so I rewound the project and got that fixed. Then, since this blog uses SASS I needed to run the extended version of Hugo, or more specifically, hugo-bin-extended. I fixed that, apparently, with the addition of…

  "dependencies": {
    "hugo-bin-extended": "latest",
    "pagefind": "^1.2.0"
  }

…in package.json. That hugo-bin-extended key replaced hugo-bin and I set the version to latest.

Last of the Errors?

The changes mentioned above left me with two deprecation errors…

ERROR deprecated: site config key paginate was deprecated in Hugo v0.128.0 and will be removed in Hugo 0.141.0. Use pagination.pagerSize instead.
WARN  Raw HTML omitted while rendering "/github/workspace/content/about.md"; see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe
You can suppress this warning by adding the following to your site configuration:
ignoreLogs = ['warning-goldmark-raw-html']
ERROR deprecated: .Site.Social was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.141.0. Implement taxonomy 'social' or use .Site.Params.Social instead.

This post was very helpful for working with my submodule theme!

Success!

Well, somewhat. My site at https://ashy-rock-0f18efc0f.4.azurestaticapps.net/ is visible now, but the theme isn’t right. I suspect that is because my hugo.yml file still sets the baseURL to “https://blog.summittdweller.com” and we are not quite there yet. Setting the baseURL to “https://ashy-rock-0f18efc0f.4.azurestaticapps.net/" and let’s see what happens… Bingo! Now, I just need to add a search bar to expose the Pagefind results. Done!

What follows is obsolete, it's from `npm-rootstalk`, and does NOT apply to this blog!

A New Production Branch

Pushing to production is just as simple, I just have to push changes to the new production branch of the code and my app spec at DigitalOcean (see below) takes care of building, indexing, and deploying to https://rootstalk.grinnell.edu.

That DO app spec reads like this:

alerts:
- rule: DEPLOYMENT_FAILED
- rule: DOMAIN_FAILED
domains:
- domain: rootstalk.grinnell.edu
  type: PRIMARY
- domain: prairiejournal.grinnell.edu
  type: ALIAS
envs:
- key: TZ
  scope: RUN_AND_BUILD_TIME
  value: America/Chicago
- key: HUGO_MATOMO_ID
  scope: RUN_AND_BUILD_TIME
  value: "15"
ingress:
  rules:
  - component:
      name: npm-rootstalk
    match:
      path:
        prefix: /
name: npm-rootstalk
region: nyc
static_sites:
- build_command: npm run build
  environment_slug: node-js
  github:
    branch: production
    deploy_on_push: true
    repo: Digital-Grinnell/npm-rootstalk
  name: npm-rootstalk
  source_dir: /

It’s heavenly! And that’s all for now.

A New Pagefind Enabled Blog!

Mark McFate — Wed, 18 Dec 2024 08:31:49 -0600

So, node and npm are maybe not “all the rage” these days, but they do the job nicely for me.

*The links provided above and below are to a Wayback Machine capture of the original post.

That Was Too Easy!

Wrapping this Hugo blog site in an NPM package was so easy that I forgot to document it… and maybe I really didn’t need too. Time to catch up, so here’s a brief sysnopsis of what I did…

Following Tom’s Excellent Advice

cd ~/GitHub/
# Named the new project npm-blog-sd so it would not confilct with any of my existing `blog...` directories
mkdir npm-blog-sd
cd npm-blog-sd
npx hugo new site . --force
# Copied the contents of my old project into the new one and then removed whatever I no longer needed
cp -fr ~/GitHub/blog-sd/. .  
# Installed Pagefind...
npm install pagefind
git init
# I created a new empty repo in GitHub called npm-blog-sd, then...
git remote add origin https://github.com/SummittDweller/npm-blog-sd 
git add . 
git commit -m "Initial commit of new npm-wrapped Hugo project"
git push

Having secured a new repo I moved to running Hugo locally, then polishing my package.json scripts as Tom did. I now have a package.json that reads like this:

{
  "name": "npm-blog-sd",
  "version": "1.0.0",
  "description": "My personal (SummittDweller) blog built with Hugo inside an NPM package.  December 2024.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "npm run hugo:build && npx pagefind --site public",
    "do:build": "hugo -d public && npx pagefind --site public",
    "azure:build": "hugo -d public --baseURL=\"https://azure-static-web-apps-ashy-rock-0f18efc0f\" && npx pagefind --site public",
    "clean": "npm run hugo:clean",
    "serve": "npm run hugo:build && npx pagefind --site public --output-subdir ../static/_pagefind && npm run hugo:serve",
    "hugo:build": "hugo -d public",
    "hugo:serve": "hugo server",
    "hugo:clean": "rm -rf build resources public"
  },
  "author": "Mark A. McFate",
  "license": "ISC",
  "dependencies": {
    "hugo-bin": "^0.137.0",
    "pagefind": "^1.2.0"
  }
}

It Works!

Now I just use npm run serve to build the Hugo site, index it with Pagefind, and serve it locally at http://localhost:1313.

A Staging Site in Azure

I can simply push changes to the main branch of the npm-blog-sd repo to trigger an Azure (aka GitHub Actions) rebuild, indexing and deployment of the site to this address.

Errors?

  "dependencies": {
    "hugo-bin-extended": "latest",
    "pagefind": "^1.2.0"
  }

…in package.json. That hugo-bin-extended key replaced hugo-bin and I set the version to latest.

Last of the Errors?

The changes mentioned above left me with two deprecation errors…

ERROR deprecated: site config key paginate was deprecated in Hugo v0.128.0 and will be removed in Hugo 0.141.0. Use pagination.pagerSize instead.
WARN  Raw HTML omitted while rendering "/github/workspace/content/about.md"; see https://gohugo.io/getting-started/configuration-markup/#rendererunsafe
You can suppress this warning by adding the following to your site configuration:
ignoreLogs = ['warning-goldmark-raw-html']
ERROR deprecated: .Site.Social was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.141.0. Implement taxonomy 'social' or use .Site.Params.Social instead.

This post was very helpful for working with my submodule theme!

Success!

What follows is obsolete, it's from `npm-rootstalk`, and does NOT apply to this blog!

A New Production Branch

That DO app spec reads like this:

alerts:
- rule: DEPLOYMENT_FAILED
- rule: DOMAIN_FAILED
domains:
- domain: rootstalk.grinnell.edu
  type: PRIMARY
- domain: prairiejournal.grinnell.edu
  type: ALIAS
envs:
- key: TZ
  scope: RUN_AND_BUILD_TIME
  value: America/Chicago
- key: HUGO_MATOMO_ID
  scope: RUN_AND_BUILD_TIME
  value: "15"
ingress:
  rules:
  - component:
      name: npm-rootstalk
    match:
      path:
        prefix: /
name: npm-rootstalk
region: nyc
static_sites:
- build_command: npm run build
  environment_slug: node-js
  github:
    branch: production
    deploy_on_push: true
    repo: Digital-Grinnell/npm-rootstalk
  name: npm-rootstalk
  source_dir: /

It’s heavenly! And that’s all for now.

Microposts from iOS

Mark McFate — Sun, 10 Nov 2024 10:22:33 -0600

Wow, this post is long overdue.

For as long as I can remember I’ve been looking for, or building and using, a workflow that would let me create quick and simple microposts for this blog using my iPhone. I want that workflow to automatically record my location (in the form of a city/town reference) and date/time. With the help of my daughter, Mackenzie, I’ve had workflows that used Working Copy and iOS Shortcuts to get this done, but I never really understood the entire process and over time it broke down and I was unable to repair it. It’s time to revisit those pieces and I’m going to follow, and document here, the steps and components presented in Post to Eleventy from iOS with Drafts, Shortcuts and Working Copy. The only change I anticipate will be pointing the workflow at this Hugo blog rather than an Eleventy one, and those differences should be minimal and manageable.

A Pagefind Problem?

Mark McFate — Wed, 10 May 2023 14:33:09 +0000

Not Just a Hugo Issue

Take note of the question mark at the end of the title, otherwise it could be somewhat misleading. This is not really a problem with Hugo, but one with cloud deployment of Hugo static apps, particularly as an Azure Static Web App.

The Nutshell

As you may know from post 143, I have successfully installed and configured Pagefind in Rootstalk, but thus far it only works locally. When I try to deploy Pagefind to the cloud, specifically as an Azure Static Web App, I can’t make it work because there’s no apparent way to invoke the necessary npx pagefind... command AFTER Hugo compiles the site, but BEFORE the site gets deployed. Azure leverages GitHub Actions to build Hugo sites, but that process also involves some custom/proprietary Azure scripts. Therein lies the problem.

The Azure script auto-detects the presence of a Hugo project, or any one of many other platforms. That makes the process super-easy to use, but nearly impossible to “customize”. Azure does provide some configuration variables to influence the script behavior, most notably there’s an app_build_command variable that looks promising, but it only works for node builds, and not for Hugo.

Three Possible Solutions

I can reasonably see three possible solutions to this dilema. In order of simplicity they are:

1. Skip Azure and Deploy Only to DigitalOcean

Ultimately, Rootstalk’s production instance is a DigitalOcean (DO) static web app, Azure is only used for “staging” of a locally viable Rootstalk instance. DO doesn’t use GitHub Actions, a drawback in my book, so its build script, called an “App Spec” in DO, is a little more “open”. The critical portion of the App Spec I use to deploy Rootstalk in DO reads like this:

static_sites:
- build_command: hugo -d public

That’s it, just a simple hugo -d public command. So, in theory I should be able to just change that to read:

static_sites:
- build_command: hugo -d public && npm_config_yes=true npx pagefind --source "public" --bundle-dir ../static/_pagefind

It’s basically just a “compound” command to run npx immediately after hugo is done compiling.

The problem with this very simple solution, assuming it even works, is that it’s somewhat unique to Rootstalk which is already deployed to DigitalOcean. Other Hugo projects, and I have many like this blog, that need Azure or another cloud provider other than DO, would not benefit from this fix.

Update 12-May-2023: Same Problem Exists in DigitalOcean

Well, I tried. I attempted to push my Pagefind additions to Rootstalk forward directly into production on DigitalOcean. Unfortunately, that failed in similar fashion to what I saw in Azure. It all works locally, but DigitalOcean, like Azure, has no way of “detecting” that my Hugo project has an NPM component, and therefore takes no steps to build NPM or Pagefind into my solution.

So, I’m moving on to option #2 below. Wish me luck.

2. Wrap Hugo in `npm`

So, node and npm seem to be all the rage these days, and perhaps for good reason. I recently fell in love with Eleventy/11ty because it’s Javascript, not Go, and it’s elegantly simple with tons of flexibility. If my Azure Static Web App was framed in node.js, as both Eleventy and Pagefind are, there would be no problem. The Azure scripts used to deploy those frameworks are far more customizable than Hugo, and there’s documentation to prove it.

So, how might I approach something like this? Well, A Powerful Blog Setup with Hugo and NPM by Tom Hombergs looks like a promising place to start. The process that Tom advocates leverages a neat little package called hugo-bin.

If strategy #1 fails I’ll certainly give this #2 a try. Even if #1 works, I might give this strategy a spin if/when I re-tool this blog.

Update 29-May-2023: NPM is GREAT!

Since my first option (above) failed very quickly, I moved on to this option and I honestly think I might transition every static site that I have to be wrapped inside NPM, it works wonderfully and is a really attractive solution for so many ills!

I’m going to document my experience with NPM wrapped around Hugo and will post that document here soon, probably as Wrap EVERYTHING in NPM!.

3. Transition from Hugo to Eleventy

Reasonable? Yes. A lot of work? That’s relative. The right thing to do? Probably.

So, it’s already been done, see This Blog in Eleventy + Ghost and Searching for a Search Solution. That’s all I’m going to say about this option, a definite maybe.

That’s all folks… for now.

Wrapping Hugo in NPM

Mark McFate — Tue, 09 May 2023 23:13:09 +0000

I ran into a big road block with implementation of Pagefind in Rootstalk today… everything works fine in development, but I can’t easily deploy to Azure because there’s no way to “inject” Pagefind into an Azure Static Web App build before the “public” content gets deployed. I can generate the Pagefind parts after deployment, but that does me no good.

Tomorrow I need to have a look at my Rootstalk DigitalOcean deployment to see if what I already have might work there (DO uses a build script that I can add an npx... command to). If that fails I need to look back at https://www.blogtrack.io/blog/powerful-blog-setup-with-hugo-and-npm/ to see if there’s a solution there for me.

-/-/-/

location: Toledo, IA

My Hugo Timeline, A New Hugo Module

Mark McFate — Tue, 06 Dec 2022 13:30:13 -0600

What follows is an excerpt from this blog’s README.md file.

I’ve successfully added the code to drive a new /timeline page as part of this blog, but I did so “locally”, and now I’d like to repeat the process but using the aforementioned SummittDweller/hugo-timeline module.

I used guidance found in Hugo Modules: Getting Started to make this happen, like so:

╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main› 
╰─$ brew install go
╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main› 
╰─$ brew upgrade   # This is not "required", but probably overdue.

╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main*› 
╰─$ mkdir content/timeline/.out-of-the-way      # vvv Moving existing local stuff out of the way vvv
╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main*› 
╰─$ mv -f layouts/partials/hugo-timeline* content/timeline/.out-of-the-way/.   
╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main*› 
╰─$ mv -f layouts/shortcodes/hugo-timeline* content/timeline/.out-of-the-way/.
╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main*› 
╰─$ mv -f static/css/hugo-timeline* content/timeline/.out-of-the-way/.        

╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main*› 
╰─$ hugo mod init github.com/SummittDweller/blogs-SummittDweller        
go: creating new go.mod: module github.com/SummittDweller/blogs-SummittDweller
go: to add module requirements and sums:
        go mod tidy

Next, to pull in SummittDweller/hugo-timeline as a module I turned to the config.yml file and guidance found in Hugo Modules: everything you need to know!. Additions to config.yml are:

module:
  imports:
    - path: github.com/SummittDweller/hugo-timeline
      mounts:
      - source: layouts
        target: layouts
      - source: static
        target: static

Updating the Module

So, all of the above moves appeared to work correctly, at least locally, but I wanted to be sure I can successfully update the hugo-timeline module and get updated behavior in this project. The command required to make that happen per Hugo Modules: everything you need to know! is:

╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main*› 
╰─$ hugo mod get -u github.com/SummittDweller/hugo-timeline
go: downloading github.com/SummittDweller/hugo-timeline v0.0.0-20221206191252-cd7178e7e43b
go: upgraded github.com/SummittDweller/hugo-timeline v0.0.0-20221206043330-5f1ecbad913f => v0.0.0-20221206191252-cd7178e7e43b

╭─mark@Marks-Mac-Mini ~/GitHub/blogs-SummittDweller ‹main*› 
╰─$ hugo server
port 1313 already in use, attempting to use an available port
Start building sites … 
hugo v0.107.0+extended darwin/amd64 BuildDate=unknown

                   | EN   
-------------------+------
  Pages            | 288  
  Paginator pages  |   9  
  Non-page files   |   0  
  Static files     |  38  
  Processed images |   0  
  Aliases          |  79  
  Sitemaps         |   1  
  Cleaned          |   0  

Built in 90 ms
Watching for changes in /Users/mark/GitHub/blogs-SummittDweller/{archetypes,content,layouts,static,themes}
Watching for config changes in /Users/mark/GitHub/blogs-SummittDweller/config.yaml, /Users/mark/GitHub/blogs-SummittDweller/go.mod
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:62846/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Eureka! The page rendered at http://localhost:1313/timeline/ after the above hugo mod get -u... command is displaying the latest changes I made to hugo-timeline! Perfect!

My work here is done, well, for now anyway. 😁

@Summitt Dweller’s Personal Blog - Hugo

Rebranding CV to HAT with Pagefind

A Newer Pagefind Enabled Blog!

Once Again…That Was Too Easy!

Following Tom’s Excellent Advice

It Works!

A Staging Site in Azure

Errors?

Last of the Errors?

Success!

A New Production Branch

A New Pagefind Enabled Blog!

That Was Too Easy!

Following Tom’s Excellent Advice

It Works!

A Staging Site in Azure

Errors?

Last of the Errors?

Success!

A New Production Branch

Microposts from iOS

A Pagefind Problem?

Not Just a Hugo Issue

The Nutshell

Three Possible Solutions

1. Skip Azure and Deploy Only to DigitalOcean

Update 12-May-2023: Same Problem Exists in DigitalOcean

2. Wrap Hugo in npm

Update 29-May-2023: NPM is GREAT!

3. Transition from Hugo to Eleventy

Wrapping Hugo in NPM

My Hugo Timeline, A New Hugo Module

Updating the Module

2. Wrap Hugo in `npm`