me.micahrl.com til

Run Squid on exit nodes

Wed, 17 Dec 2025 21:15:00 -0600

I have a Hetzner VPS that I use as a Tailscale exit node for, among other things, circumventing geolocation blocks. This works great for that purpose, but causes problems with sites like Reddit, imgur, CloudFlare, and Google, which limit or block IPs from datacenters like Hetzner’s. I can only turn the exit node on or off for all traffic, not just some apps or tabs, so I have to toggle it on and off all the time. Annoying.

The other day I realized that Squid fits very nicely into this problem. The exit node already trusts that other nodes on the encrypted tailnet are authorized and tunnels traffic for them without caching by design. If I added a regular unauthenticated non-caching HTTP proxy that listened exclusively on the Tailscale address this wouldn’t open up any security holes and would be extremely simple to configure.

And the key: applications can often be configured individually to use a proxy server or not, so unlike the exit node, I can run a proxied application and/or browser profile on the same device as an unproxied one.

How to

I deployed Squid to my exit node with this configuration:

Squid configuration file

# Squid configuration for a Tailscale open proxy

# Replace 100.x.y.z with the Tailscale IP address
http_port 100.x.y.z:3128

# Only allow traffic from the Tailscale CGNAT range
acl pprox_allow_net src 100.64.0.0/10

# Safe ports (standard ports we allow CONNECT to)
acl SSL_ports port 443
acl Safe_ports port 80
acl Safe_ports port 443

acl CONNECT method CONNECT

# Deny requests to unsafe ports
http_access deny !Safe_ports
# Deny CONNECT to non-SSL ports
http_access deny CONNECT !SSL_ports

# Allow requests from pprox_allow_net network
http_access allow pprox_allow_net

# Deny all other access
http_access deny all

# Disable caching
cache deny all
cache_mem 0 MB
maximum_object_size 0 KB

# Enable logging if you need it
#access_log daemon:/var/log/squid/access.log
#cache_log /var/log/squid/cache.log

# Disable via header to be more transparent
via off

Here’s a simple example with curl, using your exit node’s MagicDNS name:

# Get the public IP address from my ISP
curl https://icanhazip.com

# Get the public IP address of my exit node
curl -x http://MACHINE.TAILNET.ts.net:3128 https://icanhazip.com

I wrote an ansible role to deploy this to my exit node (tip of master, specific commit).

Application support

Most applications can configure their own proxies:

Firefox connection settings are set per-profile
Chrome with the FoxyProxy extension can configure a proxy, and Chrome extensions are inherently per-profile
iCab Mobile for iOS can set a proxy of its own, separate from other apps
curl can use a proxy via the HTTP_PROXY= environment variable or -x command line flag
youtube-dl can use a proxy via the --proxy command line flag

Caveats

Some applications, including Safari on macOS and iOS, cannot set proxies independent of the system
This only works for normal HTTPS TCP-over-443 traffic like HTTPS 1.1, HTTP/2, and WebSockets; it cannot handle other traffic like QUIC HTTP/3, WebRTC (often used for telephony), or WebTorrent.

Write a comment on the original post.

git-lfs-transfer

Sat, 13 Dec 2025 08:20:06 -0600

While “the future of large files in git is git”, the present of large files in git is still something like git-lfs.

One of git’s selling points to me is its distributed nature, and the ease of setting up a simple server with sshd. I am happy to pay GitHub to handle hosting and CI because I’m not locked in there — I can and have switched repos away to personal hosting and other forges and then back again to GitHub. But git-lfs breaks this: one you have files tracked in LFS, you can only push to other git servers that provide LFS, which for self-hosting means something more complicated than a simple SSH server.

Or so I thought, until I discovered git-lfs-transfer, which can be installed on the server to provide git LFS hosting over ssh. This program has two implementations I’m aware of:

bk2204/scutiger, in Rust, is the original and reference implementation
charmbracelet/git-lfs-transfer, is a Go port

I found these today when I needed to work with an LFS-enabled repository in my Claude Code prison. This VM happened to have Go tooling already installed, so I used the charmbracelet port.

I ran this on the server:

sudo dnf install git-lfs
go install github.com/charmbracelet/git-lfs-transfer@latest
sudo cp ~/Documents/Go/bin/git-lfs-transfer /usr/local/bin/
sudo chmod 755 /usr/local/bin/git-lfs-transfer

Then on the client I could:

# Using ssh:// URLs may be a requirement, see below
git remote add REMOTE ssh://USER@HOST/path/to/repo.git
# Yes, the https:// is reequired for this, probably a holdover from previous HTTP-only LFS implementation
git config lfs.https://HOST/path/to/repo.git/info/lfs.locksverify false

After that, pushing my LFS-enabled git checkout to my server worked perfectly from the client. No HTTP required!

Troubleshooting & references

This requires git-lfs 3.0 or newer
Git over ssh does not execute your shell before running commands, so any $PATH configuration that includes Go or Rust bin directories doesn’t get applied. For me this just included /usr/bin and /usr/local/bin. See it with ssh USER@HOST 'echo $PATH'.
If you see an error message related to a missing git-lfs-authenticate binary, that means that using git-lfs-transfer has failed for some reason. git-lfs-authenticate is the normal way that forges enable pulling large files from their HTTP servers, and because it’s forge-specific, there is no generic implementation shipped with git-lfs. If git-lfs-transfer fails (or is not in the $PATH, or your git-lfs version is too old, etc), it will fall back to git-lfs-authenticate. (Some details in this comment.)
It may be necessary to use ssh://USER@HOST/path/to/repo.git remote URIs rather than USER@HOST:/path/to/repo.git style.
As far as I know, the two git-lfs-transfer implementations don’t have a way to support LFS locks. LFS locks are an optional coordination feature for preventing simultaneous edits of the same file. If you don’t explicitly disable it as shown above, git will warn you on every push that it isn’t supported.
git-lfs has a little hack for pushing to repos on the local filesystem, so git push /path/to/wherever.git should work just fine even if your working copy is LFS-enabled

Write a comment on the original post.

Hugo non-page HTML resource

Sat, 06 Dec 2025 10:00:00 -0600

I use Hugo on this site, which automatically processes HTML and Markdown files in page bundles. So for instance, content/blog/first-post/index.html isn’t copied verbatim to the site output, but it is templated with my theme and so forth. Hugo does this automatically with all HTML and Markdown files.

But sometimes I need to copy an HTML or Markdown file verbatim to the output — for instance, if the HTML file was prepared outside of Hugo to be standalone, where Hugo’s templating might interfere with proper display. One example is this slide show from a talk I gave (over ten years ago now!). It uses HTML Slidy, which gets broken by Hugo’s templating.

Hugo doesn’t have a natural way to allow for this, but it is powerful enough to let you build one. tl;dr include this in the template that renders your page¹:

{{- /* Allow a page to provide a list of Resources that would normally be procseed as Pages.
<https://github.com/gohugoio/hugo/issues/12274#issuecomment-2640061092>
*/ -}}
{{- with .Params.ResourcesPassthru -}}
  {{- range . -}}
    {{- $res := $.Resources.Get . -}}
    {{- $publishPath := urls.JoinPath $.RelPermalink $res.Name -}}
    {{- ($res.Content | resources.FromString $publishPath).Publish -}}
  {{- end -}}
{{- end -}}

This allows a page to provide a parameter called ResourcesPassthru containing filenames. For example:

params:
  ResourcesPassthru:
  - livecd.html

Any files listed in that parameter are copied directly to the output without any templating.

Alternative

The easiest thing to do, which doesn’t require any customization at all, is to place the file in static so it gets copied over without any templating. I didn’t like this because it separates the page content from the resources it relies on.

References

A comment from Hugo developer jmooring about how to accomplish this for all HTML files, which I adapted to take a parameter instead

I put this in my baseof.html so that any page can use it. ↩︎

Write a comment on the original post.

Hugo render templates for links

Fri, 28 Nov 2025 06:30:00 -0600

I learned recently that Hugo considers the ref and relref shortcodes “obsolete” for use in Markdown files. This surprised me as I have been using them on this site and others for many years. Instead, we should use render hooks. Note that this is limited to Markdown only; ref and relref continue to be necessary for HTML and other kinds of input files.

The result is just regular Markdown that’s more portable to other renderers, and it’s shorter and looks nicer when editing as well.

Hugo now ships simple render templates for links and images, and uses them by default under some circumstances (see the duplicateResourceFiles setting).

This post is about links, but render hooks are also used for blockquotes, code blocks, headings, and tables; see the docs for these.

Validating links with render hooks

When using ref, it will emit an error if that ref doesn’t resolve to a content page. I rely on this to make sure I’m not linking to nonexistent pages on my own site. The default render hooks do not do this (yet) but you can add customizations to do so. I am using these hooks from jmooring, one of the Hugo maintainers, which do extensive validation. (They even validate that anchor tags actually link to an ID on the page now!)

Switching to render hooks

I switched to using render hooks earlier this week. I started with this (uses macOS sed):

# Convert all {{< ref 'some/thing' >}} to {{ ref "some/thing" }}
# Ensure that consistent spacing is enforced: one space after < and before >
find content -type f -name '*.md' -exec sed -i ''  's/{{< ?ref "?\([^"]*\)"? ?>}}/\1/g' {} +
find content -type f -name '*.md' -exec sed -i ''  's/{{< ?relref "?\([^"]*\)"? ?>}}/\1/g' {} +

# Convert all {{< ref "/some/thing" >}} to /some/thing
# Also handle unquoted paths
find content -type f -name '*.md' -exec sed -E -i '' 's/{{<[[:space:]]*(relref|ref)[[:space:]]*"([^"]*)"[[:space:]]*>}}/\2/g' {} +

This required some manual fixes because the lookup rules for ref vs the render hook are different. I used the errors from the jmooring render hook to show me what needed to be changed.

Intentionally linking to pages that cannot be validated

