alanwsmith.com

Music for Today (March 15, 2026)

Sun, 15 Mar 2026 18:40:34 -0400

I published a big block of work last night. Stayed up super late to do it.

Today, I'm zoned out. In the post-deployment come down. I've mostly been poking around youtube. Lots of music in the mix.

A few selections from the day.

Down to the River to Pray - The Petersens

Tom Waits - "Get Behind The Mule"

Going to California - Led Zeppelin - Sierra Eagleson Cover

Getting Ready to Get Down - Josh Ritter - 2017-13-05

San Fermin - Daedalus

the Mountain Goats - This Year - Jordan Lake Sessions

Siren Song - Didn't Leave Nobody but the Baby - O Brother, Where Art Thou

Lake Street Dive feat. Tiny Habits - "Leaving on a Jet Plane" - Live From the Road

Chet Faker - Gold

San Fermin - Daedalus

Sweet Child O' Mine Bluegrass Cover - Thunder and Rain

Can't Find My Way Home (Blind Faith) - Rachael Price - Live from Here with Chris Thile

It's gray outside. A light rain. Perfect for the chill mood.

-a

You can't update an input text value with keydown

Sat, 14 Mar 2026 12:03:28 -0400

It doesn't look like there's a way to update the value of an <input> field with keydown events.

You can, of course, just update the value directly.

Simulating keyboard interactions needs to be done with something like puppeteer.

Update CSS Live using contenteditable (No JavaScript Required)

Sat, 14 Mar 2026 09:49:58 -0400

Dear RSS Reader:
The original version of this page includes custom CSS to style the page. It probably won't work in here. Check out the original page to see it in action.

I was reading the HTML Living Standard for contenteditable to figure some stuff out for bitty¹. Found a fun little tidbit: You can edit CSS live on a page without JavaScript.

Check this out:

HTML

<div class="example">the quick brown foxdiv>

<style class="style-editor" contenteditable="plaintext-only">/* change the color to green */

.example {
  color: crimson;
}
style>

Output

the quick brown fox

The contenteditable attribute does most of the work. The only other thing you need is to make the contents of the style tag visible by applying a display: block to it with something like:

CSS

.style-editor { 
  border: var(--default-border);
  display: block; 
  margin-block: 1rem;
  padding: 0.7rem;
  white-space: pre;
}

First thing that comes to mind to do with it is to set up a process on the backend that you can submit it to. It would update your actual stylesheet with it. Basically, live, on-page editing with immediate deployment.

A nice little reduction in friction.

-a

Endnotes

Editing your global styles would be nice. Even better would be creating a supplemental stylesheet for each page. You could apply whatever tweaks you want directly on the page then just have them go live.

(Of course, it wouldn't have to be an external stylesheet. You could just have your CMS embed the custom styles directly on the page.)

Probably less practical, but you could write a browser extension that opens any pages CSS in a little window to change things live that way too. What would be more interesting is to see if you can select/click on something and get its styles in an editable box on the page.

It would save you from having to open the console to kill the thing where sites disable the ability to paste a password.

You might be able to add syntax highlighting too. I'm not set up to test that at the moment.

Footnotes

^{1 ⤴}

bitty - a little front-end framework for the web

Restart fseventsd on a mac

Fri, 13 Mar 2026 22:12:29 -0400

if fseventsd is taking 100% or more of a CPU you can restart it by quitting it in Activity Monitor (after which it restarts automatically).

Open Activity Monitor
fseventsd will probably be visible if it's having an issue. You can also search for it, if it's not for some reason.
Double click it.
Click Quit in the pop-up window.

It's usually not an issue, but when my machine has been up for a couple weeks and I've been using multiple file watchers a bunch it can freak out.

Quitting it and letting it restart itself clears things up.

-a

Guidelines for Building a Static Site Generator (2026 Edition)

Thu, 12 Mar 2026 16:49:12 -0400

The Next Generation

I've built several static site generators for personal use. Early ones were to support neopolitan. Later ones were to make it easier to build sites in general.

Now, I'm looking to move my site from alanwsmith.com to al9000.com. Part of the reason I want to make the move is to pull all my sub-domains back under the main site. It'll make things a lot easier to link back and forth and to update with global templates.

I also want to expand the site by adding in my Rust Grimoire. I've got tons of rust notes on the site already, but the grimoire isn't included. Examples in it span multiple files that my current site generator isn't set up to accommodate.

TODOish

The new generator is just for me. No need to worry about it making sense for other folks. So, I'll mostly be building things as need arises. That said, there are some basics that I want to make sure I've thought through before kicking off. Here's the list (which I'll add to whenever I think of something).

