Justin Miller

Ten Years Gone

Wed, 29 Apr 2026 12:21:00 -0700

Though it’s not the day that I want to most remember her by, I can’t let today go by without noting that it’s been ten years since Michelle passed.

If you didn’t know her, or maybe even if you did, you can read her obituary or the eulogy that I gave at her funeral.

Instead, I choose to remember her by her adventures, by her unbridled enthusiasm for life and fun activities, by her generosity of her time to friends and strangers alike, and by her instigation of all of those things in others. Michelle was the ultimate instigator.

I think about Michelle every day, and while I miss her very much, the thing that still hits me the hardest is the fact that the world is missing out on having her in it.

Her first big run, the Sauvie Island half marathon; cuddling sled dog pups in Skagway, Alaska; visiting Slappy Cakes; enjoying a beer in the sun

Although it caused some difficulty at first, I consider it a testamant to Michelle that I was able to move on and continue a normal life relatively soon after she passed. Amazing support from family, friends, and my employer at the time was also a huge factor in this. I always heard Michelle’s voice in my ear, telling me to get out there and to keep soaking life in. I’m also very thankful for our house family, our cat Macy and our dog Ronny, both passed now, who helped me in that transition. There were days of just lying on the floor, crying with them, mourning.

Lying around, 2014. We always said this would make a good album cover.

I was very involved publicly with PanCAN right after Michelle died, even meeting with my senator in DC and being interviewed on live TV. But after a couple years, I found it difficult to continue this public outreach. I was very good at it — I was a top fundraiser and was recognized on stage, and the second year, I was the head of the Oregon delegation in DC. But doing that required that I keep the wounds very fresh, that I bring Michelle to life as my wife and to emphasize the hole left behind in my life. Maybe it could be done another way, but for me, it’s what felt right in that circumstance. But I found that I couldn’t continue doing that year after year. I support efforts in my own way now, but this public chapter has long been closed for me.

I have been so incredibly lucky to have two loves in my life, Michelle and now Jessica. Some days I can’t even believe the fortune with which I have been gifted. In a sense, Michelle and I grew into adults together, and the life we led with each other put me in a place where I was much more prepared to move on when she was gone. I am somewhat conflicted in saying that, but it’s how I feel, and I am incredibly thankful. You always hear as much, but I discovered firsthand that there is no right way to mourn, or to recover, or to move on. You have to do what it takes — for you — to keep yourself from unraveling entirely when such a tragedy hits.

They say that we have two deaths, one when we die physically and the other the last time there is someone alive who remembers us. I consider it my sacred duty to keep Michelle alive for as long as I can. If you ever want to talk, or to share — reach out. I am always here, remembering.

Changes fill my time, baby, that’s all right with me
In the midst I think of you, and how it used to be

Led Zeppelin, Ten Years Gone

Supercon 2025 Badge Hack

Mon, 01 Dec 2025 15:15:49 -0800

I greatly enjoyed Hackaday Supercon again this year after attending for the first time in 2023. Why did I miss last year? I don’t have a good reason, but it’s not happening again!

One of my favorite parts, and probably of many attendees, is the badge hacking. This year’s badge (announcement, GitHub, schematic) was an extra bonus as I love small handheld computers.

I spent a lot of Saturday in and around conference sessions thinking about possible hacks. Nothing was really jumping out at me other than maybe a tiny language interpreter, but I didn’t feel like that made for a compelling demo (watch me program on a tiny keyboard!)

When I got up on Sunday, I had a strong idea: using the ~~Shitty~~ Standard Add-On port which is on the front of Supercon badges to add a quick bit of hardware and write a graphical synthesizer keyboard. We’ve got PWM-capable GPIO, we’ve got graphics, we’ve got a keyboard. And serendipitously, the diagonal spacing on the SAO header between GPIO pin 1 and a ground is pretty close to the pin spacing of a simple piezo buzzer with minimal bending.

Thus was born Synthy Add-On.

Here’s my presentation of the hack at the closing session, about eight hours of attempted normal conference attendance after I hatched the idea:

You can also watch the video of everyone’s hacks!

My code is over on GitHub. True to the spirit, it’s pretty hacky, especially the graphics drawing placement, but the core of things, the synthesizing, is pretty simple and clean.

Basically I’m just using pulse width modulation on GPIO pin 1 (which corresponds to the top right pin on the SAO header) to configure and create a square wave. The frequency corresponds exactly to the musical note frequency (since that’s how sound works) and the duty cycle can be used for either a normal 50% square wave — 512 (half of the 10-bit max) corresponds to note on — or by setting it to zero (unlike a frequency of zero, which has unexpected noise) you can get a note off.

I edited things right on the badge using Thonny on my laptop, which bills itself as a “Python IDE for beginners” but I find really nice even for complicated on-device MicroPython work (which this isn’t, really).

A couple other implementation notes:

I grabbed the note frequencies from a standard chart that I found online.
I modeled the keyboard after that of Apple’s GarageBand.
I made a note auto-off of 250ms, but interruptible by continued user action. That way, if you tap a note, it will play for a short time, but if you tap a number of notes in succession, it will switch the pin output to play the new note right away. I do the auto-off by keeping track of when the last note started, then each pass of the main program loop, checking if 250ms have passed yet.
I tested things around the conference using my pocket oscilliscope instead of audio output, which was both fun and, I’m sure, appreciated by those around me trying to get their own work done.
One of the trickier bits was figuring out the API for the LVGL MicroPython bindings. While I appreciate the work put into them, it’s one thing to have docs for the C API, but another entirely to then have to mentally figure out how constants, function names, and other structures have been ported to MicroPython. I’m sure it’s easy for anyone immersed in LVGL already or who knows the library backwards and forwards, but for someone trying to build something new, it’s a lot of work. Some of the links that I found helpful:
- advanced demos on DeepWiki
- these examples, especially lv_canvas.py
- this LVGL forum post
- these canvas examples
Given more time, I would have done more and cooler sound synth such as some of David Johnson-Davies’ projects like his Tiny MIDI Player. I’ve played with some of his ideas before and was greatly inspired by them for my PCB Christmas tree ornament among other projects.

Special thanks also to John Bates from here in Portland who was also down at the conference and who I just knew would have a piezo lying around that I could use (he gave me five, and also had both 3.3V and 5V available).

Lastly, unrelated to my badge, I also gave a seven-minute lightning talk about Catch the Wave! which you can find on my talks page.

Happy hacking!

When Having a Computer Was Weird

Wed, 09 Oct 2024 00:00:00 +0000

I just finished up the first weekend of my vintage computer exhibit for Portland Design Month entitled When Having a Computer Was Weird: A showcase of early personal computers. I had two fun groups of visitors and I plan to run another date on October 18, plus others as time permits and interest demands.

I have eight vintage computers from my collection on display, working and ready for people to try:

Atari Video Computer System (a.k.a. Atari 2600, 1977)
Texas Instruments TI-99/4A (1981)
Commodore 64 (1982)
Commodore 128 (1985)
Radio Shack TRS-80 Model 100 (1983)
Dolch PAC 386-25 clone (1989)
Macintosh Plus (1986)
Power Macintosh 8500 (1995)

All of the machines are kitted out with various accessories such as game cartridges, CRT displays, cassette tape program loading and saving, disk drives and floppies, joysticks, musical keyboards, manuals, and contemporary books and magazines. Visitors can play games, write documents, try applications, or craft programs.

A computer museum

This exhibit is a stab in the direction of something I’ve wanted to do for a while, which is to create a space locally where people of all ages can experience yesterday’s computing technologies firsthand. Eventually I would love to see a space like this with many more examples, staffed by local volunteers, experts, and enthusiasts.

Aside from my own experience with this era of computing, I intend this as an homage as well to the old, old Powell’s Tech bookstore, back when it was on the North Park Blocks here in Portland.

Circa 2007 (Flickr user the_impression_that_i_get)

While the computers there were merely decoration around the shelves, seeing them in person evoked a strong sense of technological history when I first experienced it over twenty years ago.

These days, Powell’s Tech is folded into the main site on West Burnside and these computers have scattered to the wind, like so many before them. We are only ever seeing less and less of these older computers, especially in their full usable glory.

Some Powell’s Tech interior photos from 2010 (Flickr user caseorganic)

Right at home

I decided to host this event at home, having moved earlier this year and now having a large garage workshop for this sort of thing. I used some hanging drop cloths to block out the distracting parts of the building and I setup table displays around the room.

And I’m pretty happy with the end results.

Being at home, I was also able to make some last-minute repairs and tweaks on various machines as needed.

Gallery

I’ve leave you with some closeup photos of things setup and running, along with their rough thematic groups from the original exhibit proposal.

On The Living Room TV

The Rise of Commodore

Going Mobile: Walk Before You Run

The Ascent of Apple

Special thanks

I’d like to give a shout out to Tyler Morrison for table, chair, and BlueSCSI lending, Jared Boone for CRT TV lending, Andrew Kreps for late-game 3D printing, Travis Smith for his excellent TeensyROM and its prompt delivery, and my peeps at NSPDX for moral support, ideas, and general hilarity during projects.

The exhibit is ongoing

If this is something that interests you or someone you know, there’s still time to see it. I have one other definitive day of exhibit groups on October 18, plus could add more if there is interest. Please spread the word.

Creating an electromagnet and sound wave learning environment

Wed, 11 Sep 2024 00:00:00 +0000

I’ve been meaning for a while to write more about one of my recent projects, Catch the Wave!. Originally it was made for last year’s Oregon Science Festival and since I’m exhibiting again at the festival this year (this weekend, in fact!) I thought now was as good a time as any.

What is it?