Sometimes with render hooks you might want to intentionally link to a page that can’t be validated when the site builds, like the 404 page, the RSS feed or sitemap, etc.

When I was using ref for most links, I just used regular Markdown links for these non-validatable links, e.g. [RSS feed](/rss.xml). But when using validating render hooks, this will fail.

There are two solutions:

Use HTML links instead of native Markdown links, like <a href=https://testcom.micahrl.me/rss.xml>RSS feed</a>. This is the method I’m using. I’m adding an attribute data-linkcheck-exempt to indicate that the link is HTML to bypass validation, like <a data-linkcheck-exempt href=https://testcom.micahrl.me/rss.xml>RSS feed</a>. One downside of this method is that it requires permitting HTML in your Markdown files with unsafe = true.
Modify the render hook to skip validation if the link contains a certain query string like [RSS feed](/rss.xml?validate=false). This is probably a nicer solution for the general case. jmooring suggested it on the Hugo forums.

If render hooks are enabled, use `%` for shortcodes

You can enable render hooks and continue to use the ref shortcode, but there is one caveat: you have to convert ref and any other shortcodes in Markdown links to the % syntax.

Ok	`[click here]({{% ref "blog" %}})`
Broken	~~`[click here]({{< ref "blog" >}})`~~

The < style shortcodes cause the render hook to see values like HAHAHUGO‍SHORTCODE858s1HBHB as the link destination. This means any validation that inspects the link destination will not work as expected. The % style shortcodes get handled properly by render hooks.

This applies to all shortcodes, not just ref — if you have anything custom like [click here]({{< yourCustomShortCode >}}), you’ll need to convert that to the % version too.

A note on `HAHAHUGO‍SHORTCODE` placeholder values

You cannot include this string anywhere in your site, even Markdown content, or Hugo will fail to build with an error

illegal state in content; shortcode token missing end delim

I’m including it above with an invisible space, literally <code>HAHAHUGO&zwj;SHORTCODE</code>, so that it doesn’t cause this problem. If you select and copy that text, you’ll also copy that zwj character. If you paste it into the terminal you’ll get something like:

> printf 'HAHAHUGO<200d>SHORTCODE' | xxd
00000000: 4841 4841 4855 474f e280 8d53 484f 5254  HAHAHUGO...SHORT
00000010: 434f 4445                                CODE

As discussed in #7416, Hugo didn’t always check for this, and sometimes the placeholder could sneak into production sites, especially as Hugo shipped new releases that changed behavior.

Write a comment on the original post.

hugo deploy, S3, and CloudFront

Thu, 20 Nov 2025 06:00:00 -0500

tl;dr: don’t set gzip = true (see docs) when using hugo deploy to deploy a site to S3 and CloudFront under normal assumptions.

With gzip = true, hugo will write files that are already compressed; e.g. index.html on S3 will be a binary gzip’d file.

The thing is that this will mostly work fine for you in the browser, but will have some surprising behavior with curl. This is because browsers always send an Accept-Encoding: gzip, br, deflate, ... header, and are happy to receive gzip data in response, but curl will only send such a header with the --compressed flag passed, and will not transparently decompress the response even if the server properly provides the Content-Encoding: gzip header, and so will show you a warning about binary content if you try to send the result to a terminal:

> curl 'https://example.com/index.html'
Warning: Binary output can mess up your terminal. Use "--output -" to tell curl to output it to your terminal anyway, or consider "--output <FILE>" to save to a file.

You don’t need to compress the files before uploading to serve them compressed. CloudFront can transparently handle compression for you based on the client’s Accept-Encoding header via the Compress option. This also has the benefit of supporting other forms of compression like brotli.

Depending on what you’re trying to do, it may not be “wrong” to compress files with gzip before placing them in S3 and just require clients to deal with it, but allowing both compressed and uncompressed requests are the norm for the Web, so your site will be less surprising if you allow both.

Write a comment on the original post.

Pin prettier

Mon, 16 Jun 2025 07:00:00 -0500

tl;dr: Pin the prettier version you use for each project.

I recently discovered that running prettier from the command line was applying different formatting rules than when run from VS Code on save. After ruling out a few possible causes:

.prettierrc is setting the same things as VS Code settings
I don’t have any other formatters configured in VS Code

… I found the problem was that I was actually running two different versions. I hadn’t installed prettier as a project dependency, so when I ran it from the a package.json script like bun x --bun prettier --write "src/**/*.{ts,js,json,css,html}", I was getting whatever bun pulled down (probably the latest), while the VS Code extension bundles its own version.

Once I saved it as a dev dependency with a pinned version number (bun add -ED prettier or npm install -D --save-exact prettier), the extension and the script used the same version, which apply the same rules.

The VS Code extension helpfully describes how it selects which one to use:

This extension will use prettier from your project’s local dependencies (recommended). When the prettier.resolveGlobalModules is set to true the extension can also attempt to resolve global modules. Should prettier not be installed locally with your project’s dependencies or globally on the machine, the version of prettier that is bundled with the extension will be used.

Which, btw, each prettier release changes the formatting rules. Release notes are posed on the prettier blog. I don’t care at all about the specifics of the rules — that’s why prettier works for me in the first place — but I do want to pin the version so I have consistent formatting until I upgrade intentionally.

(This annoyed me on a low level until I started experimenting with Copilot agent mode opening PRs, when it became more disruptive. Agents can’t pick up precise formatting rules from your codebase by osmosis in any case, but when working with agents like Claude Code locally I tend to at least lightly edit their output before committing, and when doing so VS Code’s format-on-save kicks in and prettier runs then. But when the agent is opening a PR, my editor usually won’t see it until it’s merged to master, which leads to incorrect formatting sticking around until the next time I edit the file locally, at which point the whole thing gets reformatted.)

Write a comment on the original post.

Bash networking redirects

Sun, 08 Jun 2025 22:00:00 -0500

I recently read instructions that surprised me. Paraphrased:

You can send messages over UDP:
echo -n "message" | nc -4u -w0 localhost 1738
Or if you use bash, you might prefer this instead:
bash -c 'echo -n "message" > /dev/udp/localhost/1738'

/dev/udp? That doesn’t look bash-specific. How did I miss that this was available as a device on Unix? Wait a second…

$ echo -n message > /dev/udp/localhost/1738
zsh: no such file or directory: /dev/udp/localhost/1738

No, this is truly a bash feature, not a generic shell one. In fact, UDP in particular seems to be completely unique to bash — zsh has a module that provides TCP networking, but no similar module for UDP networking.

It seems almost perverse. There is no /dev/udp directory (or device) at all in the filesystem, bash just intercepts any attempt to redirect to it and does networking stuff transparently. Although maybe it’s not perverse and redirection is just weirder than I thought it was. From the previously linked bash manual:

Bash handles several filenames specially when they are used in redirections, as described in the following table. If the operating system on which Bash is running provides these special files, bash will use them; otherwise it will emulate them internally with the behavior described below.

The table lists more than just networking: aside from /dev/udp/HOST/PORT and /dev/tcp/HOST/PORT, it includes /dev/fd/FD, /dev/stdin, /dev/stdout, and /dev/stderr.

This lead me to realize that these too are not POSIX! The string /dev/fd doesn’t exist at all in the online POSIX documentation, and the others are specifically called out as extensions:

The system may provide non-standard extensions. These are features not required by POSIX.1-2017 and may include, but are not limited to: … Additional character special files with special properties (for example, /dev/stdin, /dev/stdout, and /dev/stderr)