Split out the neopolitan parser so that it's its own thing that can be included in other projects.
Use MiniJinja as the template engine (it's Jinja, but in rust).
Every page on the site gets loaded as a template that can be included by any other page.
Make a two pass system so that each page can be rendered and then the rendered version be included in the next pass.
Standard tokes that are processed on the first pass are:
- [! !] functions
- [@ @] output
- [# #] comments
Tokens for the second pass are:
- [2! !2] functions
- [2@ @2] output
- [2# #2] comments
During the first pass those tokens get changed to their standard counterparts so they get used normally in the second pass.

NOTE: it may more more sense to do [1@ @1] etc to assist with caching. The idea being that you can watch files for changes and only update the ones with [1@ @1] on the first run through and everything else could be cached and ready. (Not sure if that makes sense or not. Something to look into)
Escaping tokens is done with:
- [/! !/] functions
- [/@ @/] output
- [/# #/] comments
After the second pass those tokens are converted to strings of their non-escaped versions.
Template names are the full path to the file (as opposed to one of my current site builders where the leading / isn't there in the template names)
Syntax highlighting of blocks. (Return values won't include and pre tags, just the spans to put into a pre tag).

Ideally this can be [! hlblock("html") !][! endhlblock !]

But I think i may have to be [! filter hlblock("html") !][! endfilter !]
Syntax highlighting of spans.

[! filter hlspan("html") !][! endfilter !]

As well as:

[@ hlspan("html", "the string to highlight") @]
Syntax highlighting of files [@ hlfile(PATH, "html") @].
Funciton to pull specific lines from a file with syntax highlighting applied (i.e. the syntax highlighting happens on the entire file and then the lines are pulled)
Cache syntax highlighting since it can take some time.
Use tracing library to be able to meausre performance when necessary.
Shorthand for [! filter some_filter !][! endfilter !] that is [! f some_filter !][! endf !].
[! md !][! endmd !] filter.
Actually, thinking about it, you should be able to use whatever strings you want for filters and then just find/replace them with whatever minijinjas needs (e.g. [! md !] becomes [! filter md !]).
Include a full file as markdown (e.g. [@ mdfile(PATH) @])
Good error messages for where things went wrong in template processing or neopolitan parsing.
Update the most recently changed file first and send refresh to browser when its updated.
Auto populate `/last-update/index.html` with whatever the most recent .html file to have changed is.
Any valid JSON files is available from a [@ json @] variable (e.g. /some/data.json is available at [@ json.some.data.KEYS @]
Hooks to run before the build, after the first pass, and after the second pass.
Provide JS minifier
Provide CSS minifier
Auto genreate RSS feeds. One for all posts. One each for different tags.
Auto generate pages for each tag (with pagination)
Auto generate index link pages for posts (with pagination)
Provide details on the time it takes to render each page.

Neopolitan

Need to do more thinking about how to integration Neopllitan and MiniJinja.
I think the biggest thing will be setting up the -- template in page metadata to define the minijinja template to include from.
There will have to be some things that build out a little differently. I think it's basically going to require a preprocessor that turns neopolitan files into base level HTML files that are ready to be processed by minijinja.
More thinking (and, more importantly, prototyping) to figure that out.

Images

A single image folder that can have any folder/file structure inside it.
Image calls in content are done with just the image file name without the extension. The engine finds the right file and links it up based on the name.
Auto generate responsive image sites.
Auto generate responsive image tags with the available sizes.
Output files are generated in the same places as their inputs. That is, /path/filename.html does not become /path/filename/index.html.
File extension can change (e.g. "file-name.neo" becomes "file-name.html").
Any file can have a `.off` added before its extension to opt it out of converting tag

File Metadata

During processing every file has access to a filemd variable that holds metadata including:

File name with extension.
File name without extension.
The source file extension.
The destination file extension.
The full string path to the source file.
The string path to the parent folder.
An array containing strings for the path to the parent folder split on each directory level.
A variable that points to the files directory for calling JSON in it. (e.g. /path/to/file.html and /path/to/data.json would have a variable called [@ local @] that is an alias for `[@ json.path.to @]so you can do [@ local.data.KEY @] to get whatever is in the data.json file.

Folder Metadata

Similar to file metadata
details tbd

Site Metadata and Functions

A folders() function that returns an array of all the folders on the site where each entry is itself an array of the folder path split by directories.
An exists(PATH) that returns true if a given path exists.

Miscellaneous

Build in preview server with hot realoading on file changes (with appropriate throttle/debounce).
Files and directories starting with two underscores (i.e. __) are available to be used as templates but don't get transformed/output directly.
files_in_folder(FOLDER_PATH) function
files_in_folder_ext(FOLDER_PATH, EXTENSION) function (i.e. files_in_folder_ext("/some/folder", "jpg") finds all the JPG files. EXTENSION can also be an array to find files with any number of extensions.
folders_in_folder(FOLDER_PATH) function
path(STRING, STRING...) function that assembles strings into safe paths.

Version 9000

That's everything I can think of at the moment. That thinking included taking a look at my current generators and this prior post with earlier ideas. Some of that holds up. A lot I'm thinking about differently these days.

I've got bitty in pretty good shape. Moving into this njavascript.on.jsew generator isn't too far away.

Pretty excited about the update, tbh,

-a

Get a Random Number with crypto.getRandomValues() in JavaScript

Thu, 12 Mar 2026 12:14:24 -0400

Dear RSS Reader:
The original version of this page includes JavaScript. It probably won't run in here. So, any functionality it might have had probably won't work. Check out the original page to see it in action.

The Road to Random

I'm adding some randomizing functions to bitty. I wanted to use `crypto.getRandomValues()` instead of `Math.random()`. While it's unlikely to matter, I figure using the better tool makes sense.

Here's the core functions:

JavaScript

function randomInt(min, max) {
  const seeker = new Uint32Array(1);
  crypto.getRandomValues(seeker);
  const base = seeker[0];
  const modder = Math.abs(max - min) + 1;
  let result = (base % modder) + Math.min(min, max);
  return result;
}

JavaScript

function randomFloat(min, max) {
  const seeker = new Uint32Array(1);
  crypto.getRandomValues(seeker);
  const base = seeker[0] / (0xFFFFFFFF + 1);
  const distance = Math.abs(max - min);
  let result = (base * distance) + Math.min(min, max);
  return result;
}

Snake Eyes

You pass the functions your minimum and maximum values. They spit out a random value. The numbers are inclusive. To simulate rolling a six sided die, you'd do this:

const roll = randomInt(1, 6);

Negative Space

I don't generally need random negative numbers. That's no reason to avoid them. The functions handles them just fine:

randomInt(-2, 2);

Min/Max

The Math.min(min, max) part of the `result` lines is a nice-to-have. It allows you to flip the inputs without breaking the function. I find that useful for negative numbers. Both of these operate on within the same range:

randomInt(-1, -6);
randomInt(-6, -1);

How's That Now?

The crypto.getRandomValues(seeker) function requires a different approach than Math.random(). It works by filling an array with random numbers instead of providing a single random output like the Math function.

The approach here makes an array with only one item and populates it with the random number. Then, it uses the remainder operator (%) to get a value in the min/max distance. Finally, the min value is added back in to shift it into the right place.

The float version works by using bytes. It divides the incoming number by 0xFFFFFFFF + 1. That places the result between 0 and 1. We multiply that by the distance between the min and max numbers using the same approach generally used with Math.random().

More Code is Better (in this case)

The crypto functions are notably longer than their Math.random() counterparts. Take this standard integer approach, for example:

function randomIntViaMathRandom(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

That doesn't matter. The entire point of baking things into functions is to encapsulate the complexity.

-a

Endnotes

Here's the code I used to make sure swaping the min and max worked properly:

test code

Prevent a Checkbox from Staying Checked when a Page Refreshes in Firefox

Wed, 11 Mar 2026 11:12:15 -0400

This one bit me.

In some browsers, a checkbox that's been checked will revert to unchecked by default if the pages refreshes. That's not true in the current version of Firefox. You have to add autocomplete="off" to make it consistent with the other browsers.

For example, in my Chrome browser I can check both of these and when I refresh the page both revert to being unchecked. In Firefox, the first box stays checked.

Output

Example checkbox without an autocomplete attribute

Example checkbox with autocomplete set to 'off'

HTML

<div>
  <label>
    <input type="checkbox" />
    Example checkbox without an autocomplete attribute 
  label>
div>

<div>
  <label>
    <input type="checkbox" autocomplete="off" />
    Example checkbox with autocomplete set to 'off'
  label>
div>

We have way fewer differences between browsers than in the days of The Browser Wars. They still crop up from time to time, though.

-a

Endnotes

I'm running Firefox on a mac and seeing the checkbox state persist there. YMMV on other OSes and maybe the browsers will gain consistency over time.

The input -> autocomplete docs on MDN state that:

This attribute has no effect on input types that do not return numeric or text data, being valid for all input types except checkbox, radio, file, or any of the button types

Clearly, that's not accurate. The checkbox -> checked docs have an explicit call out to Firefox maintaining the state and pointing to autocomplete for how to address it.

References

: The HTML Input element - autocomplete

- checked

HTML attribute: autocomplete

Filter the First N Number of Items from a JSON Array with jq

Wed, 11 Mar 2026 09:11:23 -0400

Use jq's [start:finish] to filter JSON to remove all but the first N number of items from a JSON array. For example:

For example:

echo '{ "items": ["a", "b", "c", "d"] }' \
| jq '.items = .items[0:2]'

Output:

{
  "items": [
    "a",
    "b"
  ]
}

More Range

The start and finish values are indexes. They can pull other ranges of the array beyond starting with the first item. For example:

echo '{ "items": ["a", "b", "c", "d"] }' \
| jq '.items = .items[1:3]'

Output:

{
  "items": [
    "b",
    "c"
  ]
}

The key being that the overall structure of the JSON remains the same.

jq continues to impress.

-a

References

the lightweight and flexible command-line JSON processor.

A `jq` Filter for Card Types from Archidekt JSON Feeds

Fri, 6 Mar 2026 09:05:06 -0500

I'm making my own Magic: The Gathering deck maker. It's based on feeds from Archidekt.

The process I'm doing is to make big collections of cards for each color/color-combination to start with. I filter those down to make actual decks.

My first step was to split things my existing decks into the colors/combos. I did that by pulling down the Archidekt JSON data from their API. Then, I used jq to filter the decks and pull out the names for each set.

Single Color Cards

For example, Green:

cat tmp.json | jq -r '.cards[] 
| select(.card.oracleCard.colors | length == 1) 
| select(.card.oracleCard.colors | any(index("Green") )) 
| .card.oracleCard.name' > green-names.txt

Multi Color

For example, Green and Black for "Golgari"

cat input.json | jq -r '.cards[]
| select(.card.oracleCard.colorIdentity | length == 2) 
| select(.card.oracleCard.colorIdentity | any(index("Black"))) 
| select(.card.oracleCard.colorIdentity | any(index("Green"))) 
| .card.oracleCard.name' > golgari-names.txt

I've used jq a few times before. This is the first time I used it to filter things based on values nested inside objects. It's super impressive.

-a

References

The Archidekt API

Archidekt doesn't mind folks poking at their API. You can use the ID of a deck in a URL like this to get the JSON for it:

https://archidekt.com/api/decks/20588790/

jq - the JSON processor

The only way to fly when you need to mess with JSON on the command line.

Default Pages for a Static Site Generator

Thu, 26 Feb 2026 10:01:37 -0500

More work on bitty's¹ documentation is under way. I'm using files and directories for all the data instead of putting it into a database. Pages are assembled by including files inside each other.

I use a directory structure like this:

data-receive
  index.html
  tests 
    basic-check
      name.html
      notes.html
      sample.js
      trigger.js
    bounce-check
      name.html
      notes.html
      sample.js
      trigger.js

The index.html file is what gets served. Its content is built by looping over the tests directory and combining the files from the directory for each test.

Each Like the Other

Every test directory has the same set of files with the following features:

The name.html and script.js are different for each test.
The trigger.js file is the same for 90% of the tests.
The notes.html file is usually empty.

Unsurprisingly, I wrote a script that watches for new test directories and stubs in an initial set of files.

The thing is, the trigger.js file has evolved over time. So, I needed a way to update it. The trick being to avoid overwriting any of the versions of the file I customized.

Scoring the Default

The solution I'm using is all about and underscore. It breaks down like this:

My script generates the default version of trigger.js with a leading underscore on the file name:
```
_trigger.js
```
I rename the file to remove the underscore if I need to customized the test.
```
trigger.js
```
I re-run my file generation script when the trigger format changes.
- If the trigger.js file exists, the script doesn't do anything for that test.
- If the trigger.js file doesn't exist, the script creates or updates the _trigger.js file.
When the site builds, the trigger.js file gets included if it exists. Otherwise, the fallback _trigger.js is used.

The Name is the Game

Removing the other files from the directory tree for a moment we get this:

data-receive
  index.html
    tests 
      basic-check
        _trigger.js
      multi-check
        trigger.js
      rebound-check
        trigger.js
      static-check
        _trigger.js

Using the name of the file as a toggle to determine what should happen in both stubbing and output is nice. Removing a single character takes care of everything for me. It's also an instance read for which files are the default and which have been customized.

I'm all about reducing the friction it takes to make thing. This is a nice one that lets me focus on content rather than on how it's stored.

-a

Endnotes

The site is built with a custom static site generator built around MiniJinja (rust's version of Jinja). It's fantastic.

This is a cut down version of the directory structure to make the example clearer. The actual one has more levels and everything starts with the _ named stub file.

Footnotes

^{1 ⤴}

bitty - the little framework that could

Version 8 is underway. I've got a good feeling about this one.

Walking a Directory with Directory Parts in Python

Wed, 25 Feb 2026 15:46:00 -0500

Working on bitty. Setting up a copy system for making tests. This is the way I'm pulling direcotires to build out a little easier.

The idea being that I need to keep the positions of the input directories relative to a template structure.

I've done this like a million times, but never put the function into the grimoire. Checking that off the list here.

-a

import os

def parse_dir(dir):
  return (dir[0].split("/"), dir[2])

def dir_list(path):
  return [parse_dir(dir) for dir in os.walk(path)]

if __name__ == "__main__":
  for dir in dir_list("dir-structure-test"):
    print(dir)

Output:

(['dir-structure-test'], ['.DS_Store'])
(['dir-structure-test', 'variance-trustee'], ['.DS_Store', 'appendix-dublin.txt', 'invited-urls.txt', 'tahoe-leone.txt', 'neck-ericsson.txt'])
(['dir-structure-test', 'variance-trustee', 'springfield-poetry'], ['elections-imaging.txt', 'standings-coding.txt', '.DS_Store', 'pasta-hotmail.txt', 'table-constraint.txt'])
(['dir-structure-test', 'variance-trustee', 'springfield-poetry', 'out-tub'], ['auditor-whom.txt', 'inside-lawyer.txt', 'life-rush.txt', 'naked-earlier.txt'])
(['dir-structure-test', 'variance-trustee', 'springfield-poetry', 'liquid-ensuring'], ['gratuit-ascii.txt', 'bikini-kits.txt', 'safer-finding.txt', 'driving-oriented.txt'])
(['dir-structure-test', 'variance-trustee', 'springfield-poetry', 'tattoo-reference'], ['airports-language.txt', 'virginia-roll.txt', 'del-embassy.txt', 'returns-lately.txt'])
(['dir-structure-test', 'variance-trustee', 'springfield-poetry', 'jewish-weak'], ['unemployment-cattle.txt', 'assigned-hu.txt', 'floors-sales.txt', 'adaptive-loud.txt'])
(['dir-structure-test', 'variance-trustee', 'motorcycle-valves'], ['.DS_Store', 'otherwise-topless.txt', 'simpson-enemy.txt', 'painted-error.txt', 'result-newer.txt'])
(['dir-structure-test', 'variance-trustee', 'motorcycle-valves', 'johnston-finland'], ['seventh-japan.txt', 'elementary-romania.txt', 'salem-enhancement.txt', 'qatar-encryption.txt'])
(['dir-structure-test', 'variance-trustee', 'motorcycle-valves', 'research-bother'], ['gen-indonesian.txt', 'downloading-processor.txt', 'informal-weak.txt', 'fruit-completely.txt'])
(['dir-structure-test', 'variance-trustee', 'motorcycle-valves', 'motor-million'], ['ny-zoom.txt', 'metro-newspapers.txt', 'modified-cables.txt', 'italic-collection.txt'])
(['dir-structure-test', 'variance-trustee', 'motorcycle-valves', 'den-lexmark'], ['acids-hydraulic.txt', 'remember-obtaining.txt', 'dishes-ref.txt', 'offers-campus.txt'])
(['dir-structure-test', 'variance-trustee', 'accurately-struct'], ['scientists-hotels.txt', '.DS_Store', 'save-bookmark.txt', 'tn-populations.txt', 'vg-griffin.txt'])
(['dir-structure-test', 'variance-trustee', 'accurately-struct', 'accidents-ads'], ['draw-mug.txt', 'writings-journalist.txt', 'gave-integrating.txt', 'only-environments.txt'])
(['dir-structure-test', 'variance-trustee', 'accurately-struct', 'interventions-src'], ['faqs-tries.txt', 'milfhunter-seen.txt', 'stanford-relationship.txt', 'trails-mouse.txt'])
(['dir-structure-test', 'variance-trustee', 'accurately-struct', 'drove-justice'], ['biography-considerations.txt', 'slovenia-digit.txt', 'jackets-be.txt', 'tubes-henry.txt'])
(['dir-structure-test', 'variance-trustee', 'accurately-struct', 'collectible-kirk'], ['admissions-wifi.txt', 'expertise-qualifying.txt', 'systematic-hebrew.txt', 'performance-ask.txt'])
(['dir-structure-test', 'variance-trustee', 'configuration-consumer'], ['riders-for.txt', '.DS_Store', 'towers-ford.txt', 'grams-shut.txt', 'acrobat-sample.txt'])
(['dir-structure-test', 'variance-trustee', 'configuration-consumer', 'assumed-dir'], ['tubes-heath.txt', 'overseas-press.txt', 'providers-helmet.txt', 'markers-asbestos.txt'])
(['dir-structure-test', 'variance-trustee', 'configuration-consumer', 'dallas-would'], ['ryan-acer.txt', 'gmbh-mas.txt', 'strip-bulletin.txt', 'steal-release.txt'])
(['dir-structure-test', 'variance-trustee', 'configuration-consumer', 'comparison-notify'], ['lincoln-scotia.txt', 'church-communication.txt', 'optional-assist.txt', 'ga-taxi.txt'])
(['dir-structure-test', 'variance-trustee', 'configuration-consumer', 'coastal-maria'], ['blast-exercises.txt', 'dynamic-pleased.txt', 'bother-language.txt', 'tiger-sewing.txt'])
(['dir-structure-test', 'defined-dice'], ['.DS_Store', 'indicator-optimize.txt', 'browsers-lift.txt', 'alternate-postings.txt', 'always-retail.txt'])
(['dir-structure-test', 'defined-dice', 'vertex-undefined'], ['japanese-vehicle.txt', '.DS_Store', 'surplus-designs.txt', 'link-educated.txt', 'labour-stretch.txt'])
(['dir-structure-test', 'defined-dice', 'vertex-undefined', 'turned-totals'], ['carry-curtis.txt', 'russian-configure.txt', 'producing-ministry.txt', 'coach-briefing.txt'])
(['dir-structure-test', 'defined-dice', 'vertex-undefined', 'cl-benefits'], ['cycling-booking.txt', 'rim-walnut.txt', 'characterization-traditional.txt', 'pools-competitions.txt'])
(['dir-structure-test', 'defined-dice', 'vertex-undefined', 'allocated-fabulous'], ['build-cute.txt', 'phd-complement.txt', 'tell-producing.txt', 'ass-filtering.txt'])
(['dir-structure-test', 'defined-dice', 'vertex-undefined', 'organised-ko'], ['then-wholesale.txt', 'occupation-disclaimers.txt', 'preferences-aircraft.txt', 'boom-clark.txt'])
(['dir-structure-test', 'defined-dice', 'reservations-cho'], ['.DS_Store', 'hats-concerned.txt', 'excel-acquisition.txt', 'ecology-safe.txt', 'wrapped-imports.txt'])
(['dir-structure-test', 'defined-dice', 'reservations-cho', 'total-smaller'], ['urge-compete.txt', 'wool-harbour.txt', 'phentermine-bookings.txt', 'breakfast-voice.txt'])
(['dir-structure-test', 'defined-dice', 'reservations-cho', 'worked-compliance'], ['wrote-catch.txt', 'hu-fujitsu.txt', 'settlement-longest.txt', 'robin-sony.txt'])
(['dir-structure-test', 'defined-dice', 'reservations-cho', 'ez-plenty'], ['chelsea-defend.txt', 'czech-butter.txt', 'starting-escorts.txt', 'sparc-september.txt'])
(['dir-structure-test', 'defined-dice', 'reservations-cho', 'open-ng'], ['casino-enormous.txt', 'aim-unlock.txt', 'adopt-carrier.txt', 'gbp-safety.txt'])
(['dir-structure-test', 'defined-dice', 'contact-nurse'], ['.DS_Store', 'button-modems.txt', 'carmen-showing.txt', 'chief-insider.txt', 'servers-declared.txt'])
(['dir-structure-test', 'defined-dice', 'contact-nurse', 'cho-gratis'], ['cotton-episodes.txt', 'customise-chemical.txt', 'tar-operators.txt', 'baseball-three.txt'])
(['dir-structure-test', 'defined-dice', 'contact-nurse', 'indirect-chicks'], ['consoles-dh.txt', 'plenty-complex.txt', 'being-silver.txt', 'wax-victim.txt'])
(['dir-structure-test', 'defined-dice', 'contact-nurse', 'jeffrey-stereo'], ['boom-mi.txt', 'noted-current.txt', 'improvements-typical.txt', 'diversity-cable.txt'])
(['dir-structure-test', 'defined-dice', 'contact-nurse', 'bmw-novel'], ['apparel-detective.txt', 'populations-spent.txt', 'hurt-puzzle.txt', 'maker-relocation.txt'])
(['dir-structure-test', 'defined-dice', 'restaurant-exchange'], ['.DS_Store', 'gold-implemented.txt', 'threads-discretion.txt', 'enquiry-minolta.txt', 'composer-afford.txt'])
(['dir-structure-test', 'defined-dice', 'restaurant-exchange', 'athletic-streets'], ['prev-keys.txt', 'recover-centered.txt', 'viral-dot.txt', 'textbooks-satisfactory.txt'])
(['dir-structure-test', 'defined-dice', 'restaurant-exchange', 'vitamin-documentary'], ['mr-chorus.txt', 'miller-characteristic.txt', 'trained-dispatched.txt', 'e-wonderful.txt'])
(['dir-structure-test', 'defined-dice', 'restaurant-exchange', 'instrument-curtis'], ['flour-describing.txt', 'antonio-dialog.txt', 'conceptual-artists.txt', 'doug-maria.txt'])
(['dir-structure-test', 'defined-dice', 'restaurant-exchange', 'consider-mileage'], ['friendly-smith.txt', 'examines-goods.txt', 'aims-forums.txt', 'citations-islam.txt'])
(['dir-structure-test', 'fare-farm'], ['.DS_Store', 'smile-tear.txt', 'handjobs-scheduled.txt', 'device-concern.txt', 'tries-validation.txt'])
(['dir-structure-test', 'fare-farm', 'greenhouse-gi'], ['.DS_Store', 'suburban-children.txt', 'bahrain-eur.txt', 'login-explained.txt', 'featuring-police.txt'])
(['dir-structure-test', 'fare-farm', 'greenhouse-gi', 'eos-knowing'], ['tells-continental.txt', 'exports-they.txt', 'plants-tight.txt', 'pos-million.txt'])
(['dir-structure-test', 'fare-farm', 'greenhouse-gi', 'flight-gnu'], ['translator-pgp.txt', 'affair-asian.txt', 'powerseller-filename.txt', 'serious-intervention.txt'])
(['dir-structure-test', 'fare-farm', 'greenhouse-gi', 'production-released'], ['respondent-much.txt', 'conclusions-avon.txt', 'exec-laboratory.txt', 'demonstration-isolation.txt'])
(['dir-structure-test', 'fare-farm', 'greenhouse-gi', 'ultimately-preferred'], ['specialized-search.txt', 'sunshine-preference.txt', 'satellite-preserve.txt', 'ongoing-tommy.txt'])
(['dir-structure-test', 'fare-farm', 'lamps-nirvana'], ['.DS_Store', 'apartments-tea.txt', 'snake-ferrari.txt', 'combat-vocals.txt', 'appliance-abraham.txt'])
(['dir-structure-test', 'fare-farm', 'lamps-nirvana', 'central-richard'], ['fragrances-thoroughly.txt', 'cheers-inspired.txt', 'cricket-bid.txt', 'reconstruction-group.txt'])
(['dir-structure-test', 'fare-farm', 'lamps-nirvana', 'consolidated-literacy'], ['mailing-pork.txt', 'believed-african.txt', 'contractor-apache.txt', 'southern-gamecube.txt'])
(['dir-structure-test', 'fare-farm', 'lamps-nirvana', 'quick-devel'], ['ir-laptops.txt', 'great-anti.txt', 'removal-cutting.txt', 'concentrations-suit.txt'])
(['dir-structure-test', 'fare-farm', 'lamps-nirvana', 'independence-statements'], ['solve-sent.txt', 'simple-lauren.txt', 'asthma-legislature.txt', 'assets-linked.txt'])
(['dir-structure-test', 'fare-farm', 'particles-supplements'], ['.DS_Store', 'outdoor-alien.txt', 'flesh-papers.txt', 'sd-melissa.txt', 'carbon-jacksonville.txt'])
(['dir-structure-test', 'fare-farm', 'particles-supplements', 'usps-jpeg'], ['points-securities.txt', 'ghost-hip.txt', 'msgid-initiative.txt', 'tourism-comfort.txt'])
(['dir-structure-test', 'fare-farm', 'particles-supplements', 'positions-impacts'], ['pump-punch.txt', 'al-charge.txt', 'nickname-income.txt', 'lamb-lights.txt'])
(['dir-structure-test', 'fare-farm', 'particles-supplements', 'laden-gzip'], ['hire-harvey.txt', 'quiz-approximate.txt', 'wifi-determine.txt', 'women-louisiana.txt'])
(['dir-structure-test', 'fare-farm', 'particles-supplements', 'bat-houses'], ['helmet-staffing.txt', 'eric-bicycle.txt', 'republic-printer.txt', 'zoo-platform.txt'])
(['dir-structure-test', 'fare-farm', 'assess-enabled'], ['mere-write.txt', '.DS_Store', 'system-wines.txt', 'opportunity-cia.txt', 'pt-cumulative.txt'])
(['dir-structure-test', 'fare-farm', 'assess-enabled', 'general-duplicate'], ['connect-counseling.txt', 'believed-maintain.txt', 'locking-surround.txt', 'centre-anchor.txt'])
(['dir-structure-test', 'fare-farm', 'assess-enabled', 'arena-also'], ['percentage-patrick.txt', 'jewelry-trinidad.txt', 'barrel-eric.txt', 'cut-dans.txt'])
(['dir-structure-test', 'fare-farm', 'assess-enabled', 'alarm-denied'], ['agree-spanish.txt', 'plasma-consideration.txt', 'sperm-socket.txt', 'reporters-theory.txt'])
(['dir-structure-test', 'fare-farm', 'assess-enabled', 'exclusive-joyce'], ['close-bag.txt', 'utilize-egyptian.txt', 'jj-customized.txt', 'mechanics-additional.txt'])
(['dir-structure-test', 'development-love'], ['.DS_Store', 'belly-blackjack.txt', 'weekly-helps.txt', 'flooring-migration.txt', 'clearing-trading.txt'])
(['dir-structure-test', 'development-love', 'relates-creator'], ['.DS_Store', 'houston-sticker.txt', 'gray-render.txt', 'expired-thunder.txt', 'thailand-doe.txt'])
(['dir-structure-test', 'development-love', 'relates-creator', 'cry-wiley'], ['pike-routers.txt', 'referenced-doors.txt', 'lf-defines.txt', 'sept-mexico.txt'])
(['dir-structure-test', 'development-love', 'relates-creator', 'collaborative-rb'], ['switched-springfield.txt', 'verified-visit.txt', 'worm-genres.txt', 'forming-anybody.txt'])
(['dir-structure-test', 'development-love', 'relates-creator', 'brisbane-tokyo'], ['movers-roger.txt', 'href-preparing.txt', 'saved-previews.txt', 'principal-soldier.txt'])
(['dir-structure-test', 'development-love', 'relates-creator', 'clouds-arnold'], ['proprietary-laboratories.txt', 'fears-visiting.txt', 'tu-donated.txt', 'situations-catalyst.txt'])
(['dir-structure-test', 'development-love', 'overview-disabled'], ['.DS_Store', 'architectural-poster.txt', 'genome-jeffrey.txt', 'cheap-contracts.txt', 'us-tit.txt'])
(['dir-structure-test', 'development-love', 'overview-disabled', 'lobby-nobody'], ['ppc-wiley.txt', 'days-sbjct.txt', 'hurt-barnes.txt', 'portions-os.txt'])
(['dir-structure-test', 'development-love', 'overview-disabled', 'ap-tanzania'], ['fog-sql.txt', 'lots-pleasure.txt', 'm-constructed.txt', 'cookies-agency.txt'])
(['dir-structure-test', 'development-love', 'overview-disabled', 'ratio-barriers'], ['actual-matches.txt', 'covered-lately.txt', 'focal-projectors.txt', 'nw-rise.txt'])
(['dir-structure-test', 'development-love', 'overview-disabled', 'unix-soa'], ['grand-recorders.txt', 'flour-downloading.txt', 'nipples-macintosh.txt', 'focus-cr.txt'])
(['dir-structure-test', 'development-love', 'hypothetical-clip'], ['.DS_Store', 'affected-doctors.txt', 'direction-ghana.txt', 'paso-theory.txt', 'cave-warcraft.txt'])
(['dir-structure-test', 'development-love', 'hypothetical-clip', 'javascript-pan'], ['ic-fan.txt', 'overhead-homeland.txt', 'drum-smallest.txt', 'sustainability-ampland.txt'])
(['dir-structure-test', 'development-love', 'hypothetical-clip', 'cellular-urge'], ['police-tiffany.txt', 'are-ministries.txt', 'mt-dynamics.txt', 'hay-advert.txt'])
(['dir-structure-test', 'development-love', 'hypothetical-clip', 'hawaii-passive'], ['subscription-television.txt', 'mustang-lost.txt', 'dollars-betting.txt', 'yet-howard.txt'])
(['dir-structure-test', 'development-love', 'hypothetical-clip', 'courtesy-len'], ['sql-cole.txt', 'metro-agent.txt', 'complex-dedicated.txt', 'grade-peterson.txt'])
(['dir-structure-test', 'development-love', 'printed-artists'], ['.DS_Store', 'frames-aaa.txt', 'cycling-belly.txt', 'seventh-guru.txt', 'ratio-partnerships.txt'])
(['dir-structure-test', 'development-love', 'printed-artists', 'codes-thing'], ['molecules-grenada.txt', 'sans-feeds.txt', 'rings-iraq.txt', 'italiano-charts.txt'])
(['dir-structure-test', 'development-love', 'printed-artists', 'headers-cherry'], ['specialty-expression.txt', 'sociology-gulf.txt', 'send-girl.txt', 'pad-girls.txt'])
(['dir-structure-test', 'development-love', 'printed-artists', 'mortgage-wagner'], ['second-younger.txt', 'versions-rebound.txt', 'fired-sitting.txt', 'moderator-adventure.txt'])
(['dir-structure-test', 'development-love', 'printed-artists', 'replies-recommend'], ['sustained-gifts.txt', 'needed-align.txt', 'establishment-horror.txt', 'toy-rates.txt'])
(['dir-structure-test', 'anymore-cart'], ['.DS_Store', 'jacksonville-uniform.txt', 'balance-portal.txt', 'accommodate-grateful.txt', 'whatever-conceptual.txt'])
(['dir-structure-test', 'anymore-cart', 'cf-incorporate'], ['gallery-radar.txt', 'usage-issn.txt', '.DS_Store', 'ring-coalition.txt', 'stomach-masturbating.txt'])
(['dir-structure-test', 'anymore-cart', 'cf-incorporate', 'paragraph-province'], ['reaches-surge.txt', 'harvey-salon.txt', 'storage-gathering.txt', 'current-allow.txt'])
(['dir-structure-test', 'anymore-cart', 'cf-incorporate', 'bali-childrens'], ['wales-ocean.txt', 'pvc-relevance.txt', 'provide-pioneer.txt', 'worcester-drunk.txt'])
(['dir-structure-test', 'anymore-cart', 'cf-incorporate', 'holdem-fingering'], ['carefully-theta.txt', 'marsh-temporarily.txt', 'filed-progress.txt', 'amsterdam-springer.txt'])
(['dir-structure-test', 'anymore-cart', 'cf-incorporate', 'artistic-discovery'], ['wayne-sin.txt', 'welsh-germany.txt', 'agreed-cruises.txt', 'checks-undertake.txt'])
(['dir-structure-test', 'anymore-cart', 'bra-fiction'], ['.DS_Store', 'consists-nyc.txt', 'pound-sq.txt', 'bookmarks-stem.txt', 'intense-graphical.txt'])
(['dir-structure-test', 'anymore-cart', 'bra-fiction', 'senators-dozen'], ['seattle-ali.txt', 'photographic-gage.txt', 'status-invalid.txt', 'tu-occupied.txt'])
(['dir-structure-test', 'anymore-cart', 'bra-fiction', 'hate-thread'], ['piece-shaved.txt', 'adams-wear.txt', 'ones-molecular.txt', 'thong-various.txt'])
(['dir-structure-test', 'anymore-cart', 'bra-fiction', 'staying-excerpt'], ['robert-prayers.txt', 'interactive-recycling.txt', 'artificial-harley.txt', 'toddler-enlargement.txt'])
(['dir-structure-test', 'anymore-cart', 'bra-fiction', 'cat-extract'], ['federation-gt.txt', 'estimate-wear.txt', 'governments-weak.txt', 'invision-rev.txt'])
(['dir-structure-test', 'anymore-cart', 'introduces-apartments'], ['.DS_Store', 'knit-payment.txt', 'vacuum-biz.txt', 'governance-hwy.txt', 'box-tiger.txt'])
(['dir-structure-test', 'anymore-cart', 'introduces-apartments', 'collections-celebrate'], ['treating-leading.txt', 'jan-pussy.txt', 'physicians-implications.txt', 'geneva-fare.txt'])
(['dir-structure-test', 'anymore-cart', 'introduces-apartments', 'collectables-proposal'], ['sam-timer.txt', 'hop-cleaners.txt', 'crap-lines.txt', 'restaurants-chemicals.txt'])
(['dir-structure-test', 'anymore-cart', 'introduces-apartments', 'ny-liberty'], ['litigation-achievements.txt', 'platinum-breeds.txt', 'iran-healing.txt', 'sam-value.txt'])
(['dir-structure-test', 'anymore-cart', 'introduces-apartments', 'fotos-performing'], ['cafe-survival.txt', 'seats-matching.txt', 'nursery-address.txt', 'lawyer-practical.txt'])
(['dir-structure-test', 'anymore-cart', 'pro-choose'], ['smart-mn.txt', '.DS_Store', 'appropriations-licence.txt', 'disagree-saves.txt', 'vc-executive.txt'])
(['dir-structure-test', 'anymore-cart', 'pro-choose', 'colleagues-raises'], ['crops-carry.txt', 'di-difference.txt', 'demands-hanging.txt', 'fingering-streams.txt'])
(['dir-structure-test', 'anymore-cart', 'pro-choose', 'networks-trust'], ['paper-worry.txt', 'motherboard-ser.txt', 'dept-attend.txt', 'board-parallel.txt'])
(['dir-structure-test', 'anymore-cart', 'pro-choose', 'invoice-blow'], ['con-campus.txt', 'atm-interact.txt', 'merchandise-lebanon.txt', 'tactics-democrat.txt'])
(['dir-structure-test', 'anymore-cart', 'pro-choose', 'aim-realize'], ['jeep-alias.txt', 'suggestion-strikes.txt', 'votes-image.txt', 'returning-accepting.txt'])

Fall Back to a Default Include File in MiniJinja

Wed, 25 Feb 2026 11:11:10 -0500

I'm working on upgrading the documentation for bitty. Everything is built with MiniJinja (rust's version of the Jinja template engine).

Very section has live test code with it. Most of the tests trigger the same way. A few don't. I wanted a way that I could use a script to generate the default approach and then override it when I need. I'm doing with in three steps:

Use a script to generate default files with names the begin with an underscore.
Manually make files with the same name minus the underscore when I need to customize something.
Have MiniJinja use the non-underscore version of the file if it exists. Otherwise, fall back to using the default one that starts with the character.

The file structure looks like this:

alfa-test/
  code_to_test.js
  _trigger.js
echo-test/
  code_to_test.js
  _trigger.js
  trigger.js

The goal is to use the trigger files:

alfa-test/_trigger.js
and
echo-test/trigger.js

I'm using this MiniJinja macro to make it happen:

[! macro get_content(folder, key) !]
    [! set default_content !]
        [! include [folder, "/_", key]|join("") !]
    [! endset !]
    [! set custom_content !]
        [! include [folder, "/", key]|join("") ignore missing !]
    [! endset !]
    [! if custom_content == "" !]
        [@ default_content @]
    [! else !]
        [@ custom_content @]
    [! endif !]
[! endmacro !]

It gets called like:

[@ get_content("alfa-test", "trigger.js") @]

[@ get_content("echo-test", "trigger.js") @]

In each case the base filename without the underscore is called. That's what gets used if it exists. Otherwise, the underscore fallback gets output.

This way I can just let the defaults do their thing then customize when necessary. Way better than having to duplicate everything myself.

-a

Endnotes

In some cases it would be possible to use a single copy of the default file stored in a central location. That won't work for what I'm doing. Each of the default trigger files has a unique ID in it that's generated outside of MiniJinja.

The default Jinja/MiniJinja tokens are hard for me to scan quickly. I switch them out for the square bracket versions you see here (e.g. {{ }} becomes [@ @].