Catch the Wave! is a public science education project, with the side goal of bettering my own ability to make a museum-caliber interactive experience.

The project is a series of four small, colorful, table-top wooden cabinets with physical controls and screens, each of which explores a concept related to electromagnets and sound waves and how they are used for audio recording and playback.

Catch the Wave! has been a personal challenge and a labor of love. Aside from the building of it, I’ve staffed several full days’ worth of events at multiple locations in order to benefit the community at large in an educational way.

Why?

The main prompt for this project was an opportunity to submit a proposal for my local science museum’s inaugural STEM event — the Oregon Science Festival.

Beyond the initial event, I’ve been wanting to work on something for the public that is more portable than, say, an eight-foot xylophone, more directly learning-oriented, and something in line with my continued interest in synthesized audio and waveforms.

The four stations

The exhibit is meant to be approached in order, each station building upon previous stations’ concepts.

Station 1: What is an electromagnet?

What is an electromagnet? Turns out, if you wrap some lightly-insulated wire around a metal core and then run electrical current through it, you create a magnet. Turn the current on, it’s a magnet. Turn it off, it’s just a coil of wire. You can directly experience the connection between electrical current and magnetism.

Participants can push a button to run current through a professionally-wound electromagnet and get paper clips to stick when it’s on. Jaws typically drop when this is demonstrated and it’s begging for hands-on fun as people attempt to see how many they can get to stick.

Sorry, your browser doesn't support this embedded video, but you can download it directly.

Download the handout PDF

Station 2: Changing magnetic polarity

If you run current through the coil in one direction, the magnet’s polarity is aligned a certain way (you can read more about the right-hand rule). If you reverse the current, you reverse this alignment. So the second station is a larger version of the first station’s electromagnet hooked up to a two-way toggle switch. Suspended above the electromagnet is a permanent, regular magnet on a swing which can be attracted and repelled as the magnetic forces change. So now you can see how electrical current and physical motion are related! Folks seem to also have a lot of fun with this one as they attempt to get the swing to move the most distance or to see how fast they can switch the current’s direction.

Sorry, your browser doesn't support this embedded video, but you can download it directly.

Download the handout PDF

Station 3: Fast changes make sound

Imagine if you could flip that switch, as well as the magnetic polarity, hundreds or even thousands of times per second. Or imagine it more like a slider, controlling how much current flows in a direction. A computer or a synthesizer is able to do this electronically. If you then have a thin membrane like paper or plastic that can be moved by this physical interaction between the permanent magnet and the electromagnet, the vibrations of the membrane vibrate the air around it. If your ear is close enough, and the number of vibrations is in a certain range, the vibrating air also vibrates your eardrum and you can hear a sound! This is what we call the frequency of a sound.

The station lets you play with a knob to adjust the frequency in the audible range, as well as the waveform.

Sorry, your browser doesn't support this embedded video, but you can download it directly.

Download the handout PDF

You can think of the waveform as the pattern of movement of the membrane. Quickly switching between fully one direction and fully the other is a square wave. Switching more slowly in one direction, but quickly in the other could be described as a sawtooth wave, rising before sharply dropping.

These waveforms sound different to our ear. And you can even feel the sound by touching the center of the speaker at the lower frequencies, much like how you can feel a subwoofer’s sound. This is because the membrane vibrations are moving the tissue in your body as well as the air around you.

Even at its most basic level, people have fun with this station since it makes noise and has very hands-on controls.

Station 4: Complex waves

The last station lets you record your own voice into a microphone, then play it back, optionally with effects applied like pitch shifting, reversing, and echoing. The same electromagnetic principles are at work in this system, but here you can just focus on the fun of sound.

Sorry, your browser doesn't support this embedded video, but you can download it directly.

Download the handout PDF

The everyday sounds around us like speech, music, or nature rarely sound just like synthesized sound coming from a computer. This is because they are formed of many overlapping and interacting waves to add richness to the patterns. Using electromagnets, we can record the electrical signals made by sound and then computers can alter these signals before playing them back.

People love hearing their own voice in “chipmunk style” or a lot higher or lower frequency than their normal speech. It’s a very concrete way to see how these concepts apply to everyday life and to practical effects.

Reactions to the project

I’ve gotten a lot of feedback from kids and adults alike about how much they like the progression of concepts in the project. People range from having no idea about how any of this worked to being involved directly with some of the concepts — musicians, equipment builders, teachers, and others — but still taking something away from the stations’ hands-on nature. It’s been very gratifying for me to give something to people in this way.

Future installments

In future posts, I’d like to talk about some of the build details as well as some of the educational considerations and takeaways that went into and resulted from this project.

Chromebooks are amazingly hackable!
They don’t have to even look like Chromebooks!
Table saws are wonderful tools for repetitive work!
Sanding, priming, painting, and clearcoating is a laborious process!
Some kids have never seen an audio speaker!
Kids can have fun with tech that isn’t a touchscreen!