At least on my macOS desktop, the /dev/std* and /dev/fd/* devices to actually exist, so bash wouldn’t do anything special for redirection to those paths. But even the ancient bash from 2007 (!) that ships with macOS will happily talk to the special networking “device” paths.

$ /bin/bash --version
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin24)
Copyright (C) 2007 Free Software Foundation, Inc.
$ /bin/bash -c 'echo -n message > /dev/udp/localhost/1738'
$ echo $?
0

Prescriptions

Being a POSIX sh purist, I can’t endorse this for lay shell scripting, but it seems really interesting as a tool for fixing very broken systems, bootstrapping very barebones systems, and penetration testing.

Other references

Write a comment on the original post.

Writing docs for Hammerspoon spoons

Sat, 07 Jun 2025 08:55:00 -0500

A few notes on documentation for Hammerspoon Spoons that I took as I was writing GridCraft and the Hammerspoon docs.json content adapter for it.

First, read the Spoon docs on writing Spoon docs. This shows an example of the basic format of the documentation comments.

Documentation generation

There are two processes you should understand:

Using genJSON:
```
hs -c "hs.doc.builder.genJSON(\"$(pwd)\")" | grep -v "^--" > docs.json
```
This will generate docs.json only.

It looks through all Lua (and ObjC) files in the passed directory recursively, so make sure that doesn’t include anything you don’t want docs for.

It does some basic checking, but doesn’t show which file has an error.

It requires the hs command-line tool installed but nothing else.
Using build_docs.py:
```
hammerspoondir=/path/to/hammerspoon/checkout
docsout=dist/docs
src="$pwd"
python "$hammerspoondir/scripts/docs/bin/build_docs.py" \
  --standalone \
  --templates "$hammerspoondir/scripts/docs/templates" \
  --output_dir "$docsout" \
  --json \
  --html \
  --markdown \
  --standalone \
  "$src"
```
This requires the hs cli tool installed, as well as a local checkout of the Hammerspoon source code and various Python dependencies installed.

It does more checking and shows more detailed errors including which lines contain problems for the docstring parser.

It builds HTML documentation, but unfortunately for my purposes it isn’t really suitable for hosting anywhere except on the official https://hammerspoon.org site.

Docstring format

Some notes on the docstring format:

Docstrings must start with 3 dashes and a space
Bullets must start with an additional space, so three dashes + two spaces
Sections like Parameters/Notes/etc must end with a colon
Section content must not contain any blank lines

Examples

The most helpful things I found for writing Hammerspoon docs were examples and parsing code in the Hammerspoon repo itself.

`hs.window.layout:setScreenConfiguration()`

hs.window.layout:setScreenConfiguration(screens) shows a method with parameters, returns, notes, and examples sections.

Documentation comment for the method

--- hs.window.layout:setScreenConfiguration(screens) -> hs.window.layout object
--- Method
--- Determines the screen configuration that permits applying this windowlayout
---
--- Parameters:
---  * screens - a map, where each *key* must be a valid "hint" for `hs.screen.find()`, and the corresponding
---    value can be:
---    * `true` - the screen must be currently present (attached and enabled)
---    * `false` - the screen must be currently absent
---    * an `hs.geometry` point (or constructor argument) - the screen must be present and in this specific
---      position in the current arrangement (as per `hs.screen:position()`)
---
--- Returns:
---  * the `hs.window.layout` object
---
--- Notes:
---  * If `screens` is `nil`, any previous screen configuration is removed, and this windowlayout will be always allowed
---  * For "active" windowlayouts, call this method *before* calling `hs.window.layout:start()`
---  * By using `hs.geometry` size objects as hints you can define separate layouts for the same physical screen at different resolutions
---  * With this method you can define different windowlayouts for different screen configurations (as per System Preferences->Displays->Arrangement).
---  * For example, suppose you define two "graphics design work" windowlayouts, one for "desk with dual monitors" and one for "laptop only mode":
---    * "passive mode" use: you call `:apply()` on *both* on your chosen hotkey (via `hs.hotkey:bind()`), but only the appropriate layout for the current arrangement will be applied
---    * "active mode" use: you just call `:start()` on both windowlayouts; as you switch between workplaces (by attaching or detaching external screens) the correct layout "kicks in" automatically - this is in effect a convenience wrapper that calls `:pause()` on the no longer relevant layout, and `:resume()` on the appropriate one, at every screen configuration change
---
--- Examples:
--- ```lua
--- local laptop_layout,desk_layout=... -- define your layouts
--- -- just the laptop screen:
--- laptop_layout:setScreenConfiguration{['Color LCD']='0,0',dell=false,['3840x2160']=false}:start()
--- -- attached to a 4k primary + a Dell on the right:
--- desk_layout:setScreenConfiguration{['3840x2160']='0,0',['dell']='1,0',['Color LCD']='-1,0'}:start()
--- -- as above, but in clamshell mode (laptop lid closed):
--- clamshell_layout:setScreenConfiguration{['3840x2160']='0,0',['dell']='1,0',['Color LCD']=false}:start()
--- ```

`logger.lua` examples

logger.lua shows that the doc comments can be found anywhere, not necessarily right next to their code.

An excerpt of some doc strings

--- hs.logger.setLogLevel(loglevel)
--- Method
--- Sets the log level of the logger instance
---
--- Parameters:
---  * loglevel - can be 'nothing', 'error', 'warning', 'info', 'debug', or 'verbose'; or a corresponding number between 0 and 5
---
--- Returns:
---  * None

--- hs.logger.getLogLevel() -> number
--- Method
--- Gets the log level of the logger instance
---
--- Parameters:
---  * None
---
--- Returns:
---  * The log level of this logger as a number between 0 and 5

Explanation of types of doc strings in `module.lp`

module.lp is a Lua template file of some kind, which explains what the different types of doc strings are.

A list of the different types of doc strings

local sectionorder = { "Deprecated", "Command", "Constant", "Variable", "Function", "Constructor", "Field", "Method" }
local sectiondetails = {
  ["Deprecated"]  = "API features which will be removed in an upcoming release",
  ["Command"]     = "External shell commands",
  ["Constant"]    = "Useful values which cannot be changed",
  ["Variable"]    = "Configurable values",
  ["Function"]    = "API calls offered directly by the extension",
  ["Constructor"] = "API calls which return an object, typically one that offers API methods",
  ["Field"]       = "Variables which can only be accessed from an object returned by a constructor",
  ["Method"]      = "API calls which can only be made on an object returned by a constructor",
}

Other files with docstring examples

Write a comment on the original post.

git note

Fri, 16 May 2025 22:00:00 -0500

Git needs a way to annotate previous commits, without changing their contents and force-pushing. It’s good that commits are immutable, but we need the ability to add more information to old commits much later.

For example, if last year I made a change and explained the reason in a commit message, and this year I realize that my reasoning was completely wrong, I want to be able to add a message for myself next year when I might be doing a git blame and finding the inaccurate explanation in last year’s message.

(It goes without saying that it’s possible to change that commit from last year and that doing so has other extremely inconvenient effects.)

And TIL that Git has had this feature for over 15 years, but that its implementation is fatally flawed.

git note was added in Git 1.6.6 which was released in 2009! And it’s still part of Git today. It lets you add annotations to previous commits, without changing their hash. Which is great!

Except:

Notes are not pushed or pulled by default.
Notes are not supported in certain major web UIs

Which is really too bad.

Writing notes

git notes add -m "Your note" SOME_SHA

You can also append to an existing note with git notes append.

Pushing and pulling

To push local notes:

git push origin 'refs/notes/*'

To pull notes from the remote:

git fetch origin 'refs/notes/*:refs/notes/*'

You can configure git to always pull and push notes:

git config --add remote.origin.fetch +refs/notes/*:refs/notes/*
git config --add remote.origin.push   refs/notes/*:refs/notes/*

Command line support

Notes are shown by default in git show and git log.

Web UI support

GitHub has added and then later dropped support for displaying notes.

GitLab does not support notes.

Gitea does support notes, though there isn’t any official documentation or issue on this as far as I can tell; see this screenshot. This may imply support in GOGS and/or Forgejo as well, but I haven’t checked.

Sourcehut seems to use it to sign releases according to its documentation, but I’m not sure if or how notes are displayed in the Sourcehut UI.

Write a comment on the original post.

Argo Workflows path trigger

Fri, 09 May 2025 07:45:00 -0500

In Argo Workflows, you can have a Sensor trigger only when specific paths in a repo have changed, but it isn’t well documented. Here’s how it works.

Trigger on any change

You’ll want to make sure this is working first.

Deploy a WorkflowTemplate; here we’ll assume called build-example is already created.

Create a webhook EventSource

apiVersion: argoproj.io/v1alpha1
kind: EventSource
metadata:
name: example-webhook
namespace: argowf
spec:
replicas: 2
service:
    ports:
    - name: http
        port: 12000
        targetPort: 12000
webhook:
    gitea-webhook:
    endpoint: /gitea
    method: POST
    port: "12000" # Has to be a string because lol

This will deploy a service called webhook-eventsource-svc in the argowf namespace.

Configure a repository in Gitea to call that webhook on every push, http://webhook-eventsource-svc.argowf.svc.cluster.local:1200/gitea.

Configure a Sensor. Replace REPO_OWNER/REPO_NAME with the owner and name of the repo in Gitea. Note: you’ll also need to define a trigger,

apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
name: workflow-build-example-project
namespace: argowf
spec:
template:
    serviceAccountName: argowf-sensor
    container:
    env:
        - name: LOG_LEVEL
        value: "debug"

dependencies:
    - name: gitea-webhook-dep
      eventSourceName: example-webhook
      eventName: gitea-webhook
      filters:
        data:
        - path: body.repository.full_name
            type: string
            value:
            - "REPO_OWNER/REPO_NAME"

triggers:
- template:
    name: argo-workflow-trigger
    argoWorkflow:
      operation: submit
      source:
        resource:
          apiVersion: argoproj.io/v1alpha1
          kind: Workflow
          metadata:
            generateName: wf-build-example-
            namespace: argowf
          spec:
            workflowTemplateRef:
              name: build-example

This will trigger your build-example WorkflowTemplate any time you push to the REPO_OWNER/REPO_NAME git repository in your Gitea server.

Trigger for specific path

To trigger only on a specific path within a repo, you need to add another data filter. For instance, this will match on any file starting with some/path/.* (including subfolders):

      filters:
        # Require that all of the data filters match; boolean AND
        dataLogicalOperator: "and"
        data:
          # The same filter we had above, matching on the specific repo
          - path: body.repository.full_name
            type: string
            value:
              - "REPO_OWNER/REPO_NAME"
          # A new filter, requiring that at least one of the files added/changed/removed in the commit is under some/path/ in the repo
          - path: "[body.commits.#.modified.@flatten,body.commits.#.added.@flatten,body.commits.#.removed.@flatten].@flatten.@flatten"
            type: string
            value:
              - '"some/path/.*'

How does this work?

First, note the correct value for path depends entirely on the webhook payload from your Git server. I’m using Gitea, which is supposedly compatible with Github, but this isn’t a standard. If you’re using some other Git server, you’ll need to figure out what its webhook payload body looks like. (One way to do this is by creating a Sensor and reading the logs of the Sensor container while pushing a commit.)

Gitea (and GitHub) send(s) a rather large JSON payload, including a list of commits and a list of files modified/added/removed in each. For instance, a commit that changes some/path/README.md and adds some/path/main.c will include this (heavily truncated):

{
  "body": {
    "commits": [
      {
        "added": [
          "some/path/main.c"
        ],
        "modified": [
          "some/path/README.md"
        ]
      }
    ]
  }
}

In the path field of a data filter, Argo Workflows supports something called GJSON Path syntax, which we use to collapse all modified, added, and removed lists from the payload into a SINGLE list containing all the files in the repo that were modified:

["some/path/main.c", "some/path/README.md"]

The value field of the data filter is a regexp that operates on that JSON string, as a string. To be clear, it doesn’t understand JSON at all, and does not operate on individual list items. For non-pathological repositories you can just match on double quotes " as the beginning/end of file names; in theory you could have a repo with files that contain quotes, but my advice is: do not do that.

Here’s a simple case matching a single sub-path:

- path: "[body.commits.#.modified.@flatten,body.commits.#.added.@flatten,body.commits.#.removed.@flatten].@flatten.@flatten"
  type: string
  value:
  - '"some/path/.*'

Note that the whole thing is wrapped in single quotes '; this is so the double quote " character is parsed as part of the string.

Trigger for a list of paths

Here’s a more complicated case, matching any of several sub-paths, separated by pipes. Note the double quote " as the first character, indicating that all of these path fragments must be at the beginning.

- path: "[body.commits.#.modified.@flatten,body.commits.#.added.@flatten,body.commits.#.removed.@flatten].@flatten.@flatten"
  type: string
  value:
  - '"(path/one|path/two/that/is/deeper|path3|etc)'

References

argoproj/argo-events#1127: Unsure of the best practice for a filter with multiple paths
argoproj/argo-events#1097: Allow for JSON string to be processed in the Sensor DataFilter
Documentation was written with information about GJSON, but somehow that documentation has been lost from the current docs?
- argoproj/argo-events#1130: docs: Enhance the filters tutorial for #1097, the PR that contains GJSON documentation
- argoproj/argo-events#3525: Example documentation for filtering webhooks based on repo and path, a ticket I opened to address this

Write a comment on the original post.

Raspberry Pi and device tree

Sat, 19 Apr 2025 12:00:00 -0500

I have just finished adding support for psyopsOS to the Raspberry Pi. Along the way I learned a few things about how device trees and the Pi that surprised me.

U-Boot needs its own device tree

The Pi’s firmware has a pretty nice Linux loader, but a feature of psyopsOS is A/B updates, and to support selection between two different runtime operating systems, I needed to use U-Boot¹.

U-Boot needs its own device tree. Device trees come from the Linux kernel, so U-Boot is tied to the Linux kernel source. Typically, a U-Boot binary for Raspberry Pi will set a default dtb file at compilation time, maybe bcm2711-rpi-4-b.dtb for the Raspberry Pi 4B. When booting U-Boot on the Raspberry Pi, the device_tree=... configuration setting in the Pi’s config.txt will override whatever U-Boot has set as its default.

The U-Boot device tree can be different from the kernel device tree

When booting a kernel, you can specify a different device tree than the one used in U-Boot. Which is good for psyopsOS, because the whole point of the psyopsOS A/B system is to enable upgrading the non-booted A/B side, including the kernel, without changing the bootloader.

U-Boot needs a device tree like the one it was compiled with, NOT necessarily like the one used in the kernel that it’s booting.

VideoCore needs device tree overlays (sometimes)

VideoCore is the proprietary Broadcom GPU firmware. On the Pi, it is loaded first, before any bootloaders like U-Boot, and before the Linux kernel. (VideoCore can also load a Linux kernel directly, which is the usual way to boot a Pi.) The config.txt file on a Raspberry Pi boot partition configures VideoCore.

The device tree system has base device trees for a single device, like bcm2711-rpi-4-b.dtb for the Raspberry Pi 4B, and optional overlays that can be applied on top of those bases.

For psyopsOS, I want to have a console listening on the serial port so that I can do emergency maintenance on any machine with a laptop and a serial adapter without a full monitor and keyboard. I’m using the primary PL011 UART (which Linux sees as /dev/ttyAMA0), which is used by the Bluetooth subsystem by default. I have to use an overlay to disable bluetooth to access this UART. There is a device tree overlay file called disable-bt.dtbo that does this.

When booting a Pi the normal way, where VideoCore loads Linux directly based on config.txt, you need to have /overlays/disable-bt.dtbo on the boot filesystem, and set this in config.txt:

overlay=disable-bt

When I had VideoCore load U-Boot, I took this out, because I applied the overlay inside U-Boot. But my kernel could never see the serial port.

It turns out that the disable-bt overlay is needed both by the kernel and by VideoCore. When it is set in config.txt, VideoCore reconfigures the hardware to give the GPIO pins to the UART, rather than to Bluetooth. (I think this is called “pin muxing”, but I don’t understand it very well.)

Example with separate dtb(o) files for U-Boot and Linux

So in my boot partition, I have:

u-boot.bin, the U-Boot binary
u-boot.dtb, the Raspberry Pi 4B device tree base file that U-Boot was built with.
overlays/disable-bt.dtbo, the device tree overlay that disables Bluetooth and changes the pin muxes so that GPIO 14/15² are serial TX/RX. This was built from the same kernel sources that built u-boot.dtb. Note that this path is special. The device tree base file can be set with device_tree=... in config.txt, but the overlay=... lines do not take a path, they take a name like disable-bt, which VideoCore takes to mean /overlays/disable-bt.dtbo.

A config.txt file that references these:

device_tree=u-boot.dtb
dtoverlay=disable-bt
kernel=u-boot.bin
enable_uart=1
uart_2ndstage=1

And in each psyopsOS A/B side, I have:

kernel, a Linux kernel that U-Boot can load (from the Alpine linux-rpi package, although it could be hand built instead)
initramfs, an initramfs that was built alongside the kernel
/dtbs/bcm2711-rpi-4-b.dtb, a device tree base file for the Raspberry Pi 4B that was built with the kernel.
/dtbs/overlays/disable-bt.dtbo, a device tree overlay file that disables bluetooth and was built alongside the kernel. This path is not special, because I load an absolute path to the dtbo in the U-Boot script.
… other files not relevant here

The A/B kernel, dtb, and dtbo might be the same version as the ones on the boot partition, but they don’t have to be. Over time, as I upgrade the A and B sides, those versions will change. The boot volume will change much less often, if at all.

in the future, UEFI might be a viable option, but at the moment it has a few problems: it can only address 3GB of RAM without changing the configuration, the configuration cannot be changed outside of the UEFI UI at boot time, and updating UEFI wipes out all local changes. I don’t have any Pi 5 devices, but UEFI also doesn’t support those. ↩︎
The GPIO numbers are not the same as the Pi’s pin numbers. GPIO 14/15 are on Pi pinout pins labeled 8/10. https://pinout.xyz/ is an excellent reference. ↩︎

Write a comment on the original post.

Generate Kubernetes CRD documentation

Fri, 04 Apr 2025 13:00:00 -0500

You know how some Kubernetes CRDs have no documentation and incomplete examples, so you have to wade through the CRD to figure out how to configure it? You might think that is simple laziness on the part of the developers, but you’re wrong. It’s abject laziness. It’s pathological laziness. It’s malicious laziness. It is the deadly sin of sloth.

If you’ve already written the CRD, you can generate documentation for free!

If you are currently trying to use a CRD that doesn’t provide complete documentation, you can generate some right away with https://doc.crds.dev/. Just pop in the GitHub repo and it’ll find them for you! Amazing.

If you’re writing CRDs, for god’s sake at least link to this in your readme, if you can’t bother to generate them yourself with one of the many programs designed for this purpose.

Write a comment on the original post.

scrollbar-gutter: stable

Sat, 15 Mar 2025 07:50:56 -0500

I learned about scrollbar-gutter recently and I can’t believe it’s not the default. (Maybe I should make a whole series of these for CSS.)

The scrollbar-gutter CSS property allows authors to reserve space for the scrollbar, preventing unwanted layout changes as the content grows while also avoiding unnecessary visuals when scrolling isn’t needed.

scrollbar-gutter | MDN

I discovered this when I built a site with centered content. When navigating between pages, the content would shift a few pixels left/right. It took me a while to figure out that this was because some pages showed a scrollbar, and other pages didn’t.

A screen recording of the behavior

Observe the right side of this screen recording to see the scrollbar appear and disappear during navigation.

Your browser does not support the video element, but you can download the recording.mp4 file instead.

Setting scrollbar-gutter: stable fixes this behavior. You can set it on any scrolling element; I recommend doing so on the root html element.

html {
  scrollbar-gutter: stable;
}

Not only is this something you have to specify, but it wasn’t even available until recently; MDN indicates this is in Baseline as of December 2024. What did poor designers do in the past, I don’t even want to know.

Write a comment on the original post.

POSIX man pages on every system

Fri, 28 Feb 2025 21:25:49 -0600

The Linux kernel project maintains a free copy of the POSIX man pages that you can install on any system. Your Linux distribution probably has a man-pages-posix package you can get via your package manager, but the generic version works anywhere (such as on macOS) almost as easily:

curl -fsSL "https://www.kernel.org/pub/linux/docs/man-pages/man-pages-posix/man-pages-posix-2017-a.tar.xz" |
    sudo tar -xJ -C /usr/local/share/man/ -f - --strip-components=1 man-pages-posix-2017/man1p

This extracts just the directory man1p from the tarball, which includes only the man pages for the POSIX shell and commands. (You can also extract the man0p directory for header files and man3p directory for library functions if you like, but we don’t need those for my primary purpose of shell scripting.) It adds a section 1p to the manual containing only the POSIX commands. You can reference them directly by specifying the section:

# Show the first man page for `sh` found in any section of the manual
man sh

# Show the man page for `sh` from section 1,
# the section for your operating system's general commands
man 1 sh

# Show the man page for `sh` from section 1p,
# the section we just added for POSIX general commands
man 1p sh

Several versions of the man pages are built from the Git repository and published to tarballs.

Update: I wrote a formula to make installation even easier for Homebrew users. It is in my personal tap because these docs are licensed restrictively and cannot be included in homebrew-core. This formula includes all the sections provided by the man-pages-posix project:

0p: Headers
1p: Commands and Built-Ins
3p: Functions

To install it, run:

brew install mrled/cauldron/man-pages-posix

I recommend strict POSIX compliance in shell scripts (furthermore). But how can you know whether a given option or command is pure POSIX or a filthy vendor extension? Most vendor manual pages do not specify, so you have to reference the POSIX documentation directly.

Because of this, I am a regular user of the excellent https://shellhaters.org, which contains links to official POSIX shell and command documentation from The Open Group in HTML.

And now I also can find the docs in my own terminal.

Write a comment on the original post.

Page-specific styles, scripts, and sprites

Thu, 19 Dec 2024 10:31:05 -0600

I stumbled upon a pattern recently that turned out to be very useful. It would be useful for any site that is built directly from the filesystem, but my sites and this example assumes Hugo.

The Hugo template that contains my <head> element finds page resources for CSS, JavaScript, and SVG sprite files that have specific names. If they are present, I embed their contents directly in the page.
I can create a file with those names any time I need styling, scripts, or sprites that are unique to a single page.

And that’s it! It’s especially useful when prototyping, but I’ve used it everywhere.

Here’s what’s in <head>:

<style id="pagestyle">
{{- with .Page.Resources.Get "pagestyle.css" }}
{{ .Content | safeCSS }}
{{ end }}
</style>

<script id="pagescript" type="text/javascript">
{{- with .Resources.Get "pagescript.js" }}
{{ .Content | safeJS }}
{{ end }}
</script>

{{ with .Page.Resources.Get "pagesprites.svg" }}
{{ .Content | safeHTML }}
{{ end }}

Here’s the filesystem layout:

content/
  blog/
    post-1/
      index.md
      pagestyle.css
      pagescript.js
      pagesprites.svg

You could do this with links instead of embedding the content directly. I figure that since these artifacts are be design only useful on a single page, there’s no need to load them separately to take advantage of caching, and there’s a small benefit of being certain they’ve loaded before the <body> by inlining them.

Write a comment on the original post.

Use nosniff for universal browser display of web feeds

Thu, 14 Nov 2024 09:25:54 -0600

I like to style my web feeds. Until recently, I thought that Safari simply didn’t support this, because when I tried it, it would just ask if I wanted to load the page in my feed reader.

This is ok, if you have one installed, but I’m not even sure what happened to users that didn’t already have a feed reader installed. I’d prefer the browser to display the styled feed and let the user copy the URL into their reader.

It turns out this has been possible all along! The punchline: Serve your RSS feed with the X-Content-Type-Options: nosniff HTTP header set.

My feeds are now viewable directly in any browser:

Discovery

I read a Mastodon post praising the lovely Standard Ebooks site, including a shout-out to its nicely styled feeds.

There’s OPDS (the catalog feed format), and RSS and Atom. Normally, you make the mistake of going to a feed URL in your browser instead of a specific program to read feeds, and you’re punished with horrible XML. But click on any feed link here and it’s the nice looking HTML like the rest of the site.

I happened to be on iOS at the time (which constrains me to Safari only), and when I clicked through to the various feed pages, it was true: it showed me a nicely laid out feed. Examining the feed source showed a normal-looking RSS feed, and the W3C feed validator indicates it’s a fully valid feed. What are they doing that I wasn’t?

Coincidentally, Matt Webb had recently posted his colophon, and Simon Willison linked to it noting Matt’s styled RSS feed. I read Simon’s post on my phone as well, and tried the link, and it too worked great in Safari.

I thought about it for a minute and wondered if there was a header that controlled this.

See `curl -I` output comparing the sites

Standard Ebooks

> curl -I https://standardebooks.org/feeds/rss/new-releases
HTTP/2 200
strict-transport-security: max-age=15768000
x-frame-options: sameorigin
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
referrer-policy: no-referrer-when-downgrade
content-security-policy: default-src 'self';
cache-control: no-store
last-modified: Wed, 13 Nov 2024 02:31:06 GMT
etag: "1c042e-3bdf-6269c0b6a2088"
content-length: 15327
content-type: application/rss+xml
date: Thu, 14 Nov 2024 03:40:45 GMT
server: Apache

Matt Webb

> curl -I https://interconnected.org/home/feed
HTTP/1.1 200 OK
Date: Thu, 14 Nov 2024 01:26:20 GMT
Server: Apache/2.4.41 (Ubuntu)
Content-Length: 64882
x-content-type-options: nosniff
Vary: Accept-Encoding
Content-Type: application/xml; charset=utf-8

My blog

> curl -I https://me.micahrl.com/blog/rss.xml
HTTP/2 200
accept-ranges: bytes
age: 0
cache-control: public,max-age=0,must-revalidate
cache-status: "Netlify Edge"; fwd=miss
content-type: application/xml
date: Thu, 14 Nov 2024 03:40:53 GMT
etag: "b5caa51975a8b10766bd5c3e8ca49c50-ssl"
onion-location: http://mgv3s6mkbisnggxz5xg3f75vkch67qmj5fkw5yaaazztaqofmgplddad.onion/
server: Netlify
strict-transport-security: max-age=31536000
x-nf-request-id: 01JCMC4Y2TNJSEW5EZ2RSW4J03
x-underappreciated-truth: "Having a defensible opinion takes work."
content-length: 2209662

The Content-Type header stood out to me as different;

content-type: application/xml: mine
content-type: application/rss+xml: Standard Ebooks
Content-Type: application/xml; charset=utf-8: Matt Webb

But changing mine to match either of theirs didn’t make a difference to Safari. I examined the list more closely and the thing that both of their sites had that mine didn’t was X-Content-Type-Options: nosniff. This turned out to be the missing piece! My content-type: application/xml works fine when accompanied by the nosniff header, though I did change it to the more specific Content-Type: application/xml; charset=utf-8.

Existing documentation

When writing my RSS styles blog post, I recall reading somewhere that all browsers don’t support it. However, it has been documented in Matt Webb’s pretty-feed-v3.xsl since at least 2021.

I had seen that XSL stylesheet before, but hadn’t read it closely. I took another look via a link from Keith Wagner’s blog post on feed styles, which I only found by searching for articles about RSS and nosniff.

Write a comment on the original post.

Transformed HTML on the macOS clipboard

Sun, 22 Sep 2024 11:04:43 -0500

Have you ever noticed that you can copy text from a web page, and when you paste it into a rich text editor like Word or Google Docs, all the links work? And also of course, simple formatting is copied pretty well too, including bold, italics, and even tables.

This is great, but can you get it to output a text string of HTML tags for you?

View source isn’t good enough for links

For example, right now I’m looking at the Old fashioned (cocktail) article on Wikipedia. If you view source, you’ll see relative links to other articles like:

<a href="/wiki/Hudson,_New_York" title="Hudson, New York">
  Hudson, New York
</a>

and anchor links to footnotes like

<sup id="cite_ref-5" class="reference">
  <a href="#cite_note-5">
    <span class="cite-bracket">[</span>5<span class="cite-bracket">]</span>
  </a>
</sup>

Copying from the page source in the browser will just leave you with those useless non-absolute links.

But if you copy from that page paste this into a rich text editor, these relative and anchor links are transformed into absolute links like

https://en.wikipedia.org/wiki/Hudson,_New_York

and

https://en.wikipedia.org/wiki/Old_fashioned_(cocktail)#cite_note-5

That’s what I want. How can I get that?

`pbpaste(1)` can’t do it

You’d really like the built-in ~~clip~~pasteboard tool to be able to handle this for you, but it can’t. If you copy text from a browser and run pbpaste(1), you’ll get all the formatting stripped out.

The first documented definition of the word "cocktail" was in response to a reader's letter asking to define the word in the 6 May 1806, issue of The Balance and Columbian Repository in Hudson, New York.

pbpaste(1) can get RTF or Postscript data if you pass -Prefer rtf or -Prefer ps. However, the browser doesn’t convert rich text to either of those formats on copy, so you just end up with the text result.

Wait, what kind of data is on the clipboard?

Oh yeah, maybe it’s worth being explicit about this: the clipboard may contain different representations of the same data. We can look at it with a bit of Applescript.

osascript -e 'tell app "Finder" to clipboard info'

When the clipboard contains text from a web browser, that shows:

«class HTML», 4604, «class utf8», 1760, «class ut16», 3520, string, 1106, Unicode text, 3518

Interesting that it has a UTF-8 and UTF-16 version on there, but what matters to us is that there an HTML type. pbpaste(1) doesn’t support that type :(.

Use AppleScript

So instead we have to use AppleScript to get it. In fact, I copiloted a little shell script.

#!/bin/sh
set -eu

osascript <<EOF
use framework "Foundation"
use framework "AppKit"

set thePasteboard to current application's NSPasteboard's generalPasteboard()
set theHTML to thePasteboard's stringForType:(current application's NSPasteboardTypeHTML)

if theHTML is missing value then
    return "No HTML content found in clipboard."
else
    return theHTML as text
end if
EOF

And that results in something like:

<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body>The first documented definition of the word "cocktail" was in response
to a reader's letter asking to define the word in the 6 May 1806, issue
of <i>The Balance and Columbian Repository</i> in <a href="https://en.wikipedia.org/wiki/Hudson,_New_York" title="Hudson, New York">Hudson, New York</a>.</body></html>

AHA!

Write a comment on the original post.

lunr.js site search

Fri, 06 Sep 2024 14:12:02 -0500

I added search to this site on the main page.

It’s all client-side with lunr, which relies on building a JSON index of all site content at deploy time. It has no dependencies and is fast once the index is downloaded.

It comes more as lego bricks than an out of the box system, though. I needed to build an index for it to use, decide what fields to make searchable, add HTML for entering the search terms and configure a place to show results, and write some JavaScript to call lunr to perform the search and show the results in my UI.

Here’s how I did it.

Generate the lunr index with Hugo

As mentioned, Lunr needs a JSON index. I got Hugo to create this form me with a custom output format. From my config (other mediaTypes, outputFormats, and outputs are elided):

outputFormats:
  # ...
  lunr:
    basename: lunr
    isPlainText: true
    mediaType: application/json

outputs:
  # ...
  home:
    - HTML
    - lunr
    # ...

I added layouts/_default/index.lunr.json:

{{/*  Build the lunr.js index for the site.
      -*- mode: go -*-

      Ignores the following sections:
        - warchive:     No good way to index the WARC and WACZ files
        - twarchive:    Would have to read Twitter data JSON files, not worth it

      The "content" is used for searching.
      The "summary" is displayed in search results.
        https://gohugo.io/methods/page/summary/
        Hugo generates one of a limited number (default 70) of words of the content,
        or splitting the content with a <!--more--> comment,
        or you can set it yourself with the "summary" frontmatter key.
*/}}
{{- $ignoreSections := slice "warchive" "twarchive" -}}
{{- $index := slice -}}
{{- range $page := $.Site.RegularPages -}}
  {{/*  The first section .Path will be like `/blog`; this gets just `blog`.  */}}
  {{- $firstSectionName := strings.TrimPrefix "/" $page.FirstSection.Path -}}
  {{- if collections.In $ignoreSections $firstSectionName -}}
    {{- continue -}}
  {{- end -}}
  {{- $content := $page.Plain | jsonify -}}
  {{- $tags := $page.Params.tags | default (slice) -}}
  {{- $technologies := $page.Params.technologies | default (slice) -}}
  {{- $index = $index | append (dict
    "title" $page.Title
    "uri" $page.Permalink
    "section" $firstSectionName
    "content" $content
    "summary" ($page.Summary | plainify | jsonify)
    "tags" (delimit $tags " ")
    "technologies" (delimit $technologies " ")
  ) -}}
{{- end -}}
{{/*  In dev mode, pretty-print the JSON; otherwise minify it  */}}
{{- $jsonifyArgs := dict -}}
{{- if eq hugo.Environment "development" -}}
  {{- $jsonifyArgs = dict "indent" "  " -}}
{{- end -}}
{{- $index | jsonify $jsonifyArgs -}}

And now the index is created at public/index.lunr.json

Some notes about this index:

The Hugo template populates fields called “tags” and “technologies”, which are taxonomies I use here. You’ll want to adapt this to your own site’s taxonomies, or remove the taxonomy fields altogether.
I populate a “section” field, so that the section name like “blog” or “til” is searchable.
I run jsonify against the content and summary fields, which means I have to decode that JSON in my JavaScript (see below)
In development it creates a pretty-printed JSON file, but in production it’s minified.
At the time of this writing, the production index is 824KB.

Get lunr

To get it, you can use a whole package.json and npm install and spend 45 minutes every third Wednesday opting out of telemetry or whatever JavaScript people do. But in this case, the package has no dependencies and there’s no security concerns (all client side, no private data), so I decided to just install a single version and update it later if I feel like it.

Get the NPM package with npm pack lunr
This downloads (at the time of this writing) lunr-2.3.9.tgz to your current directory
Extract package/lunr.js and place it in your assets/ directory
You could instead get package/lunr.min.js, but I got the non-minified version and am using Hugo’s JavaScript minification on build

Install lunr

Include the lunr code in your <head>.

{{ $lunrJs := resources.Get "js/lunr.js" | resources.Minify | resources.Fingerprint }}
<script src="{{ $lunrJs.Permalink }}" defer></script>