And speaking of kids and having fun, I knew this already in the abstract, but kids can always educate you very directly when it comes to user interfaces and the gulf between their intended and real-world uses. I feel like as with many projects, I’ve learned a lot myself even with this project that was intended as a teaching experience.

As with all of my projects, please get in touch if you’d like to talk about Catch the Wave! or get more info.

fari: fast Safari tab browsing

Sun, 21 Jan 2024 21:11:42 -0800

I’ve been hacking on and off for a few years on a little open source side project, fari. It’s a terminal-based utility for the Mac for quickly zipping through the tabs that you’ve got open in Safari.

Recently, I started picking it back up again as I have been meaning to apply some research into getting at Safari’s iCloud Tabs and even Tab Groups.

iCloud Tabs are a way to see — and open locally — any browser tabs that you might have open on another iCloud-enabled device — including an iPhone or iPad. This is nice if you start reading in one place and want to continue somewhere else later, or if you’ve got a machine physically elsewhere and want to get at its tabs. This feature has been around in Safari for a few years.

Safari Tab Groups are a bit newer and are a way to create and manage named groups of tabs that are easily accessible to all of your devices. They’re meant to be more project-based, where you can open a window for a group and work with it, then put it away for another time — on this device or any other.

While I haven’t released it yet, I’ve been hacking on improvements to fari to handle both of these types of cloud-based tabs quickly and efficiently.

Here’s a quick overview video of the features fari has now, as well as how iCloud Tabs are coming:

I’ll likely post here when a new release happens or you can just watch the GitHub project for progress.

Winter Walk

Sun, 14 Jan 2024 16:43:50 -0800

Took a ~4 mile walk in the newly-snowy neighborhood this afternoon. For the first time in years, I grabbed my camera to go along.

I need to retrain my eye to look for photo opportunities. Feeling a little rusty so far.

You can read a bit more about Futel and the payphone here.

How my link blog works

Thu, 11 Jan 2024 11:46:34 -0800

Despite not posting stuff as much as I’d like to get around to on this site, I do keep my link blog pretty active. It lets me share publicly some links to things on the web, sometimes with commentary.

I run the Hugo content management system, but the generalities could apply to a lot of systems if this is something that you’d like to replicate.

Here’s an overview of how I use it and how it works. The moving parts are:

Saving links while browsing
Bringing content into Hugo
Displaying content in Hugo
Creating an RSS feed

Saving links

While I’ve technically got content currently from four places — Pinboard (my account is private by default on that site), GitHub starred repositories, and Thingiverse and Cults likes of 3D printed designs, only the first two are really active, so I’ll focus on those as examples in case they might serve as inspiration for your own sort of system.

I’ll start with GitHub. All I do is press the star button on a repository. Easy. Something I was doing already anyway.

For Pinboard, I use one of the bookmarklets, which is way of using a bit of JavaScript code as a browser bookmark that, when visited, will capture information about the current page and turn it around into a Pinboard posting popup window.

The bookmarklet code:

javascript:q=location.href;if(document.getSelection){d=document.getSelection();}else{d='';};p=document.title;void(open('https://pinboard.in/add?url='+encodeURIComponent(q)+'&description='+encodeURIComponent(d)+'&title='+encodeURIComponent(p),'Pinboard','toolbar=no,width=700,height=350'));

In order to streamline this, I made a Safari-specific keyboard shortcut, ⌘B (hat tip to this StackExchange post for info on producing the ⌘ symbol).

This works because you can setup keyboard shortcuts system-wide in any app by menu item name and I’ve appropriately named the bookmarklet, which shows up in Safari’s Bookmarks menu, even though I never use it there. Just having it buried somewhere in the Mac menu system for Safari is enough for the shortcut to be able to access it.

For Pinboard, there’s also a page of posting clients, so you do you. I actually used to work on my own Mac-native posting client, Pukka, but it is, alas, no more. It was part of what got me interested in Pinboard in the first place.

When posting a link to Pinboard, there are five things that I do specifically for my system.

I might highlight some page content before using the bookmarklet, which gets transferred into the description field as a starting point (document.getSelection() takes care of this above).
I remove any tracking or other query string crap from the URL so that it is clean for the next person.
I edit out the oft-added site name at the end of the page title.
Alongside my normal tags, I add a special tag (links) if it’s something that I want to show up on this site.
Optionally, I add or edit the commentary, possibly with quoting (using Markdown’s >).

I use Markdown in the description since this will eventually get piped through to my site and rendered by Hugo. I like sparing use of italics (_foo_) or bold (**bar**) and sometimes bullet lists (- baz).

With both GitHub and Pinboard, I can bookmark while I’m browsing, not have to think about it very much, and move on.

Bringing content into Hugo

The next part of the system is something that I’ll either do manually on a fairly regular basis or as part of my deployment of other new content (like this post) on the site.

Basically, for each link source, I’ve written a Python script to use its API to download content. There is a lot of potential for reuse between them still, and I’m not proud of the code, but it’s for me and it works. I’d consider releasing them, but this does not come without the possibility of support. I’d rather this post serve as an inspiration for similar systems.

For GitHub, I use their stars endpoint, which doesn’t even require authentication, since this is public data.

USERNAME = 'incanus'

STORE = './data/links/github_stars.json'

PER_PAGE = 100
URL = f"https://api.github.com/users/{USERNAME}/starred?per_page={PER_PAGE}"
HEADERS = {
    'Accept': 'application/vnd.github.v3.star+json'
}

The paging allows my script to compare results with what it has on disk and only grab recent pages of results as needed.

After some munging, I store things into the JSON file in the sort of place where Hugo likes data.

For Pinboard, I use my account username and password and their API.

STORE = './data/links/pinboard_public.json'

TAG = 'links'

PER_PAGE = 100
URL = f"https://{USERNAME}:{PASSWORD}@" \
      f"api.pinboard.in/v1/posts/recent" \
      f"?tag={TAG}&format=json&count={PER_PAGE}"`

Similar sort of thing here — munge the various fields in the JSON received from Pinboard into a common format for Hugo in its JSON on disk.

Displaying content in Hugo

I feel like Hugo’s page on data templates does a pretty good job of explaining how it works. In my case, an individual entry in a link data file (regardless of source) looks something like this:

{
    "name": "The Un-Brie-Lievable History of Tyromancy",
    "description": "> Predicting the future using cheese is something I do as a side business, and from what I can tell, there aren\u2019t very many of us doing this anymore.",
    "url": "https://www.saveur.com/culture/tyromancy-cheese-divination/",
    "date": "2024-01-11T19:07:39Z",
    "kind": "pinboard_public"
}

One thing that I don’t bring through is my Pinboard tags, since sometimes these refer to private projects or I otherwise don’t want to post what I’m tagging things under.

And it’s the kind field that I use to distinguish in my rendering code how things are displayed.

An entry on the links page looks something like this:

I like a terse version of the domain right after the title, and at the bottom, a permalink and bookmark date.

For GitHub stars, I pull the repository description if it exists so that things look like this:

Here’s what’s in my layouts/section/links.html to accomplish this, broken down a little.

First, start off the page by pulling a parameter from my config.yaml related to how many links I want to show per page.

<div class="posts">
{{ range (.Paginate .Site.Params.Counts.LinksPage).Pages.ByDate.Reverse -}}

Then, output the title linking to the URL and munge the link domain a bit to clean it up.

<article class="post">
  <h2 class="post-title"><a href="{{ .Params.target }}">{{ .Title }}</a></h2>
  {{- $domain := (urls.Parse .Params.target).Host | replaceRE "^www." ""}}
  <p style="font-size: 0.75em; color: gray;">{{ $domain }}</p>

For the main body of the entry, depending on what type of link it is, I’ll do some processing.

For GitHub stars, fill in a default description (since a lot of repos don’t have one) and display that description as if it were quoted content.
For Thingiverse or Cults likes, include a thumbnail image of the model.

{{ $desc := .Content }}
{{- $desc := (cond (eq (chomp $desc) "") "_no description_" $desc) -}}
{{- $desc := (cond (eq .Params.kind "github_star") (printf "> %s" $desc) $desc) -}}
{{- $desc := (cond (or (eq .Params.kind "thingiverse_like") (eq .Params.kind "cults_like")) (delimit (slice "<a href=\"" .Params.target "\"><img src=\"" .Params.thumbnail "\" style=\"width: 350px; margin: 20px 0px 25px 0px; box-shadow: 5px 5px 10px lightgray;\"/></a>") "") $desc) -}}

Here’s what a Thingiverse entry looks like.

In all cases, I run the resulting description through a few Hugo filters to render it safely.

<p>{{ $desc | markdownify | emojify | safeHTML }}</p>

Lastly, I add the permalink and date and close out the entry.

<a href="{{ .Permalink }}"><time datetime="{{ .Date.Local.Format "2006-01-02T15:04:05" }}" class="post-date">🔗 {{ .Date.Local.Format "Mon, Jan 2, 2006 at 3:04pm" }}</time></a>
</article>
{{- end }}
</div>

Individual link pages (something I added fairly recently, after a few years with this system) are more or less the same, just in layouts/links/single.html instead.

The link pages themselves have permalinks, so that each link that I’ve put on my site has a permanent page on which to live, allowing anyone else to link to that if they like. Is anyone doing that? I don’t know. I’d just like to give them the option. At the very least, it lets me link to my link-of-a-link, in case I want to pass my version (and commentary) of the link to someone else. And most importantly, I have my own links backed up, locally, in my website code. Combined with a paid Pinboard account’s archival service, this is a pretty good personal copy of my stuff.

The permalinks and the pages they link to get generated by a little links.py that I run. They look like this:

---
title: "jstasiak/python-zeroconf"
date: 2020-05-02T19:38:41
target: https://github.com/jstasiak/python-zeroconf
kind: github_star
---

A pure python implementation of multicast DNS service discovery

This file, as an example, lives forever at content/links/07bsoxfTSm.md.

The one thing that took some puzzling here (most of it is mungy-munge on the data JSON into the Markdown file) is the unique URL string (07bsoxfTSm above). I landed on the Sqids library for this, using it like so:

sq = Sqids(min_length=10)

[...]

for kind in kinds.keys():
	l = run('ls content/links/*.md', shell=True, capture_output=True)
	l = l.stdout.decode('utf-8').split('\n')
	with open(f'data/links/{kind}.json', 'r') as f:
		schema = kinds[kind]
		j = json.load(f)
		for b in j[schema['container']]:
			d1 = int(datetime.fromisoformat(b['date'][0:-1]).timestamp())
			d2 = len(b[schema['metadata']] or '')
			h = sq.encode([d1, d2])
			if not f'content/links/{h}.md' in l:

[...]

The script will, for each kind of link, compare the data file with the existing links files on disk in content/links to see if any links need a page generated for them. They then spit out the above content stub pages for Hugo to pickup and render according to the layouts/links/single.html template.

The Sqids-generated ID is based on a combination of the bookmark date (d1) and the “metadata” of the bookmark (d2) which is either the description text or, for the thumbnail links, the thumbnail URL. I’ve got to commit to a certain description before publishing the final version if I don’t want the “permalink” to change.

I realize that I am skipping a lot of functionality here, as well as assuming a large amount of familiarity with Hugo and its usage. Again, I hope this gives you some ideas on a way (not the best way! not necessarily the way for your site!) that you could accomplish such a thing.

This is very much a hacker’s way of jamming things together to just barely work, but it does the job for me. I’m fully aware that this is not for the average writer on their site. And it saddens me quite a bit to consider that in the past 15 or 20 years, instead of bringing this sort of functionality to everyone, instead we have giant data silos like Facebook or unprogrammable-but-nice site management solutions like Squarespace. The best I can hope for right now is to maybe show other hackers how I did this. I like sharing (and reading!) glimpses of others’ techniques as much as I like reading everything else on the web.

Creating an RSS feed

Speaking of nerds, the last bit of this system is an RSS feed. At this point, you’d probably not be surprised (or you know already) that Hugo makes RSS feeds quite easy.

There is a page stub at content/pages/links.xml.md that puts the feed in the right place.

---
layout: links
title: Links
url: /links.xml
outputs:
  - rss
---

And there is a layout template at layouts/pages/links.xml that builds up the feed XML.

{{- printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>{{ .Site.Params.Author }} - Links</title>
    <description>{{ .Site.Params.Description }}</description>
    <link>{{ ref . "links.md" }}</link>

[...]

This is perhaps the most concise example of how Hugo combines content files and layout files in order to create the final rendered pages. Sometimes the content is in the actual page, but oftentimes, like this, it’s all in the layout (combined with data files) instead.

Once again we’re looping through the site content, with LinksFeed as the item count so that it can potentially be different than the HTML version.

{{- range first .Site.Params.Counts.LinksFeed (where .Site.RegularPages "Section" "=" "links").ByDate.Reverse }}

And an individual link RSS entry looks like this.

<item>
    <title>{{ .Title }}</title>
    <description>
        {{- $domain := (urls.Parse .Params.target).Host | replaceRE "^www." "" -}}
        &lt;p&gt;&lt;code&gt;{{ $domain }}&lt;/code&gt;&lt;/p&gt;
        {{- $desc := .Content -}}
        {{- $desc := (cond (eq $desc nil) "_no description_" $desc) -}}
        {{- $desc := (cond (eq .Params.kind "github_star") (printf "> %s" $desc) $desc) -}}
        {{- $desc := (cond (eq .Params.kind "thingiverse_like") (delimit (slice "<a href=\"" .Params.target "\"><img src=\"" .Params.thumbnail "\" style=\"width: 350px;\"/></a>") "") $desc) -}}
        {{- $desc | markdownify | emojify | html -}}
        &lt;p&gt;&lt;a href="{{ .Permalink }}"&gt;🔗&lt;/a&gt;&lt;/p&gt;
    </description>
    <pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
    <link>{{ .Permalink }}</link>
    <guid isPermaLink="true">{{ .Params.target }}</guid>
</item>

A lot of this is a variation on the HTML version, so I won’t cover much of it. I just wanted to show some of the RSS/XML-specific tweaks needed to make this all work.

Wrapping up

I do feel like I moved through this rather quickly (and it’s still long!) and again, it is admittedly Hugo-specific in its code content. I hope that it can be useful, though, to see how to build up such a system, as well as to highlight the fact that it takes an experienced programmer and somewhat half-assed blog author at least a dozen programming languages and/or data formats to put something like this together 30+ years into the web. I guess I started out enthusiastic about sharing some useful technical bits, and ended up rather pensive about an end result that I feel should be available to more people.

However, I think that this shows another good reason to blog, which is to actually take a moment to reflect on it all and assess the state of things. In that vein, I’d be curious to hear what other folks think about this or what they use for similar systems.

Repurposing Hugo as a wiki

Wed, 27 Dec 2023 16:04:34 -0800

As part of a project that I’m working on, I decided to see if I could repurpose the excellent Hugo website framework (which also powers this very site) as a single-user wiki of sorts.

Short version: yes!

Requirements

The main features that I wanted were:

The ability to, while writing a page, freely link to other topic pages that I know will (or at least plan to make) exist in future, without having to worry about if they exist right now.
An automatically-updating visual indication of whether a linked-to page does or does not exist yet.
A common “coming soon” page that the missing links will land on (i.e. no actual 404’s for content linked in this manner; normal site 404 functionality is untouched).
The simplicity of writing in Markdown that I am so used to already, especially because this is a technical project featuring lots of code syntax highlighting in the content.

Why not <wiki software X>?

The main reason that I didn’t want to use an established wiki package like MediaWiki, the software behind Wikipedia, was that it seemed like overkill. For this project, I don’t need separate authors, I don’t need revisions of pages, and I certainly don’t need a database server.

Hugo exists to create static HTML websites, supports Markdown formatting, is fast, and has a powerful shortcode system which can be extended.

So let’s make it happen. But first, before I get too far into the weeds, let’s take a look at the end result and how simple it is to use while writing.

Using the custom shortcode

I created a custom shortcode called link. Here’s how you use it.

For linking to a page where the page slug is the same as the word you want clickable:
```
{{% link other %}}
```
This will produce the link text other linking to /pages/other/.
For linking to a page where you want to make clickable some custom text:
```
{{% link "my text here" other2 %}}
```
This will produce the link text my text here linking to /pages/other2/.

That’s it. But critically: if in the above examples the pages other or other2 don’t exist, the link will be styled in a noticeable way (in my case, red instead of blue) and will link to (also, in my case) /pages/missing/. Whenever I get around to adding said page, all existing links to it will auto-update and become blue in future.

Overview of components

A few things need to happen to bring this configuration together.

Enable Goldmark renderer “unsafe” mode. This allows rendering of inline HTML in shortcodes. A reason why you would not want this enabled is if you have untrusted users and/or untrusted content. For me and this project, neither of these apply.

In your hugo.yaml:
```
markup:
  goldmark:
    renderer:
      unsafe: true