You also need to define your own search function and decide how you want to display results. I decided I will have a search bar only on the main site page, and it’ll display results below the main content of my site page, and auto-scroll to the results when searching. It will add the search to the query string in the URL, add entries to the browser’s history so that back/forward buttons work, and run a search automatically if a page is loaded with a search term in the query string. This means it feels like having a separate results page, but it’s all just part of the main page of my site.

That meant adding this HTML to my home page where I want the search bar:

  <form id="search" class="search" role="search">
    <label for="search-input">
      
      <svg class="spritecore" viewBox="0 0 100 100"><use href="https://testcom.micahrl.me/images/spritesheet.svg#fa-solid-search" /></svg>
    </label>
    <input type="search" id="search-input" class="search-input">
  </form>

And adding this to my home page where I want the results to show up:

<template id="search-result" hidden>
  <article class="content post">
    <h3 class="post-title"><a class="summary-title-link"></a></h3>
    <summary class="summary"></summary>
  </article>
</template>

<div id="lunr-search-results"></div>

And this CSS:

@keyframes spin {
  100% {
    transform: rotateY(360deg);
  }
}

form.search {
  /* This needs to be large enough on mobile
   * so that focusing on the input doesn't cause zoom.
   */
  font-size: 1.5rem;
  border: 1px solid var(--body-fg-color-deemphasize-nontext);
  min-width: 1em;
  height: 1em;
  line-height: 1;
  border-radius: 1em;
  padding: 0.5em;
}