```
Create and configure the common “missing” page and make it so that unreachable-by-Hugo pages are not fatal errors in the rendering process.

In your hugo.yaml:
```
refLinksErrorLevel: WARNING
refLinksNotFoundURL: /pages/missing/
```
Create the shortcode. As per above, I used the name link, which means I created a layouts/shortcodes/link.html containing the following:
```
{{- $link := (urls.RelRef . (cond (eq (len .Params) 2) (.Get 1) (.Get 0))) -}}
<a href="{{ $link }}"{{ if eq $link (relref . "missing") }} class="missing"{{ end }}>{{ .Get 0 }}</a>
```
Please forgive the line wrapping. Since a shortcode gets replaced inline in your content, and since I didn’t want to add extra spacing or linebreaks in my content, the shortcode is just two (long-ish) lines.

Configure the missing class in your theme’s CSS.

main#content a.missing {
  color: #f00;
}

How the shortcode works

The shortcode took the most work, as the other bits were just a little configuration tweaking and some strategic web searching in order to puzzle through some minor issues. Here’s how it works.

Line 1: Resolve destination

In the first line, a $link variable is created which benefits from the flexibility of specifying either one or two arguments to the shortcode — one if the page slug and linked text are the same, and two if they differ.

{{- $link := (urls.RelRef . (cond (eq (len .Params) 2) (.Get 1) (.Get 0))) -}}

I will add that spending a lot of time recently in Lisp and other similar languages which are composed of S-expressions has made Go syntax like (cond (eq (len .Params) 2)... much more natural to me.

The best part about the use of urls.RelRef in the link buildup is that the links are filename- and reorganization-independent. If you use a destination page filename of other.md, a shortcode argument of other will find it. If you use a filename of other-page.md but a slug within its front matter of other, it will also work. If you change the location of resources but keep either of these the same, it will be found. And finally, if the page cannot be found (likely because it doesn’t exist yet, one of the requirements of tolerance in this system), the “missing” common page will be linked (in my configuration above, /pages/missing/).

Line 2: Conditionally style link text

Moving on from the $link setup, the other line of the shortcode sets up a standard HTML anchor link <a> tag highlighting the shortcode’s first argument as the link text. Most importantly, if the link resolves to the common missing page, this can be detected and the custom “doesn’t exist yet” CSS is applied to the link.

<a href="{{ $link }}"{{ if eq $link (urls.RelRef . "missing") }} class="missing"{{ end }}>{{ .Get 0 }}</a>

Astute readers and/or optimization nerds will notice that this technically relies on duplication of the missing term — once here and once in the hugo.yaml part which sets up the missing page for failed urls.RelRef resolution. While I would have liked to avoid this, no Hugo function exists to get at the same of the refLinksNotFoundURL variable specified in the site configuration. The closest I got was .Site.Config, but that only exposes the services and privacy keys as a subset of the configuration. Argh, code duplication.

Exciting conclusion

All in all, I’m quite happy with this. While I’ve only really begun the actual buildout of the site for which this system was contrived, it’s already reducing mental overhead and allowing me to see some structure to the site without having to worry about writing it all or even creating placeholder page files for now.

It’s definitely a case of The General Problem, though.

What can I say? I’m most certainly a developer and toolmaker at heart. I prefer to take inspiration here from Abraham Lincoln as quoted in the previous link:

If I had six hours to chop down a tree, I would spend the first four sharpening the axe.

Bonus: Visual Studio Code snippets

Not content with a mere single level of yak shaving, and in keeping with the spirit of the preceding section, I also wanted a quick way to insert these shortcode-based links into my writing. I learned about VS Code snippets which are both easy and powerful, and I was able to create a project-specific .vscode/snippets.code-snippets file with the following:

{
  "Insert wiki page link": {
    "scope": "markdown",
    "prefix": "link",
    "body": ["{{% link ${1:linked text} ${2:slug} %}}"]
  }
}

Then, in my project, whenever I type link, I can Tab to get a popup suggestion with tab-completion into the two fields for easy fill-out. And if I only want one shortcode argument, I can easily delete the second tabbed-to argument.

Bonus 2: Extra-meta

In the process of writing this post in Hugo and about Hugo, I discovered a puzzler of a problem with including the example shortcode in the usage and snippets examples — the shortcode doesn’t actually exist on this site, but was still being interpreted by Hugo as a shortcode in this post’s content, causing the page render to fail. Bless this kind soul, Chris Liatas, for writing about a technique to work around this using C-style code comments, thereby allowing me to display unparsed Hugo code in a post about Hugo code within a system running Hugo code.

See the discussion about this post on Lobsters.

Now page year-end 2023

Fri, 22 Dec 2023 11:35:48 -0800

I just updated my now page. I like it because it’s something I can do three or four times a year, pretty casually, and feel like I’m not so behind in talking about WTF I’m actually doing with my time.

And it’s a nice way to reflect a bit and regroup.

The wave's been caught

Mon, 18 Sep 2023 11:19:24 -0700

I successfully finished and “shipped” my booth, Catch the Wave!, at the inaugural OMSI Oregon Science Festival this past weekend.

I don’t have a good sense of how many people I interacted with over the course of the two days, but I would guess somewhere in the mid- to high-hundreds. There was very little downtime from 9:30-5:30 both days, and because my experiment stations were setup in an ordered way, I don’t think I could have handled any more people than I did.

Broadly, my personal goals for this project, aside from obviously making a compelling booth, were:

trying my hand at a science museum-caliber build
getting better at my planning and execution process
making something more transportable and reusable in future
exercising some educational concepts I’ve been working on in another project

I hope to write up more soon about what I made, as well as the multi-month process leading up to it, but for the next few days at least, I’m taking a bit of a break — still with other projects I need to work on, though. I always have intentions of writing things up more, and this time I am taking them very seriously as a way to continue using this project in other contexts. I am trying to see the after part of the project as just as important as the making and showing parts.

Roughly, the work on this project involved:

researching electromagnetic concepts
designing fun and compelling hands-on demos for a variety of ages
acquiring, re-flashing, and repurposing second-hand Chromebooks
designing, building, painting, finishing, and securing wooden enclosures
sourcing electronic components
3D printing enclosure and experiment parts
designing, laying out, soldering, and enclosing electronics
writing microcontroller firmware
writing apps for the display screens to interact with the electronics
designing, laying out, printing, and laminating accompanying visual guides
designing and ordering stickers
designing, setting up, and hosting a web-based discussion forum

I can only seem to do one of these types of projects every year or two, as they are mentally and, near the end, very physically exhausting. While I have detailed planning and concepting stages throughout, I always seem to be very deadline-driven when it comes to putting on the final touches to what becomes the eventual project. I’m going to spend some time reflecting on that, as I always do, and see what I can learn about myself and my process. I will say that this time only involved a few hours at the end of “wow, I’m desperate for this project to be over so I can get off this ride”, rather than days or weeks.

All of the toil to ship a physical thing that is used by the public is worth it, though, for moments like these.

Special thanks to Jessica for support, staffing help, and last-minute laminating, and to Sam and Jenni for stopping by and giving me a bit of a break.