.search[data-running] .search-icon {
  animation: spin 1.5s linear infinite;
}

form.search input {
  width: 10em;
  color: var(--body-fg-color);
  background-color: var(--body-bg-color);
}

#lunr-search-results-title {
  margin-top: 6em;
}

#lunr-search-results summary {
  color: var(--body-fg-color-deemphasize-text);
  font-size: 85%;
}

@media (min-width: 600px) {
  form.search {
    font-size: 1rem;
  }
}

/* -*- mode: css -*- */

And this Javascript to run on page load. Much of this was adapted from Wladimir Palant’s code, with my own changes.

/* lunr search implementation
 */
window.addEventListener("DOMContentLoaded", function(event) {
  var index = null;
  var lookup = null;
  var queuedTerm = null;

  var form = document.getElementById("search");
  var input = document.getElementById("search-input");
  var resultsContainer = document.querySelector("#lunr-search-results");

  const entityDecoder = document.createElement("textarea");
  function decodeHTMLEntities(text) {
    text = text || "";
    entityDecoder.innerHTML = text;
    return entityDecoder.value;
  }

  form.addEventListener("submit", function(event) {
    event.preventDefault();

    var term = input.value.trim();
    if (!term)
      return;

    startSearch(term);
  }, false);

  function startSearch(term) {
    // Update URL with search term
    const searchParams = new URLSearchParams(window.location.search);
    searchParams.set('q', term);
    const newRelativePathQuery = window.location.pathname + '?' + searchParams.toString();
    history.pushState({searchTerm: term}, '', newRelativePathQuery);

    // Start icon animation.
    form.setAttribute("data-running", "true");

    if (index) {
      // Index already present, search directly.
      search(term);
    } else if (queuedTerm) {
      // Index is being loaded, replace the term we want to search for.
      queuedTerm = term;
    } else {
      // Start loading index, perform the search when done.
      queuedTerm = term;
      initIndex();
    }
  }

  function searchDone() {
    form.removeAttribute("data-running");
    queuedTerm = null;
  }

  function initIndex() {
    var request = new XMLHttpRequest();
    request.open("GET", "/index.lunr.json");
    request.responseType = "json";
    request.addEventListener("load", function(event) {
      lookup = {};
      index = lunr(function() {
        this.ref("uri");

        // If you added more searchable fields to the search index, list them here.
        this.field("title");
        this.field("section");
        this.field("content");
        this.field("summary");
        this.field("tags");
        this.field("technologies");

        for (var doc of request.response)
        {
          doc.content = decodeHTMLEntities(JSON.parse(doc.content));
          doc.summary = decodeHTMLEntities(JSON.parse(doc.summary));
          this.add(doc);
          lookup[doc.uri] = doc;
        }
      });

      // Search index is ready, perform the search now
      if (queuedTerm) {
        search(queuedTerm);
      }
    }, false);
    request.addEventListener("error", searchDone, false);
    request.send(null);
  }

  function search(term) {
    var results = index.search(term);
    // console.log(results);

    clearResults();

    var title = document.createElement("h2");
    title.id = "lunr-search-results-title";
    title.className = "list-title";

    if (results.length == 0)
      title.textContent = `No results found for "${term}"`;
    else if (results.length == 1)
      title.textContent = `Found one result for "${term}"`;
    else
      title.textContent = `Found ${results.length} results for "${term}"`;
    resultsContainer.appendChild(title);
    document.title = title.textContent;

    var template = document.getElementById("search-result");
    for (var result of results) {
      var doc = lookup[result.ref];

      // Fill out search result template, adjust as needed.
      var element = template.content.cloneNode(true);
      element.querySelector(".summary-title-link").href = doc.uri;
      // element.querySelector(".read-more-link").href = doc.uri;
      element.querySelector(".summary-title-link").textContent = doc.title;
      element.querySelector(".summary").textContent = truncate(doc.summary, 70);
      resultsContainer.appendChild(element);
    }
    title.scrollIntoView(true);

    searchDone();
  }

  function clearResults() {
    while (resultsContainer.firstChild) {
      resultsContainer.removeChild(resultsContainer.firstChild);
    }
    document.title = "Search"; // Reset the page title
  }

  // This matches Hugo's own summary logic:
  // https://github.com/gohugoio/hugo/blob/b5f39d23b8/helpers/content.go#L543
  function truncate(text, minWords) {
    var match;
    var result = "";
    var wordCount = 0;
    var regexp = /(\S+)(\s*)/g;
    while (match = regexp.exec(text)) {
      wordCount++;
      if (wordCount <= minWords)
        result += match[0];
      else
      {
        var char1 = match[1][match[1].length - 1];
        var char2 = match[2][0];
        if (/[.?!"]/.test(char1) || char2 == "\n")
        {
          result += match[1];
          break;
        }
        else
          result += match[0];
      }
    }
    return result;
  }

  // Check for search term in URL on page load
  const urlParams = new URLSearchParams(window.location.search);
  const searchTerm = urlParams.get('q');
  if (searchTerm) {
    input.value = searchTerm;
    startSearch(searchTerm);
  }

  // Handle popstate event (back/forward button)
  window.addEventListener('popstate', function(event) {
    const newUrlParams = new URLSearchParams(window.location.search);
    const newSearchTerm = newUrlParams.get('q');

    if (newSearchTerm) {
      input.value = newSearchTerm;
      search(newSearchTerm);
    } else {
      input.value = '';
      clearResults();
    }
  });

}, false);

/* -*- mode: javascript -*- */

Notes about this JavaScript:

I had to adapt it to use the fields I added in the index, and to decode the JSON “content” and “summary” fields.
The path to the index is hard coded.

References

Wladimir Palant’s code The easier way to use lunr search with Hugo
Bill Baer’s Getting started with Lunr.js and Hugo
Crag Mod’s Super fast, keyboard-optimized, client side Hugo search describes deploying a similar search library called Fuse

Write a comment on the original post.

Shortcodes and outputs

Sun, 01 Sep 2024 15:43:44 -0500

In Hugo, you can make the same shortcode do different things for different outputs.

Prerequisite concepts:

Hugo can output content in multiple formats; by default the site outputs HTML and RSS. The different formats use different templates inside the layouts/ directory. It’s possible to define your own custom output formats and have Hugo output them, too.
Hugo shortcodes are snippets that call templates in your content. For instance, Hugo defines the ref shortcode which gets the URL for content, such as (from the documentation) [Post 1]({{% ref "/posts/post-1" %}}) being rendered as <a href="http://example.org/posts/post-1/">Post 1</a>. You can also write your own shortcodes to output whatever HTML you want.

So, the punchline is that you can write your own shortcodes and have them behave differently when making different outputs.

Why would you want to do this? I use this in a couple of key places for HTML that looks great on the web but doesn’t render properly in RSS. Feed readers don’t use a site’s CSS at all, but most of them will apply very limited styles that are inlined as HTML style=... attributes. Sometimes this can make a real difference.

For example, I have a shortcode called callout that works like this:

On the web, this is styled with CSS to show a border and a background color so that it stands out from the rest of the content. Since RSS doesn’t read my CSS, I have a different version of the shortcode that inlines just the border, so that the contents of the callout box don’t get mixed up with the main page content. That isn’t very reliable, though — some¹ feed readers don’t even apply the inlined border. For that reason I also insert an <hr/> element before and after the <aside>. I don’t bother trying to inline the background color, both because I can’t rely on it, and because I don’t know if the user’s app will be in dark mode or light mode, and I suspect it won’t be possible to add a single background color that would look good behind either white or black text. It’s OK with me that the RSS is much simpler than the HTML, I just want to make sure the content is clear in RSS.

Source code

The only difference between these two files is the style="..." attribute in the RSS template

`layouts/shortcodes/callout.html`

{{/* A callout is a colored box that stands out from the rest of the text.
   *
   * Arguments:
   *   type: The style of the box, one of "tip", "warning", "none". Default: "none"
   *   header: The text to display in the box header. Default: ""
   *
   * TODO: Don't support a header argument, just let the caller put a header in the content.
   */}}
{{- $calloutType := default "none" (.Get "type") }}
{{- $calloutTypeClass := printf "callout-%s" $calloutType }}
{{- $header := .Get "header" }}
<aside class="callout {{ $calloutTypeClass }}">
  {{ with $header }}<h3 class="callout-header">{{ $header | markdownify }}</h3>{{ end }}
  {{ .Inner | markdownify }}
</aside>

`layouts/shortcodes/callout.rss.xml`

{{/* A callout is a colored box that stands out from the rest of the text.
   *
   * Arguments:
   *   type: The style of the box, one of "tip", "warning", "none". Default: "none"
   *   header: The text to display in the box header. Default: ""
   *
   * TODO: Don't support a header argument, just let the caller put a header in the content.
   */}}
{{- $calloutType := default "none" (.Get "type") }}
{{- $calloutTypeClass := printf "callout-%s" $calloutType }}
{{- $header := .Get "header" }}
<hr />
<aside style="border: 1px solid gray; margin: 1em; padding: 1em;" class="callout {{ $calloutTypeClass }}">
  {{ with $header }}<h3 class="callout-header">{{ $header | markdownify }}</h3>{{ end }}
  {{ .Inner | markdownify }}
</aside>
<hr />

To make this work, you just need to make two shortcode files and name them according to the template lookup order. For this shortcode, I use

layouts/shortcodes/callout.html
layouts/shortcodes/callout.rss.xml

(I am happy to have helped improve the template lookup order documentation.)

You can also use this to write blocks that only appear on the web and not in RSS, or vice versa.

Updates

2024-09-01: Add <hr/> to the callout box in RSS.

Feed readers are very inconsistent on this. I originally tested this shortcode in NetNewsWire on the Mac, which I can do locally without deploying the site, and it displayed the border just fine. That was several weeks ago by now, and I didn’t realize that NetNewsWire on iOS doesn’t actually display the border! After making this post and seeing the result on iOS, I added the <hr/> elements. ↩︎

Write a comment on the original post.

ExitStack

Fri, 30 Aug 2024 22:07:35 -0500

If you’re using Python context managers, you can use contextlib.ExitStack to work with many of them at once.

A context manager that is designed to make it easy to programmatically combine other context managers and cleanup functions, especially those that are optional or otherwise driven by input data.

contextlib.ExitStack documentation

Basically, this allows you to use multiple context managers without knowing the list before runtime.

I’m annoyed to report that I have built more than one custom implementation of this functionality without knowing that it was in the standard library, and I basically finished a 1500 word blog post and 120 line example program describing my most recent solution. The only reason I even discovered the version in the standard library was when I started writing tests to verify my code before publishing it, Claude 3.5 Sonnet helpfully told me I should use contextlib.ExitStack for this instead.

Write a comment on the original post.

Mount static/ to assets/static/

Thu, 29 Aug 2024 14:39:05 -0500

For Hugo sites, you should probably use module mounts to mount the static directory to assets/static. Doing so allows you to reference static files directly via their path like /file.txt, or using Hugo resources with resources.Get "static/file.txt".

I found this helpful for using the same font both as a web font and in og:image generation. (By the way, did you know that Hugo can generate social preview og:image files!? TODO: write another TIL about this.)

When referencing a font in CSS, it is much more convenient to keep that font in static/ than assets/, because CSS files cannot call resources.Get. (You can call resources.Get "font.woff2" in an HTML partial, and put template variables in the CSS, then use resources.ExecuteAsTemplate to force Hugo to apply those variables from the HTML partial, but this is not a very nice experience. You would much rather put your font in static/ and reference it in CSS as /font.woff2 and be done with it.)

On the other hand, if you want to use the same font with images.Text, which is required for og:image generation, you must use resources.Get to find it, which means it has to be in the assets folder, not static.

… Until recently, that is. With the advent of module mounts, you can now overly any part of your source onto any other part. And specifically, you can virtually mount static/ to assets/static/. Unless you already have an assets/static/ folder for some reason — which would be pretty weird — there are no downsides to this. Everything in static is already deployed to your site, and making it available inside assets/static just lets you use all the files there with resources.Get.

Note that mounts are per-module, and your site and each theme is a separate module. Therefore, your site and each theme must set this in its own config file. I don’t think it’s possible for one module to affect another one.

Requirements:

A recent-ish Hugo. I’m not sure when exactly virtual mounts were introduced, but they haven’t always been there.
A config file named hugo.toml/hugo.yaml/hugo.json. The docs actually say that it shouldn’t matter, but I found that the mounts didn’t work with a theme config file named theme.toml, and that they started working once I renamed that file to hugo.toml.

Here’s part of what mine looks like.

[module]

# Defaults
# I think defining these is required
[[module.mounts]]
source = 'content'
target = 'content'
[[module.mounts]]
source = 'static'
target = 'static'
[[module.mounts]]
source = 'layouts'
target = 'layouts'
[[module.mounts]]
source = 'data'
target = 'data'
[[module.mounts]]
source = 'assets'
target = 'assets'
[[module.mounts]]
source = 'i18n'
target = 'i18n'
[[module.mounts]]
source = 'archetypes'
target = 'archetypes'

# Make all static files available as assets.
[[module.mounts]]
source = "static"
target = "assets/static"

After you set this up, you can make sure that it’s working in Hugo by running hugo config mounts. That will return output like this:

{
   "path": "micahrl",
   "version": "",
   "time": "0001-01-01T00:00:00Z",
   "owner": "me.micahrl.com",
   "dir": "/Users/mrled/mrldata/Repositories/me.micahrl.com/themes/micahrl/",
   "mounts": [
      {
         "source": "static",
         "target": "static"
      },
      {
         "source": "layouts",
         "target": "layouts"
      },
      {
         "source": "assets",
         "target": "assets"
      },
      {
         "source": "archetypes",
         "target": "archetypes"
      },
      {
         "source": "static",
         "target": "assets/static"
      }
   ]
}

Write a comment on the original post.

text-size-adjust: none

Tue, 27 Aug 2024 15:41:39 -0500

I’ve known this fact for years¹, but it still makes me mad: some browsers, and notably Webkit, will change your font size if it thinks it’s too small unless you tell it to fuck off.

Theorycrafting

Because many websites have not been developed with small devices in mind, mobile browsers differ from desktop browsers in the way they render web pages. Instead of laying out pages at the width of the device screen, they lay them out using a viewport that is much wider, usually 800 or 1000 pixels. To map the extra-wide layout back to the original device size, they either show only part of the whole render or scale the viewport down to fit.

Since text that has been scaled down to fit a mobile screen may be very small, many mobile browsers apply a text inflation algorithm to enlarge the text to make it more readable. When an element containing text uses 100% of the screen’s width, the algorithm increases its text size, but without modifying the layout. The text-size-adjust property allows web authors to disable or modify this behavior, as web pages designed with small screens in mind do not need it.

MDN on text-size-adjust

This might have been defensible in 2007, but it’s absolutely ludicrous in 2024.

To fix it, you need to set both -webkit-text-size-adjust: none and text-size-adjust: none. iOS Safari debuted the -webkit-text-size-adjust property and that is still the only one it respects. Chrome and Edge and others support the experimental standard text-size-adjust property. Firefox doesn’t support either, though I’m not sure whether mobile Firefox has the bad behavior in the first place.

What it looks like

Every once in a while I come across a site that doesn’t set this properly.

Pinboard has exhibited this behavior for many years. Note the size difference between text in the second bookmark and the other three.

Encountered in https://mylynch.io in July 2024. Note the size of the opening label tag compared to the close.

To be clear, I don’t mean to shame the examples I list above (well, except maybe Pinboard, which I did notify about the problem). For one thing, my site was published like this for weeks/months before I noticed and several days before I figured out how to fix it. I just think it’s easier to see by example, and I think it’s worth noting that people do trip over this pothole in practice.

The absurdity of the situation makes me more sympathetic than I would have been otherwise to Pinboard’s plan to address this by “waiting for the mobile fad to die out tbh”.

References

Mozilla Developer Network: text-size-adjust
Kilian Valkhof: Your CSS reset needs text-size-adjust (probably)
Apple Documentation Archive: Adjusting the Text Size
Can I use: text-size-adjust

In this house, TIL stands for “thing(s) I’ve learned”, not “today I learned” ↩︎

Write a comment on the original post.

Presentation selectors

Tue, 27 Aug 2024 13:32:46 -0500

In some HTML, I used the ↩ HTML entity, intending to product a nice classy U+21A9 LEFTWARDS ARROW WITH HOOK as described in the Arrows Unicode block (PDF). I built my site and tested it in Firefox, and it looked as I expected, like so:

↩︎

This morning, upon awakening from agitated dreams (and promptly looking at my own website on my phone before getting out of bed), I found the character had been transformed into a monstrous ~~vermin~~ emoji, like so:

↩️

Outrageous. Ridiculous! Sad, shameful, and uncouth.

This was caused by different default presentation between Firefox on macOS and Safari on iOS. In fact, those two symbols are both valid representations of the U+21A9 LEFTWARDS ARROW WITH HOOK character that I put in my HTML.

I was reminded that emoji are not Unicode codepoints, but glyphs. Some glyphs have their own codepoint; some are made up of multiple codepoints strung together in a certain order, and some share a codepoint with other glyphs.

U+21A9 LEFTWARDS ARROW WITH HOOK is a codepoint in that latter category. For codepoints like these, text rendering engines can decide which glyph to use however they like. Fortunately, however, I can use presentation selectors to specify the one I want.

↩ by itself will be rendered according to the browser’s defaults, which for your browser is ↩.
↩︎ will be rendered as text: ↩︎.
↩️ will be rendered as emoji: ↩️.

Postscript

I tripped over this last night when implementing section links, so that each TIL has a link to the TILs section like ↩︎ /til/, each blog post has a link to the blog section, etc.

But when writing up this TIL, I wrote a footnote¹. Lo and behold, the footnote also has a U+21A9 LEFTWARDS ARROW WITH HOOK as a link to return to the main content, and it is using the text presentation selector to avoid emojification. I don’t control this, however; I believe it comes from the goldmark markdown processor, which appears to insert the text presentation selector automatically.

Something I didn’t appreciate until now is that inspector from the browser dev tools, at least in Firefox and Chrome on macOS, will display the rendered character like ↩︎ or ↩️ not HTML entities like ↩︎ or ↩️ even if that’s what comes across the wire. You have to “view source” to see what is in the HTML.

(Caveat lector: By the time you read this, the layout may have changed.)

like this ↩︎

Write a comment on the original post.

post-commit hook GIT_DIR

Tue, 27 Aug 2024 09:16:26 -0500

For secret reasons, instead of using a Git forge like Github for one of my projects, I am using a regular Linux virtual server running in a major hosting provider. I push to a bare Git repository¹, which has a post-commit hook² that checks out the commit I just pushed, builds the project and runs a few sanity checks, and then deploys the result.

This was the first time I had set such a system up from scratch myself, and I fell into a common pitfall: GIT_DIR.

Here’s the punchline: When checking out a repository from a Git hook, make sure to unset Git environment variables like GIT_DIR, or the actions will fail with strange errors.

What that looks like in practice is pushing to the Git repository and seeing an error like this:

remote: fatal: Not a git repository: '.'

The Git documentation actually calls this out, but I didn’t see it until I ran into problems.

Environment variables, such as GIT_DIR, GIT_WORK_TREE, etc., are exported so that Git commands run by the hook can correctly locate the repository. If your hook needs to invoke Git commands in a foreign repository or in a different working tree of the same repository, then it should clear these environment variables so they do not interfere with Git operations at the foreign location.

The githooks manual

What’s happening is that the post-commit hook sets variables like GIT_DIR, which has special value to subsequent git commands. GIT_DIR in particular is set to ., which is where the error message Not a git repository: '.' comes from.

You can use unset $(git rev-parse --local-env-vars) in a hook to unset all such variables.

Implementation details

My build script was doing something like this (heavily paraphrased):

#!/bin/sh
set -eux
# $newrev is the revision that was just pushed
# $PWD is the bare git repo path
local_git_url="file://$PWD"
while read oldrev newrev refname; do
    # We can't clone a repo and check out a specific commit in a single command.
    git clone --no-checkout "$local_git_url" /tmp/checkout
    cd /tmp/checkout
    git checkout "$newrev"
done

The git clone would succeed – I guess a bad value for GIT_DIR doesn’t break that command – but git checkout would fail.

Of course, running these commands in an interactive SSH session worked just fine, because GIT_DIR hadn’t been set. This had me tearing my hair out for a bit until I found the exact error message on StackOverflow. After that, I discovered that the githooks manual addresses this problem as quoted above, notes that there are other variables aside from GIT_DIR that may cause similar problems, and includes the unset $(git rev-parse --local-env-vars) example to handle all of them. (I added an answer to the SO post that covers this.)

As described in Pro Git chapter 4.2, a bare repository is a repository that doesn’t contain a working directory. You can’t interact with the files in the repo directly. In the past, pushing to non-bare repositories was actively discouraged; now, Git makes allowances for doing that in some use cases. Regardless, a bare repository is the best plan for my specific use case. ↩︎
Git hooks are scripts that run automatically at certain stages, like on the client before pushing a commit, or on a server after receiving a commit. See the githooks manual for official documentation, and https://githooks.com/ for unofficial but very nice documentation. Developers may be familiar with the pre-commit project, which is a package manager for client-side hooks. ↩︎

Write a comment on the original post.

Inline shortcodes

Sun, 25 Aug 2024 20:19:39 -0500

I saw recently that Hugo supports inline shortcodes, allowing you to put the logic for a shortcode in a content file rather than in layouts/shortcodes/....

Depending on how your site’s content is authored, this may have security implications:

It is disabled by default for security reasons. The security model used by Hugo’s template handling assumes that template authors are trusted, but that the content files are not, so the templates are injection-safe from malformed input data. But in most situations you have full control over the content, too, and then enableInlineShortcodes = true would be considered safe. But it’s something to be aware of: It allows ad-hoc Go Text templates to be executed from the content files.

Inline shortcodes

At least for the moment, I’m the only author for any text processed by Hugo on my site. (That might change if I add comments or webmentions to the site content, but it’s how things stand today.)

So I can enable inline shortcodes with the security.enableInlineShortcodes configuration option, and then do something like this. For example, I might want to reference the date of the most recent update to my site in content. There’s a simple builtin function for this called .Site.Lastmod, and you can use Hugo’s time.Format to get the result in the format you prefer, but these are only accessible from templates (layouts), so using them in a content page requires creating a shortcode. With inline shortcodes, I don’t need a separate siteLastmod.html shortcode just to show this date. Instead I can do:

{{< siteLastmod.inline >}}{{ .Site.Lastmod.Format "January 2, 2006" }}{{< /siteLastmod.inline >}}

And that’s how you can read that this site was last modified on April 13, 2026.

The real power is shown by modifying the format. Without inline shortcodes, if I wanted this data on multiple pages, but sometimes as a YYYY-MM-DD datestamp, sometimes as Month D, YYYY, sometimes with a time component, and sometimes with a date component, I would have to build multiple shortcodes or a single shortcode with configuration options. With inline shortcodes, I can format the date the way I want right in the content file.

Write a comment on the original post.

me.micahrl.com til

Run Squid on exit nodes

How to

Application support

Caveats

git-lfs-transfer

Troubleshooting & references

Hugo non-page HTML resource

Alternative

References

Hugo render templates for links

Validating links with render hooks

Switching to render hooks

Intentionally linking to pages that cannot be validated

If render hooks are enabled, use % for shortcodes

A note on HAHAHUGO‍SHORTCODE placeholder values

hugo deploy, S3, and CloudFront

Pin prettier

Bash networking redirects

Prescriptions

Other references

Writing docs for Hammerspoon spoons

Documentation generation

Docstring format

Examples

hs.window.layout:setScreenConfiguration()

logger.lua examples

Explanation of types of doc strings in module.lp

Other files with docstring examples

git note

Writing notes

Pushing and pulling

Command line support

Web UI support

Argo Workflows path trigger

Trigger on any change

Trigger for specific path

Trigger for a list of paths

See also

References

Raspberry Pi and device tree

U-Boot needs its own device tree

The U-Boot device tree can be different from the kernel device tree

VideoCore needs device tree overlays (sometimes)

Example with separate dtb(o) files for U-Boot and Linux

Generate Kubernetes CRD documentation

scrollbar-gutter: stable

POSIX man pages on every system

Page-specific styles, scripts, and sprites

Use nosniff for universal browser display of web feeds

Discovery

Standard Ebooks

Matt Webb

My blog

Existing documentation

Transformed HTML on the macOS clipboard

View source isn’t good enough for links

pbpaste(1) can’t do it

Wait, what kind of data is on the clipboard?

Use AppleScript

lunr.js site search

Generate the lunr index with Hugo

Get lunr

Install lunr

References

Shortcodes and outputs

layouts/shortcodes/callout.html

layouts/shortcodes/callout.rss.xml

Updates

ExitStack

Mount static/ to assets/static/

text-size-adjust: none

Theorycrafting

What it looks like

References

Presentation selectors

Postscript

post-commit hook GIT_DIR

Implementation details

Inline shortcodes

If render hooks are enabled, use `%` for shortcodes

A note on `HAHAHUGO‍SHORTCODE` placeholder values

`hs.window.layout:setScreenConfiguration()`

`logger.lua` examples

Explanation of types of doc strings in `module.lp`

`pbpaste(1)` can’t do it

`layouts/shortcodes/callout.html`

`layouts/shortcodes/callout.rss.xml`