Web excursions brought to you in partnership with Setapp. Get access to hundreds of Mac and iOS apps for one low monthly subscription fee.

julienXX/terminal-notifier

Send User Notifications on macOS from the command-line. A great shell script companion that doesn’t require making your own calls to osascript.

giladdarshan/gdialog: Display macOS dialogs from terminal and scripts

Another handy scripting tool to display macOS dialogs from terminal and scripts. There was a more involved version of this that I used to use years ago, but this fits the bill nicely for my current needs.

steveyegge/beads

Beads - A memory upgrade for your coding agent.

I haven’t quite gotten the hang of this yet, but I think it has a lot of potential. A persistent, structured memory for coding agents, replacing markdown plans with a dependency-aware graph to handle long-horizon tasks without losing context.

Get Sh*t Done

A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code and OpenCode.

I’m not a Claude Code user, but for non-masochistic developers, this looks like an excellent tool.

Check out Setapp today and get access to the best Mac and iOS apps out there.

Like or share this post Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’ve been using Sascha Ißbrücker’s extension for linkding with my own instance for a while now, and while it’s simple and works great, there’s one thing that always frustrated me: the popover window closes the moment you click outside of it, erasing what you’ve entered.

Obviously, this will only be of use to people who:

• Have a linkding server
• Use Firefox or Chrome for general browsing

If you fit the target audience, read on!

Picture: you’re adding a bookmark, you’ve filled in the title and tags, maybe added some notes, and then you realize you need to copy something from the current page. Or maybe you want to paste some text from another window. The moment you click away to grab that text, poof — the popover closes and you lose everything you’ve typed.

The persistent popup solution

So I created bt-linkding, a fork that opens the bookmark panel in a persistent popup window instead of the default toolbar popover. The window stays open until you explicitly click Save, Update, or Cancel. No more accidentally dismissing the window and losing your changes.

This means you can freely navigate away from the bookmark panel to copy text from the current page, paste from another window, or do whatever else you need to do. Your work stays put until you’re ready to save it.

The extension keeps all the features from the original like tag autocomplete, automatic page description detection, keyboard shortcuts (Alt+Shift+L to bookmark the current tab), and Omnibox search (type ld in the address bar). It just fixes that one annoying behavior.

Building and installing

Right now, the extension isn’t available in the browser stores (though I’ve submitted it to both Firefox and Chrome, but this is my first time submitting to either, so no promises about when or if it’ll be available there). For now, you’ll need to build and install it manually.

The process is pretty straightforward. First, clone the repo and install dependencies:

npm install

Then build for your target browser. Firefox and Chrome require different background script formats, so you need to use the right build command:

# For Firefox
npm run build:firefox

# For Chrome
npm run build:chrome

This updates the manifest.json file for the target browser. Once that’s done, you can load it as an unpacked extension.

Installing in Firefox

After running npm run build:firefox, open Firefox and navigate to about:debugging. Click “This Firefox” in the sidebar, then click “Load Temporary Add-on…”. Navigate to the project root directory and select any file in the extension (or just the manifest.json file). The extension will load and you’re good to go.

Installing in Chrome

After running npm run build:chrome, open Chrome and navigate to chrome://extensions/. Enable “Developer mode” (toggle in the top right), then click “Load unpacked”. Navigate to the project root directory and select it. The extension will load immediately.

What’s next

I’ve packaged the extension for both stores (npm run package:firefox and npm run package:chrome create the zip files), and I’ve submitted it to both. But since this is my first time going through the submission process for either store, I’m not making any promises about availability or timing. For now, building from source is the way to go.

If the popover closing unexpectedly is a nit for you as well, give this fork a try. The persistent window makes a world of difference when you’re trying to add bookmarks with content from multiple sources.

Full instructions and code are on GitHub.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Web excursions brought to you in partnership with Backblaze. Back up everything.

docmd — Minimalist Markdown Docs Generator

Generate beautiful, lightweight static documentation sites directly from your Markdown files with docmd. Zero clutter, just content.

I’ve written multiple versions of this concept for myself, ranging from Jekyll plugin-based sites to wholly custom solutions using Apex. This is a very nice, plugin-capable solution that I look forward to trying out for my next documentation project.

SourceDocs/SourceDocs: Generate Markdown documentation from source code

As I get more into Swift development, automatic generation of documentation from source code comments is very nice.

Kapeli/cheatset: Generate cheat sheets for Dash

I recently had a pull request merged that fixed Cheatset for versions 2.7-4.x compatibility. If you want to make cheat sheets for Dash easily, this provides a DSL for doing so. I’ve incorporated it into several workflows, including a new one that uses Apex to convert Markdown documents into Dash cheatsheets that I’ll publish soon.

Bartender 6

The latest builds of Bartender 6 bring it once again to the top of my list of menu bar managers. Super smooth on Tahoe, and beats Ice and Barbee for me now.

Backblaze securely backs up your entire computer to the cloud, affordably and reliably. I trust it with all my data. Check it out today.

Like or share this post Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’ve been using a combination of Pandoc and other tools to generate the man page for Apex from Markdown. As Apex nears a 1.0 release, I figured it should be able to generate man pages on its own.

Man pages are what gets shown when you run man COMMAND in Terminal. They use roff formatting, which is a pain to write as a human. Writing documentation in Markdown is much easier. Apex can now turn your Markdown into roff man pages or styled HTML man docs. Two output formats cover both classic terminals and the web.

-t man turns Markdown into roff (the traditional man-page source). Use it to generate apex.1, my-tool.1, and so on, then install them with make install or your package manager. No pandoc or go-md2man needed: after make build, make man runs the built apex binary with -t man to produce the man pages. Write your docs in Markdown and keep a single source for both the website and man apex.

-t man-html turns the same Markdown into HTML. Without -s you get a content-only snippet (no wrapper, no nav), handy for embedding. With -s (standalone) you get a full page: fixed left sidebar TOC (NAME, SYNOPSIS, DESCRIPTION, etc.), a large headline from the NAME section, and optional custom CSS via --css or --style. The document_title metadata (e.g. for APEX(1)) is used when present. You can also pass --code-highlight pygments or --code-highlight skylighting to highlight code blocks in either snippet or standalone output.

See it in action

The Apex man page is available as HTML and as Markdown:

• HTML (standalone): apex.1.html
• Markdown source: apex.1.md

Both are generated from the same Markdown; the HTML is what you get with apex -t man-html -s (plus any site styling).

What else is new

Highlights from the changelog:

• Man page creation: -t man and -t man-html as above; Makefile uses apex -t man for man targets.
• -t / --to output formats: html, json, json-filtered/ast-json/ast, markdown/md, mmd, commonmark/cmark, kramdown, gfm, terminal/cli, terminal256, and now man and man-html.
• Terminal and terminal256 renderers with theme support, --theme, and user theme files in ~/.config/apex/terminal/themes/. JSON and AST JSON output before and after filters for tooling.
• Terminal options: --width for column wrap; Terminal.width and Terminal.theme metadata; theme list_marker style for bullets and numbers; Span_classes mapping for inline span classes.

For the full list, see CHANGELOG.md.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Whether you’re a new user or a seasoned pro, ScreenCastsONLINE offers in-depth screencasts on a wide range of topics, from tutorials to app discovery. Check it out.

DockFlow

Boost your productivity with DockFlow. Instantly save, manage, and switch between multiple macOS Docks.

Interesting app. This is basically how Bunch started (albeit Bunch configuration is text-based). It lets you set up different Dock configurations for different contexts, which I like a lot. It is, in my opinion, overpriced for such a utility, but I also would never begrudge a developer charging what they think their work is worth. Who am I to say?

OpenClaw Mac mini M4 Enclosure: Every powerful little crustacean needs a proper shell! | Product Hunt

Just for fun.

The OpenClaw Mac mini M4 Enclosure is a fun, display-worthy 3D printed case for your OpenClaw/Clawdbot/Moltbot device. It’s a perfect blend of cute character + clean desk setup, turning your Mac mini into a chunky little desk companion.

Dockey - Make your Dock faster

A simple utility that basically offers GUI access to the animation delay and speed of the macOS Dock hide/show, avoiding the necessity of Terminal commands. Donationware.

DockFix

A reasonably-priced Dock enhancer with themes, custom icons, custom widgets, file shelf, and more.

Want more great tips and apps? Check out ScreenCastsOnline.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I love playing the New York Times game Connections. Some days it’s easy, occasionally it stumps me. I don’t cheat at it — I’ll take a loss when I have to.

What I do do, though, is check the built-in hints to find out what order the categories are in. My goal is always to get the purple (hardest) first, which often involves figuring out at least the other three categories first. Once I know all four categories, the guessing game is just which one Connections thinks is hardest.

Cheat if you want to.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Web excursions brought to you in partnership with CleanMyMac X, all the tools to speed up your Mac, in one app.

rhsev/grubber

Another cool one from Ralf Hülsmann. Turn YAML front matter and YAML code blocks in a bunch of Markdown files into structured data you can search like a database. Like data view without Obsidian.

Cursor Widget App

A cool (free) idea that lets you connect a macOS desktop widget to Cursor using an MCP. What I’ll use it for is yet to be determined, but I like the idea. Right now I’m just having it reflect its current todo list to the widget, which is kinda handy, but I think I can do cooler stuff with it.

What I learned building an opinionated and minimal coding agent

Lessons I learned while building my own coding agent from scratch.

aryankashyap0/shorlabs

Vercel for Backend. One-click deploy of Python and Node.js apps to AWS with no Docker knowledge needed. Mostly bookmarking this for my own future needs…

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Web excursions brought to you in partnership with Backblaze. Back up everything.

Devly — Developer Utilities

The fastest way to encode, decode, format, hash, and convert — 50+ developer tools, one click from your menu bar. No subscriptions, no internet required. A nice companion to TextBuddy⏎.

google webfonts helper

Found this nifty tool for downloading very streamlined, compressed versions of Google fonts for self-hosting. Get eot, ttf, svg, woff and woff2 files + CSS snippets.

giscus

A comments widget built on GitHub Discussions. If I give up on running comments from my forum Discourse server at some point, this is what I’ll switch to.

Cursor iThoughts integration

One of my own design: teach Cursor to read iThoughts X mind maps and create implementation plans for them. Just place in .cursor/commands for the project and run /ithoughts path/to/brainstorm.itmz.

Backblaze securely backs up your entire computer to the cloud, affordably and reliably. I trust it with all my data. Check it out today.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Here’s part two of my Apex posts for the day: Multiple image formats from a single image syntax.

Modern browsers support a bunch of image formats, like WebP and AVIF, that are smaller and sharper than good old PNG and JPEG. The trick is serving them without breaking older browsers. Apex makes that easy with a few attributes on your image syntax.

Apex isn’t going to generate the additional images themselves, of course, that’s up to you. But if you have a series of images in the same directory, inserting them properly is super simple now. Take a directory with:

• image.png
• image@2x.png
• image.webp
• image@2x.webp
• image.avif
• image@2x.avif

Now you can generate a <picture> (and optionally a <figure> with captions) with a single line of Markdown.

WebP and AVIF

Add webp or avif after the URL and Apex wraps the image in a <picture> element with the right <source> tags. Browsers that support the format use it; everyone else falls back to the main image.

![Hero image](img/hero.png webp)
![Hero AVIF](img/hero.png avif)

You can combine both for maximum compatibility:

![Modern formats](img/banner.jpg webp avif)

Both attributes work with @2x for retina. So ![Retina](img/hero.png webp @2x) produces a srcset with img.webp at 1x and img@2x.webp at 2x. Same deal for avif. Apex also recognizes @3x, if you need that.

Auto discovery

If you’d rather not list every format by hand, use the auto attribute:

![Profile menu](img/app-pass-1-profile-menu.jpg auto)

When base_directory is set (e.g. from the document path or --base-directory), Apex checks the filesystem for existing variants. For images it looks for 2x, 3x, webp, and avif. It only emits <source> elements for files that actually exist, so you can add formats over time without touching the Markdown.

You can also use * as the extension, which does the same thing:

![Profile menu](img/app-pass-1-profile-menu.*)

That scans for jpg, png, gif, webp, and avif (plus 2x and 3x variants) for images, and mp4, webm, ogg, mov, and m4v for videos. ![](image.*) is equivalent to ![](image.png auto).

Video: same syntax, different element

Video URLs in image syntax get special treatment. If the URL ends in mp4, mov, webm, ogg, ogv, or m4v, Apex emits a <video> tag instead of <img>:

![Demo video](media/demo.mp4)

That becomes <video><source src="https://brettterpstra.commedia/demo.mp4" type="video/mp4"></video>. No extra syntax needed.

To add alternative formats for broader browser support, tack on the format name:

![Demo with WebM](media/demo.mp4 webm)
![Demo with OGG](media/intro.mp4 ogg)

Apex adds <source> elements for each format you specify. The primary URL (e.g. demo.mp4) stays as the fallback; the attributes add webm, ogg, or whatever before it. So ![](video.mp4 ogg) gives you an ogg source plus the mp4 fallback.

Like I said, using auto or demo.* as a video URL will generate markup for all the existing formats.

What This Means

It means proper, accessible markup, and optimized web pages. It won’t mean much if your output goal is PDF or DOCX, but it’s great for web production.

The auto and `*` syntaxes mean you can write the Markdown once, and then every time you add a new format or resolution, the correct markup will be generated the next time you render, without touching the Markdown.

Quick reference

Same Markdown image syntax, better output. Check out the Apex wiki for more details.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

This is the first of two Apex posts today. In my opinion, the two things I’ve been working on deserve their own headlines. So here’s part one: terminal rendering.

If you’ve ever wanted to read Markdown in the terminal with syntax highlighting and nice formatting, you’ve probably reached for mdless or glow. They’re great tools. But what if you want all of that plus Apex’s extensions, filters, and plugins—tables with captions, footnotes, callouts, file includes, and whatever your custom filters do?

That’s where Apex’s new built-in terminal output comes in.

Triggering Terminal Output

Apex can now render Markdown directly to your terminal instead of HTML. You use --to flag with a special target:

apex README.md --to terminal

or using the short form:

apex README.md -t cli

Both produce colored, formatted output suitable for reading in an interactive terminal. No piping to mdless required—Apex handles it natively. For terminals that support 256 colors, use:

apex README.md -t terminal256

This gives you a richer color palette for headings, code blocks, links, and other elements. If your terminal supports it, the difference is noticeable.

What You Get

Because this is Apex doing the rendering, you get the full pipeline:

• Extensions: Tables, footnotes, definition lists, task lists, callouts, wiki links, and all the rest
• Filters: Any filters in your config run before render, so your title filter, delink filter, or custom Lua scripts all apply
• Plugins: Pre-parse and post-render plugins run as usual — kbd for <kbd> tags, md-fixup, or whatever you’ve installed

So when you apex doc.md -t terminal, you’re seeing the same processed document you’d get as HTML, just rendered for the terminal instead.

It’s not perfect for handling all elements yet, but the foundation is there and I’ll tweak it as needed.

Theming: mdless Compatibility

Apex’s terminal theming is compatible with mdless theme files. If you already use mdless, you can point Apex at your existing theme:

apex doc.md -t terminal256 --theme ~/.config/mdless/mdless.theme

Or set a default in your Apex config. The theme format matches mdless, so your ~/.config/mdless/mdless.theme (or any *.theme file) works out of the box.

Apex adds a few extra keys for elements mdless doesn’t have—callouts, definition lists, table captions, and the like. If you don’t define them, sensible defaults are used. You can override them in your theme file when you want finer control.

JSON Output: Build Your Own Renderer

Apex can also output a Pandoc-compatible JSON representation of the document:

apex doc.md --to json

This emits the full AST, including blocks, inlines, metadata, to stdout. From there you can pipe it into your own script to generate whatever you want: custom terminal formatting, a different HTML structure, plain text, or something else entirely.

The JSON format is the same one filters use. So if you’ve written a filter, you already know the structure. A simple Python script can read it, walk the tree, and emit your own output format. No need to re-implement the parser.

Quick Reference

So next time you’re browsing docs in the terminal, skip the Apex &rarr mdless/glow pipeline and let Apex do it all in one shot.

Like or share this post Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

NiftyMenu is the little tool I use to dump a macOS app’s menu bar into an HTML page so I can search it, click through to items, and add callouts for screencasts and product documentation. The latest round of updates brings the UI in line with macOS Tahoe and cleans up a bunch of behavior and script logic.

I wrote NiftyMenu years ago, and did a major update for Ventura. But it was way behind on Liquid Glass and basically wasn’t working anymore.

What it is

Since it’s been a while, let me explain NiftyMenu a bit. It’s a tool specifically for people documenting or blogging about apps (though anybody might get a kick out of it). When you want a screenshot of a menu item, highlighted (maybe with callouts), getting a menu to stick in place and maintain highlight state while you take a screenshot can be tricky, and doing a bunch of screenshots like this can be a pain.

NiftyMenu creates an HTML version of any app’s menu bar. You can click any item to lock it in place, navigate submenus, select items, highlight them, add callouts, and focus the shortcut key. It has dark and light modes, quick search for finding menu items with just the keyboard, customizable desktop images (including random images), and more.

I recommend viewing the pages it produces in Chrome. The styling should work well in any browser, but with Chrome you can just hit ⇧+S to save a screenshot of the currently-focused menu item. It’s super handy. Screenshotting works in Firefox, but the text gets screwy. And it doesn’t work at all in Safari. So use Chrome/Chromium.

At the bottom right of a generated menu page there’s a settings box that appears on hover, and you can change things like light/dark mode, background image, callout type, etc.

NiftyMenu is a Ruby script that generates a web app of sorts. Just one page with all the markup necessary for the menu, and some CSS and JavaScript to enable all of its functionality.

Styling to match Tahoe

The new layout and colors are tuned to feel like Tahoe’s menu bar. The font stack uses SF Pro when available (Tahoe and recent macOS), with sensible fallbacks. Top-level menu items get a soft white overlay on hover with rounded corners instead of a flat accent block; the solid accent is reserved for the selected item (.last). Submenus use the same idea: light grey overlay on hover, accent only on the selected row. Toolbar height, padding, and submenu positioning are adjusted so the overall proportions match the system menus.

Dark mode gets the same treatment: overlay-based hover states and accent only on the selected item. Submenu and divider colors use the new variables so they stay consistent with the rest of the theme.

Backgrounds and overlays

Unsplash deprecated their simpler API for image embeds, so I switched the random wallpaper generator to use Picsum.photos. You can’t do a search, but you can get a random image and apply blur and grayscale to it (NiftyMenu gives you the options when getting a random wallpaper). You can also add a “seed” word, which will stick the image so that it can be retrieved reliably. The seed you enter is stored in browser storage and will automatically be used next time the dialog is opened.

The page background (gradient or desktop image) is now fixed to the viewport, so when the menu list is taller than the window you scroll the content, not the background.

If you use a desktop image, there’s a brightening overlay: a semi-transparent layer with background-blend-mode: overlay so the image reads a bit lighter. You can tweak it (or turn it off) via $desktop-image-overlay and $dark-desktop-image-overlay in your variables. The toolbar strip at the top uses the same overlay color and blend so it sits nicely over the gradient or image.

In light mode, when submenus overlap each other or the parent, the overlap darkens instead of lightening. Submenu uls use mix-blend-mode: multiply and an opaque background so you get a clear light bluish-grey panel that darkens where it stacks.

A few fixes while I was at it

Divider rows no longer highlight on hover or accept clicks. They use pointer-events: none and the click handler bails out for divider targets and list items that only contain a divider.

The script also fixes the case where a bogus shortcut was attached to a divider line and produced blockquotes in the markdown; that combo is now normalized to a plain divider span before processing.

The globe key in shortcuts is no longer an emoji. The script outputs the entity, then swaps it for a <span class="globe-icon"> so CSS can draw the icon with a mask and currentColor, including when the shortcut is in the callout (inverted) state.

There’s a bit more progress reporting now, going to STDERR in Terminal while processing, with a simple bar and step labels: gather, process, convert, write.

What’s missing

In macOS, there are often menu items that change to an alternate option when you hold down the ⌥ key. With the way NiftyMenu gathers items, these all appear in the same menu, not hidden behind a modifier. I spent an hour this morning trying to get that to work, but it doesn’t seem feasible.

I also struggled with overlapping transparencies. In Tahoe, when a submenu’s left edge overlaps the parent menu, the edge appears opaque, or at least at uniform transparency with the submenu. Because the HTML version uses CSS colors with alpha channels, the overlap instead becomes a brighter version of the base color. I played with blend modes and other tricks but couldn’t find a way to replicate this. It’s a very small issue, but one that bugged me. If anyone has suggestions, I’d love to hear them.

There’s a JavaScript API for automating the process of selecting menu items using fuzzy search and even saving the screenshots, so you can create a workflow that generates new screenshots even as menu item names and positions change. It’s not a perfect solution — being able to do it with AppleScript would be better, but not an option here.

I also could have, but didn’t, set it up so you could choose the OS styling to use. It’s always going to use the latest macOS (that it’s been updated for) and not be backward compatible. This seems like a reasonable approach to me.

Give it a shot

If you’re writing documentation or are a blogger who often talks about apps’ menu items and shortcuts, give NiftyMenu a shot. If nothing else, it’s a pretty cool proof of concept.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

In my quest to make Apex as complete as possible before I integrate it into Marked, I’ve added Pandoc-compatible filters, which can be written in Lua for native execution, or in any language using a Pandoc JSON pipeline.

The filter system runs your code on the document after parsing and before rendering. The pipeline is: Markdown → AST → Pandoc-style JSON → your filters → JSON → HTML. That means you can transform the document in any language that speaks JSON — Ruby, Python, Lua, Node, whatever — using the same Pandoc JSON AST that Pandoc uses. If you’ve written a Pandoc filter, the proecess is the same: read one JSON document from stdin, write one JSON document to stdout.

Running filters from the CLI

Three main options:

• --filter NAME — Run a single filter. Apex looks for an executable named NAME in your user filters directory (~/.config/apex/filters or $XDG_CONFIG_HOME/apex/filters). So apex --filter title input.md runs ~/.config/apex/filters/title. These can exist inside of subdirectories.

• --filters — Run all executables in that directory, in sorted order. Handy if you keep a fixed pipeline (e.g. 01-title, 10-delink) and just want one flag.

• --lua-filter FILE — Run a Lua script as a filter. Apex calls lua FILE; the script reads Pandoc JSON from stdin and writes JSON to stdout. You need a JSON library (e.g. dkjson: luarocks install dkjson). No Pandoc Lua runtime required.

Filters run in sequence. If any filter exits non-zero or outputs invalid JSON, Apex aborts unless you pass --no-strict-filters (then it skips the bad filter and continues).

The central filter list: install and list

There’s a small index of filters at ApexMarkdown/apex-filters. It’s a single JSON file listing filter id, title, description, author, repo, etc. This will grow as I and others create new filters.

• apex --list-filters — Prints “Installed Filters” (what’s in your ~/.config/apex/filters dir) and “Available Filters” from that index, with titles and descriptions.

• apex --install-filter ID — Installs a filter by id from the index (e.g. apex --install-filter unwrap). It clones the repo into your filters directory. You can also install by Git URL or GitHub shorthand (user/repo).

• apex --uninstall-filter ID — Removes that filter (with a confirmation prompt).

To add your own filter to the list, open a pull request on github.com/ApexMarkdown/apex-filters. Once it’s merged, everyone can --list-filters and --install-filter your-id. See the docs for more info on contributing.

Example filters in the wild

Two good references:

• ApexMarkdown/apex-filter-uppercase — Lua filter that uppercases every Str inline. Shows how to walk the AST with dkjson and mutate in place.

• ApexMarkdown/apex-filter-unwrap — Lua filter that unwraps elements starting with < (e.g. custom block markers). More involved AST walking.

Install them with apex --install-filter uppercase and apex --install-filter unwrap, then use --filter uppercase or --filter unwrap in your pipeline.

Short Ruby example

A minimal filter that reads Pandoc JSON, does one thing (e.g. prepend an H1 from metadata), and writes JSON back. Ruby’s stdlib json is enough.

#!/usr/bin/env ruby
require "json"

doc = JSON.parse($stdin.read)
blocks = doc["blocks"] || []
meta   = doc["meta"] || {}

# Get title from meta if present (simplified)
title = meta.dig("title", "c") || "Untitled"
title = title.is_a?(String) ? title : title.to_s

header = {
  "t" => "Header",
  "c" => [1, ["", [], []], [{ "t" => "Str", "c" => title }]]
}
doc["blocks"] = [header] + blocks

puts JSON.dump(doc)

Save as ~/.config/apex/filters/title, chmod +x, then apex --filter title doc.md > out.html.

Short Lua example

Same idea in Lua: read JSON, tweak doc.blocks (or doc.meta), write JSON. Requires dkjson.

local json = require("dkjson")

local input = io.read("*a")
local doc = json.decode(input)
if not doc then
  io.stderr:write("Invalid JSON\n")
  os.exit(1)
end

-- Optional: transform doc.blocks or doc.meta
-- doc.blocks = ...

io.write(json.encode(doc))

Run it with apex --lua-filter myfilter.lua input.md > output.html.

Is This Feature Complete?

No, but close. I can’t get to 100% Pandoc compatibility at this point without some restructuring of the AST generated by cmark-gfm. I’m not sure 100% parity is the goal at this point. So some existing Pandoc Lua filters require some updates to work with Apex. Additionally, this feature is literally what I came up with in two days and has a lot of testing ahead. If you’re willing to help, especially if you have Pandoc filters you’d like to port, please keep me posted on GitHub.

Am I Trying to Replace Pandoc?

No, really I’m not. I’m not trying to replicate Pandoc’s amazing export abilities, or many of its extensions.

However, Pandoc’s relatively vast compatibility with various flavors of Markdown is similar to what I want to do in Apex, so supporting many of its extensions makes sense, and supporting filters means users who’ve written their own pipelines can easily switch to using Apex as a primary renderer. That’s going to be important if I want Marked to have Pandoc capabilities without using Pandoc as an external dependency.

Learn more

• Pandoc filters — The JSON AST format and filter contract Apex follows.
• Apex wiki: Filters — Full protocol, block/inline types, Lua details, and more examples.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’ve been sleeping anywhere between 4 and 6 hours a night, which isn’t great because through trial and (mostly) error, I’ve determined that at this point in my life, 8.5 hours of sleep is what I do best on. But naps help quite a bit.

By the way, if you want to follow my sleep journey as well as a couple of other neurodivergent people, along with fun pop culture and knowledge tech tidbits, you should listen to Overtired.

As I’ve mentioned before, this sleep deprivation hasn’t affected my coding productivity, but it’s been a serious detriment to my social life, and affects my dysautonomia (which I haven’t talked about for a while but is still a major issue for me) and overall pain levels pretty drastically. My only saving grace has been daily naps.

Origin of My Routine

I’ve always taken naps, even when sleeping well. I find it very rejuvenating and my afternoons are way more productive if I nap about an hour after lunch.

Once upon a time there was a startup called Napjitsu that sold a product appropriately called Nap. It was a combination of a chewable with mostly Valerian and 2 capsules containing mostly caffeine plus some other nootropics. You took them all at once. The chewable kicked in within 10 minutes, and the capsules metabolized about 30 minutes later, giving you a deep sleep for about 20 minutes and then waking up raring to go.

I loved those, but whatever else was in the capsules often made me wake up a bit “shaky.” Napjitsu shuttered a while back, but I found alternatives. This version of the routine doesn’t leave me shaky. To the contrary, I wake up feeling quite energetic without side effects.

Scheduled Wakeup Call

For the caffeine, I’m using capsules with 50mg of caffeine & 100mg of L-Theanine (these are Amazon affiliate links, which are helpful to me, but you can find these direct in other places, and I would support you not supporting Amazon). I only take one of those, as that’s enough to get me going without making me jittery or affecting my sleep later that night.

You can really just drink a cup of coffee or a shot of espresso before laying down, as caffeine in general takes 30 minutes to metabolize. But if you want the combination of caffeine and L-Theanine, that’s basically tea. Just drink a cup of tea. (White or green tea will give you approximately the right amount of caffeine, with white tea capping out at 55mg and green tea capping out at 70mg.) The capsules aren’t the key, just the caffeine.

By the way, if you ever see guaranine as an ingredient in energy drinks or supplements, it’s essentially just caffeine. Guarana is a plant, and guaranine is derived from it’s seeds. It includes some other compounds, but the only one of note is caffeine.

Sleep Phase

For the sleep phase of the nap, I tried a few things, but valerian root gives me the best results.

Valerian root is primarily indicated as a sleep aid. It’s rumored to be good for stress, PMS, and anxiety, but there’s no scientific evidence for those. It’s also commonly used as a tea, so if you really want to drink a couple of cups of tea before laying down, that’s an option, but you’ll have to pee, what with liquids and diuretics and all. A need to urinate might help you get back up, too, but I personally dislike waking up like that.

Velerian root offers me fast sedation, but easy to overcome with stimulants like caffeine, unlike supplements like melatonin. I’m using gummies with 6000mg of valerian root and chamomile. I take 2-4 of those, depending on how overtired I am. I don’t know about the safety of doubling the recommended serving size (2 gummies), but 4 does the trick on days I feel wired despite (or because of) lack of sleep.

Weirdly, napping is easiest for me on days I actually did get enough sleep, which happens every 7-10 days. But on the days I most need a nap, a little supplemental cocktail is both necessary and effective.

I don’t know if this routine is a good idea, or how well it will work for others. I can’t guarantee anything. But I can anecdotally endorse it as a decent way to “force” a restful nap that doesn’t leave me dragging for the afternoon. If you want to nap but have trouble dozing off, or have trouble waking up, or both, this might be worth a try.

How’s Your Sleep?

I hope that’s helpful to others 💤. Let me know in the forum if you have any of your own tips, I’m always looking for new ideas in this area.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’ve been hard at work on a bunch of projects at once, so this is partly just a personal check-in on how things are going. Thanks for being my therapist of sorts. So here’s what’s up with current projects, including Marked 3, Howzit, Apex, and more.

• Table of Contents

Marked 3

The Marked beta continues. It’s going really well, and I believe I’ve fixed all crashes and made a bunch of improvements. One thing the next release will feature is better large document handling. This was important for dealing with BlogBook (see below) exports, but is also a vital quality of life improvement. Now the loading doesn’t hang while reading 1MB+ files, and the rendering is faster for all processors.

I added full tab handling (finally), with the option to open new documents in tabs. Plus a Quick Open feature that lets you hit ⇧+⌘+O and quickly type or use the arrow keys to jump to a window, tab, or recent document.

I also included a CLI that makes accessing all of Marked’s URL scheme methods easy from the command line. It can’t yet automate a full export, but it’s still useful. I’ve refactored the whole export system to eventually allow full automation, but that’s going to be a 3.1 feature, not something that holds up the 3.0 release.

BlogBook

This is a new app I’m publishing as a complement to Marked 3. It generates a “Book” from WordPress, Micro.blog, or Ghost blogs. You can filter posts by author, categories, tags, date ranges, and more, then export a Markdown document (or collection of documents with an index file) which you can open in any Markdown editor. If you open it in Marked 3, special syntax like Table of Contents and page breaks will be rendered, and you can output to PDF, HTML, EPUB, and more.

This will be a great tool for people who have been blogging for a few (or a lot of) years who want a more permanent record of their work. Websites are known to disappear, but a good EPUB on your backup drive means your content will never be lost. Store your content as text, PDF, or EPUB for posterity, and/or distribute (or sell) a PDF/Ebook version of your writings. The filtering means you can easily export just a certain type of post, export only a certain date range, and you can even have the export split by year or month for making smaller books.

Check out the documentation at blogbook.my to see what it looks like. If you’re interested in helping me test, a TestFlight build will be available soon. It will be invite-only, so if you’re interested and have a WordPress, Micro.blog, or Ghost blog, contact me directly for an invite.

Apex

The last few releases of Apex have mostly addressed issues, but I added a couple new things.

First, I added support for Leanpub index syntax: {i: term}, {i: "term"}, and {i: "Main!sub"} for hierarchical entries under headings. This won’t be of use to anyone but Leanpub authors, but adding it to the existing handling of mmark and TextIndex syntax was fairly trivial.

Second, a feature I really like: if you add a @2x attribute anywhere in image attributes, e.g. ![ALT](/image.png @2x), it will generate an image with a srcset containing the original image at 1x, and then the image with @2x appended before the extension for retina displays. I also added support for @3x, which will generate srcset entries for 1x, 2x, and 3x variants of the same path.

This srcset feature is one I’ve always wanted, as I almost always provide @2x assets but Markdown never made it easy to generate the appropriate markup for these. I’m doing my best not to add arbitrary syntax to Apex that doesn’t exist anywhere else, but this one I really needed.

I also did my first real-world conversion of a build system to Apex. The Marked documentation has always used MultiMarkdown, with a build script that manually converts a bunch of Liquid-style tags (like my kbd plugin and one that generates menu item notations that open Settings panes in Marked). I converted the whole thing to use Apex, and wrote project-level plugins for all of the custom syntax I wanted to handle. It worked perfectly and required no changes to my existing documentation. So I can vouch that Apex is a great tool for this kind of thing.

I haven’t pulled the trigger on integrating Apex into Marked yet, but thanks to some reported Issues, I’ve got the Xcode integration working well. Apex is on the verge of a 1.0 release, at which point I will be converting Marked to use it. If you’re a Mac or iOS developer of a Markdown app and are willing to try it out, I’d love to help you integrate Apex and am very interested in getting some traction via inclusion in Mac/iOS apps. It’s pure C, so if you’re developing on other platforms, it will work just about anywhere, I just have the most interest in Apple platforms.

Apex Fixes

• TextIndex [term]{^} no longer includes the closing bracket in the index entry (e.g. “fresh” instead of “fresh]”).
• Reference-style image attributes (width, height, style, classes, id) are correctly applied in Unified, MultiMarkdown, and GFM modes, even when mixed with inline images and fenced div/figure blocks

Howzit

I made a simple update to Howzit to allow some interesting shell integration.

The --test-search command just returns a zero exit code if:

1. A build note file is found (build*.{md,txt})
2. The search string given matches at least one topic, based on configured search type

If either of those fails, then it returns a non-zero exit code.

This means you can have a Fish or Zsh function for handling unknown commands by testing for a matching topic and executing that if the command isn’t found and a matching build note topic exists. So if I have a “Run Tests” topic in my build notes, and I run runt on the command line, the unknown command function will execute and will run howzit -r runt, which will match the “Run Tests” topic (if fuzzy matching is enabled).

WordPress Plugins

I also added some localization to the WordPress plugins I shared the other day. No major changes to functionality, just language files for German, Spanish, French, and Italian. These were generated with AI, so I can’t vouch for their accuracy. If any speakers of these languages care to look through the various PO files for bt-downloads and bt-keyboard-shortcuts, feel free to let me know (and I’ll credit you in the documentation). Eventually when I get these published to the WordPress directory¹, this will be especially useful.

I should probably at least add Simplified Chinese, too. I’ll think about that. Any other language suggestions?

On Multitasking

That pretty well sums up what I’m working on right now. My sleep cycle is still only allowing me about 5 hours of sleep per night, and I’m usually up coding by 3:30AM. And when I’m really tired I have this weird ability to focus better while simultaneously multitasking, so most mornings I have 3 or 4 projects open at once and switch between them while one compiles or run tests or I just get bored. That part is kind of cool, though I’d rather be sleeping, were that an option.

The reason I keep adding to Howzit is because it’s how I manage to jump between projects. With identically-named topics between the projects, when switching contexts I don’t have to remember which build system I’m supposed to use, I just use Howzit to develop, run tests, build/compile, and deploy. And taking copious notes in my build notes files means I can quickly query a topic and remember what exactly I was doing.

And then there’s Doing, which I have attached to git hooks in every repo. Every time I make a commit, it adds a Doing entry for me, so if at 4am I suddenly blank on what I was doing at 3:30, I can just run doing since 3:30am to see what I’ve been working on. It’s super handy, and since I’m constantly committing to my git repos, I don’t even have to worry about making manual Doing entries.

Hopefully something in this update was of interest to you. Please keep me posted on what you’re using (join us in the forum!), what questions/issues/requests you have, and, as we we always say on Overtired, get some sleep, if you can.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Here’s a new Karabiner-Elements trick that I’ve been using to add home row app switching to my workflow. Tools like LeaderKey are great, but sometimes you just want the App Switcher, and sometimes you just want to be lazy with your fingers.

My goal was a home-row app switcher that triggered without leaving the home row, and didn’t steal keys for normal typing. The solution is a Karabiner-Elements complex modification that uses simultaneous key detection: the layer only activates when A and S are pressed together within a very short window (basically at the exact same time).

This modification is designed for the Keyboard Maestro app switcher, not the macOS default ⌘+⇥ switcher. Keyboard Maestro’s switcher uses Shift alone to move backward, whereas the system switcher expects ⇧+⌘+⇥; the key outputs below match KM’s behavior, so you’d need to adjust the modification (e.g. have D send ⇧+⇥) to use it with the built-in app switcher.

What it does

Hold A and S at the same time. While both are held, you get a temporary layer:

• D → previous app (Shift only; KM uses this for backward)
• F → next app (⌘+⇥)
• G → quit (⌘+Q)

So you chord A+S, then tap F, it loads the App Switcher, then tap D or F to move through the apps, or G to quit the highlighted app. Release A and/or S and switch to the highlighted app.

This works great with my home row arrow keys, allowing easy up/down/left/right navigation through Keyboard Maestro’s grid-based app switcher. Two-handed, but still all home row.

How it avoids hijacking A and S for regular typing

The modification never intercepts a lone A or S. It only triggers when both keys are pressed simultaneously, with a 50 ms threshold (basic.simultaneous_threshold_milliseconds). When you type normally, you press one key, release it, then press another. Your “a” and “s” key events are separated by hundreds of milliseconds, so Karabiner never sees them as a chord. Only an intentional A+S chord activates the layer. Single-key “a” and “s” pass through unchanged.

Under the hood, the rule uses Karabiner’s simultaneous from condition: an array of key codes that must all be pressed together. On that chord it sets a variable (as_layer) and injects left_command so that the following D/F/G rules (which are gated on as_layer) produce the right modifiers. When either A or S is released, to_after_key_up clears the variable and the layer drops. So you keep full use of A and S for typing; only the deliberate two-finger chord turns them into a layer key.

Import this modification

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Just for fun, I’ve been porting some of my Jekyll plugins to WordPress, and two of them have turned into what I think are really useful plugins.

I’m not switching from Jekyll to WordPress, I’ve just been enjoying the challenge of recreating these tools as WordPress extensions. It’s somewhat funny because the Jekyll plugins were originally created from WordPress plugins I’d built, and they developed over time. So this is kind of a round trip.

BT Downloads

Project page

A plugin for managing downloadables and dropping download cards into posts. You get a custom post type for each download (file URL, version, description, info link, icon, changelog), upload buttons for the file and icon right on the edit screen, and an editable HTML card template with Mustache-style conditionals ({{#description}}...{{/description}}) plus custom CSS with a live preview.

Insert them via a TinyMCE button in the classic editor or a Download block in the block editor. Pick from a dropdown and the shortcode (or block) is inserted for you. On the frontend you get a styled card: title, download link, description, dates, and optional donate/info links. There’s also a WP-CLI command to import from CSV (the way I handle downloads in Jekyll): wp btdl import_downloads --file=/path/to/downloads.csv . Full details, more screenshots, and the shortcode reference are on the BT Downloads project page.

BT Keyboard Shortcuts

Project page

This one is for writing keyboard shortcuts in posts without hand-coding symbols. I’ve created a few variations of this over time: for this blog, for Marked and Bunch documentation, and probably others. A shortcode [kbd] renders things like ⌥+⇧+⌘+A in the order Apple recommends, with options for symbol vs text (e.g. “Command-Shift-P”), a + separator, and Mac vs Windows naming.

In the block or classic editor, use the formatting menu and choose ⌘ Insert keyboard shortcut to open a dialog: check modifiers (Cmd/Opt/Shift/Ctrl/Fn), type the key, and insert the shortcode. Under Settings → Keyboard Shortcuts you can tweak display (symbols vs text, + separator, key symbols) and add custom CSS for the .btkbd keycaps, with a live preview. Examples: [kbd cmd shift p] → ⇧+⌘+P, [kbd$@P] → ⇧+⌘+P. More syntax and options are on the BT Keyboard Shortcuts project page.

Repo and requirements

Both require WordPress 5.8+ and PHP 7.4+, and are GPLv2 or later. The source for these and any future WordPress plugins from me is my wordpress-plugins repo on GitHub. Grab the code there or follow the install steps on each project page.

Like or share this post Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Whether you’re a new user or a seasoned pro, ScreenCastsONLINE offers in-depth screencasts on a wide range of topics, from tutorials to app discovery. Check it out.

I Love a Piano

I met Max Mellman at Macstock and we became fast friends. His first app is a piano synth with multiple on-screen scrollable keyboards, different piano sounds, and a built in music player with fine scrubbing for learning along with your favorite music.

The Lawyer’s Guide to Podcasting

A book from my friend Michael D.J. Eisenberg ((The Tech-Savvy Lawyer): The Lawyer’s Guide to Podcasting: Building Your Brand, Audience, Tech Stack, and Expertise!

rhsev/mi.lan:

A lightweight URL bridge for macOS automation, and a companion for dy.lan, which I wrote about last week.

‎Vimari App - App Store

A port of Vimium for Safari. Vimium is one of my favorite extensions on Chrome and Firefox, and I’d always missed it on Safari, not realizing someone had already ported it.

‎LinkThing

Not perfect, but if you need to view and search your linkding bookmarks, this runs on all Apple platforms and does the trick.

moltbot/moltbot: Your own personal AI assistant.

A personal chatbot assistant for any OS and any platform. I think this is what I’m going to do with one of the 2012 Mac minis I picked up for $25.

Gas Town - multi-agent workspace manager

We talked about this at some length on the last Overtired. Run multiple AI coding agents simultaneously with lots of useful features. Not cheap to implement fully, but powerful.

UpScrolled is live

If you’ve been waiting for a real alternative to Instagram, this is it.

From a Palestinian-Australian developer and supported by Tech for Palestine, a solid looking alternative to Instagram that allows text updates and no shadow banning/censorship. Right now it’s mostly my source for news from Gaza, but I’m curious to see how it grows. They’ve already hit limitations of scale and are updating rapidly.

Want more great tips and apps? Check out ScreenCastsOnline.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

If you use Apex for more than one project, you’ve probably hit the point where a single global setup doesn’t quite cut it. Maybe your book project wants a different plugin set than your docs site, or one repo has stricter defaults than everything else on your machine.

As a personal example, most of my app documentation has always been written in MultiMarkdown, where header ids get generated with no spaces or dashes, so all of my cross-references link to #thissection type of anchors. My blog and my Jekyll-based documentation sites have always used Kramdown, so header ids and cross references are #this-section. I needed an easy way to always have Apex use the right header format for the current project.

I also have special plugins for different destinations. For example, my Marked documentation has special Liquid-style tags like prefpane that generates nice HTML for referencing Preference panes with x-marked URLs that will open a preference pane directly in Marked. I don’t need or want a plugin to do that universally, the output it generates is very specific to Marked.

So I added project-scoped plugins and configurations to Apex. This allows me to get the settings just right for a project, then save them into a local directory and be able to just run apex without a bunch of command line flags to remember.

You also get a cleaner way to “shadow” plugins you don’t want with a local noop plugin.

I also added ++insert++ syntax for adding <ins>insert</ins> tags, but that’s just a little one-off addition.

Project-scoped plugins in .apex/plugins

Plugins used to be purely global: Apex would only look in your XDG config dir:

• $XDG_CONFIG_HOME/apex/plugins, or
• ~/.config/apex/plugins

Now there’s a proper project scope, searched in this order:

1. ./.apex/plugins (current working directory)
2. BASE/.apex/plugins when you run with --base-dir BASE
3. <git-root>/.apex/plugins when you’re inside a Git work tree
4. Global: $XDG_CONFIG_HOME/apex/plugins or ~/.config/apex/plugins

Each of those directories can hold Apex plugins in the usual format:

.apex/
  plugins/
    my-plugin/
      plugin.yml
      whatever-script-you-like

When Apex builds the plugin list, earlier locations win by id. If a plugin with id footnotes-plus exists in both .apex/plugins and your global config dir, the project version is the one that runs.

No-op shadowing: turning off plugins per project

That id-based precedence also gives you a neat trick: no-op shadowing.

If there’s a global plugin you usually like, but you don’t want it in a specific project, you can “shadow” it by dropping an empty or no-op plugin with the same id into .apex/plugins. For example:

.apex/
  plugins/
    kbd/
      plugin.yml
      noop.sh

plugin.yml might look like:

id: kbd
title: KBD Noop

Because the project copy of kbd is discovered first, it shadows the global one. You can also do the same trick with purely declarative regex plugins: define a plugin with the same id that simply doesn’t match anything meaningful, and the global behavior is effectively disabled for that project.

--list-plugins now understands projects

To make this discoverable, apex --list-plugins was updated to use the same resolution rules as the runtime plugin loader.

When you run:

apex --list-plugins

you’ll see:

• An “Installed Plugins” section that includes plugins from:
  • ./.apex/plugins
  • BASE/.apex/plugins (if --base-dir was used)
  • <git-root>/.apex/plugins
  • global config plugins
• An “Available Plugins” section from the remote directory, filtered so remote entries are hidden when you already have a plugin with the same id installed anywhere (project or global).

If a project plugin shadows a global one, you’ll only see the project entry in the installed list, and the remote listing won’t try to “helpfully” re-offer the same id.

Project-level config in .apex/config.yml

Plugins aren’t the only thing that benefit from scoping. Apex’s configuration system now has an explicit project layer, alongside the existing global and per-document metadata.

Config is now read from these places:

1. Global config
   • $XDG_CONFIG_HOME/apex/config.yml, or
   • ~/.config/apex/config.yml
2. Project config
   • ./.apex/config.yml
   • BASE/.apex/config.yml when using --base-dir BASE
   • <git-root>/.apex/config.yml when inside a Git work tree
3. Explicit metadata file
   • Any file you pass with --meta-file FILE
4. Per-document metadata
   • YAML front matter, MultiMarkdown metadata, or Pandoc title blocks
5. Command-line metadata and flags
   • --meta KEY=VALUE, --mode, --pretty, --no-tables, and so on

The merge order matters:

• Global config.yml (lowest file precedence)
• Project .apex/config.yml
• --meta-file FILE
• Document metadata
• --meta and CLI flags (highest precedence)

So if you put this in your global config:

mode: unified
pretty: true
wikilinks: false

and then in your project .apex/config.yml:

wikilinks: true
indices: true

you’ll end up with:

• mode: unified
• pretty: true
• wikilinks: true # project overrides global
• indices: true # project-only addition

Any --meta-file you pass on the command line layers on top of both, and document/CLI overrides still win last.

A quick example project layout

Here’s what a repo might look like with all of this wired up:

my-book/
  .git/
  .apex/
    config.yml
    plugins/
      figures/
        plugin.yml
        figures.py
      kbd/
        plugin.yml
  chapters/
    01-intro.md
    02-deep-dive.md

Running:

cd my-book
apex chapters/01-intro.md --plugins

will:

• Load config from:
  • global config.yml (if any),
  • then ./.apex/config.yml,
  • then any --meta-file you pass,
• Run plugins from:
  • ./.apex/plugins first,
  • then fall back to global plugins,
• Apply per-document metadata and CLI overrides on top.

You get per-repo behavior without having to constantly remember the right --meta-file or a long list of flags.

A quick note on ++insert++

While we were in here, another small but handy syntax has been added: ++insert++.

++insert++ gives you a lightweight way to add an <ins>text</ins> tag to your document. It’s just a little shorter and easier than typing out the tags manually. I try not to add too much esoteric markup to the syntax, but I’ve seen ++ a couple of places and thought it a worthwhil addition.

Wrapping up

To recap:

• Plugins can now live in .apex/plugins at the project level, and they override global plugins by id.
• --list-plugins shows the actual set of plugins Apex will run for your current project, including overrides.
• Config can now live in .apex/config.yml, layered on top of your global config.yml and below any explicit --meta-file, document metadata, and flags.
• ++insertion++ gives you <ins> tags.

If you’ve been juggling different shell aliases or wrapper scripts for each project, you can probably simplify a lot of that now by letting Apex’s own project-aware behavior do the heavy lifting.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

That’s exactly what dy.lan does. It’s a self-hosted URL router with a plugin architecture that transforms your local network into a powerful automation platform. Built by Ralf Hülsmann, a Ruby rookie from Sevelen, Germany, dy.lan (pronounced “Dylan”) is a lightweight HTTP router designed specifically for local networks.

The Basic Concept

At its core, dy.lan acts as a central entry point that translates URLs into actions. Instead of remembering 192.168.1.73:8384 for Syncthing, you can access http://sync.lan. Instead of writing complex scripts, you can use http://dy.lan/n/meeting to search your Apple Notes.

The project solves several common problems:

• Infrastructure abstraction: When a service moves to a new IP or port, you update one config line instead of hunting down bookmarks and scripts
• Workflow shortcuts: Turn URLs into actions with pattern-based routing
• Clean local services: Route HTTP traffic without the complexity of full reverse proxies like Traefik or nginx for simple use cases
• Extensibility: YAML configs for simple redirects, Ruby plugins for custom logic

Plugin Architecture and Extensibility

What makes dy.lan powerful is its plugin system. The architecture is built around numbered plugins (00-, 10-, 20-…) that follow a first-match-wins priority system. Each plugin can:

• Match URLs using regex patterns with capture groups
• Filter by domain/host
• Execute custom Ruby logic
• Handle timeouts (default 500ms, configurable per plugin)
• Auto-disable after 5 errors (circuit breaker pattern)

Plugins are hot-reloadable for YAML configs (after domain-match), and the system is resilient — syntax errors and loops won’t crash the server.

The project includes 8 example plugins covering everything from simple redirects to API integrations, monitoring dashboards, and cron jobs. You can extend it with any feature you can implement in Ruby.

Real-World Examples

Here are some practical ways dy.lan can be used:

Google Search Shortcut

# config/redirects.yaml
redirects:
  - pattern: '^/g/(.+)$'
    target: 'https://google.com/search?q=${1}'

Access http://dy.lan/g/ruby and it redirects to a Google search for “ruby”. Simple, memorable, and no coding required.

DEVONthink Search For more complex workflows, you can use a Ruby plugin:

class DevonthinkPlugin < Dylan::Plugin
  pattern %r{^/(\d{8})}

  def call(host, path, request)
    alias_id = path.match(pattern)[1]
    Dylan::Response.redirect("x-devonthink-item://#{alias_id}")
  end
end

Now http://dy.lan/12345678 opens the document with that alias in DEVONthink.

Apple Notes Search

class NotesPlugin < Dylan::Plugin
  pattern %r{^/n/(.+)}

  def call(host, path, request)
    query = path.match(pattern)[1]
    Dylan::Response.redirect("shortcuts://run-shortcut?name=search_notes&input=#{query}")
  end
end

Access http://dy.lan/n/example to search your Apple Notes for “example” via Shortcuts.

Deployment Options

One of the great things about dy.lan is its flexibility. It can run on your Mac for local development or on a Synology NAS for 24/7 operation.

On Your Mac:

git clone https://github.com/rhsev/dy.lan
cd dy.lan
docker-compose -f docker-compose.mac.yml up -d

On Synology: The project includes docker-compose.synology.yml for easy deployment on NAS devices. With macvlan networking, you can give dy.lan its own dedicated IP address, avoiding conflicts with other reverse proxies.

The performance is impressive: 6,000 requests per second on a Mac mini M4, and 2,500 requests per second on a Synology DS224+ (compared to ~200 req/s for YOURLS on similar hardware). All while using just 20-30 MB of RAM.

Technical Highlights

Built with Ruby 4.0’s async/fiber-based concurrency, dy.lan uses non-blocking I/O so slow plugins don’t block fast ones. It’s a pure Ruby implementation with no Rails, no middleware, and no database. Configuration is done through YAML files and Ruby plugins, with a browser-based dashboard for stats and container management.

The system includes modern Ruby syntax (using it parameter in core code while keeping plugins explicit), configurable timeouts, circuit breakers, and domain filtering per plugin. It’s designed to be simple, transparent, and easy to extend.

Getting Started

If you want to try dy.lan yourself, check out the GitHub repository. The project is shared as-is, built to solve specific friction in personal automation workflows. Ralf has been developing and sharing this with me for a while, and I’m glad he decided to make it public so others can benefit.

Whether you need simple URL redirects, workflow automation, or a lightweight reverse proxy for local services, dy.lan provides a clean and extensible solution.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

You can find the source code in my Fish functions repository, specifically at tween.fish.

What it does

tween displays lines between a start and end point. The start and end can be line numbers, string matches, or regex patterns. It supports multiple ranges, relative offsets, and even works with piped input.

Basic usage

The simplest form is specifying line numbers:

tween file.txt 10 20

This displays lines 10 through 20 (inclusive). You can also use a dashed range format:

tween file.txt 10-20

And here’s the nice part: arguments can be in any order. Both of these work the same way:

tween file.txt 10 20
tween 10 20 file.txt

If you only specify a single line number, tween will display from that line to the end of the file:

tween file.txt 50

This shows lines 50 through the end of the file.

Multiple ranges

Need to extract several sections? Just separate them with commas:

tween file.txt 10-20,30-40
tween file.txt 10 20, 30 40

Both formats work, so use whichever feels more natural.

Relative offsets

Sometimes you know where you want to start but need to go a certain number of lines forward. Use +N for relative offsets:

tween file.txt 10 +20

This displays lines 10 through 30 (10 plus 20 lines). You can also count from the end using -N:

tween file.txt 50 -10

This shows lines 50 to 10 lines from the end of the file. There’s a special case: -1 means the end of the file (the last line):

tween file.txt 50 -1

This displays lines 50 through the end of the file. Other negative numbers like -2, -3, etc. still mean “N lines from the end” (second-to-last, third-to-last, etc.).

String matching

Instead of line numbers, you can match on strings. This is super useful when you know the content but not the exact line:

tween file.txt 'START' +20

This finds the line containing “START” and displays it plus the next 20 lines. You can also use string matching for both start and end:

tween file.txt 50-'END'

This shows lines 50 through the line containing “END”.

Regex patterns

For more complex matching, use regex patterns wrapped in slashes:

tween file.txt /START/ +20

This matches the regex pattern “START” and displays that line plus 20 more. You can also use the -r or --regex flag to treat all string arguments as regex:

tween -r file.txt 'foo' 'bar'

Both patterns are treated as regex when using the -r flag.

Exclusive mode

Sometimes you want the lines between two markers but not the markers themselves. Use -e or --exclusive:

tween -e file.txt 'BEGIN' 'END'

This displays all lines between (but not including) the lines containing “BEGIN” and “END”.

Syntax highlighting with bat

If you have bat installed, you can use it for syntax highlighting with the -b or --bat flag:

tween -b file.txt 10-20

This displays the range with syntax highlighting, which is especially nice when viewing code.

Piped input

tween works with piped input too. Just use - as the file argument:

cat file.txt | tween 10-20,30-40 -

This is handy when you’re already working with a pipeline.

Options summary

• -e, --exclusive - Exclude the start and end lines from output
• -b, --bat - Use bat instead of sed for syntax highlighting
• -r, --regex - Treat all string arguments as regular expressions
• -h, --help - Show help message

The function is flexible enough to handle most text extraction tasks, and the ability to mix line numbers, strings, and regex makes it incredibly versatile. Give it a try and see how it fits into your workflow!

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

My two biggest projects over the last week have been Markdown Fixup and Apex. It seemed worthwhile to integrate the two in some useful way.

A quick update on Markdown Fixup: I fixed the regex replacement engine to handle multi-line replacements. This is kind of a big deal if you’re trying to convert things like BBCode to Markdown as part of the pipeline.

I’ve added a new plugin that integrates md-fixup directly into Apex’s processing pipeline. If you haven’t been tracking md-fixup, it’s an opinionated markdown linter and fixer that can normalize spacing, fix emphasis markers, and apply custom regex replacements to your markdown files. And if you haven’t been following Apex, it’s my “universal markdown processor” project that handles all kinds of Markdown extensions in one place.

Why a plugin?

You could always just pipe md-fixup into apex:

md-fixup file.md | apex --mode kramdown

That works fine for simple cases, but if you want to run md-fixup as part of a pipeline with other Apex plugins, the plugin version is the way to go. Plugins run in a deterministic order, and you can enable or disable them as needed without changing your workflow.

When it runs

The md-fixup plugin runs in the pre_parse phase, which means it processes your raw markdown text before Apex parses it. This is important for a couple of reasons:

• Compatibility: md-fixup can normalize your markdown to ensure it’s compatible with Apex’s formatting expectations
• Regex replacements: Most importantly, if you’re using custom regex replacements in your replacements.yml file, those run before Apex processes the text. This means you can transform markdown syntax itself, not just the final HTML output

Installation

The plugin is available in the Apex plugin directory. You can see it listed with:

apex --list-plugins

Install it with:

apex --install-plugin md-fixup

The plugin assumes you already have the md-fixup binary installed and available in your PATH. (And it uses the Rust version, which is what brew install md-fixup will install.)

Configuring replacements

After installation, the plugin creates a support directory at ~/.config/apex/support/md-fixup/ with a template replacements.yml file. Edit this file to add your custom regex replacements.

The file uses YAML format with a replacements: array. Each replacement has:

• name: A descriptive name for the replacement
• pattern: A regex pattern to match
• replacement: The replacement text (can use regex groups like $1, $2)
• timing: When to apply (before or after other processing)
• in_code_blocks: Whether to apply inside code blocks (true/false)
• in_frontmatter: Whether to apply in frontmatter (true/false)

Here’s an example:

replacements:
  - name: "normalize-http"
    pattern: "http://"
    replacement: "https://"
    timing: after
    in_code_blocks: false
    in_frontmatter: false

  - name: "fix-double-spaces"
    pattern: "  +"
    replacement: " "
    timing: after
    in_code_blocks: false
    in_frontmatter: false

Running with plugins

To use the plugins on a file, you can enable it globally, or run them for a specific conversion:

apex --plugins file.md

The plugin runs automatically if you’ve enabled plugins globally.

The plugin is hosted at https://github.com/ApexMarkdown/apex-plugin-md-fixup if you want to check out the code or contribute improvements.

And if you haven’t, check out Apex.

Quick side note: it’s been pointed out that md-fixup makes a great Marked preprocessor. Marked 3 adds enough search and replace capabilities that it might not be necessary, but for Marked 2, or if you prefer to edit all your replacements in a dedicated YAML file, you can just set md-fixup as your Custom Proprocessor.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’ve updated my Markdown to Sendy script with the ability to use “sliced” images with separate links, the ability to upload assets to a CDN automatically, and a “test email” mode that will actually send a test email to you without going through Sendy.

If you haven’t heard of mdtosendy before, it’s a Ruby script that converts Markdown files into email-ready HTML with automatic inline styling for maximum email client compatibility. While it can generate emails for any newsletter or email platform, it integrates best with Sendy, automatically creating and scheduling campaigns. You write your emails in Markdown, maintain your styles in CSS files, and mdtosendy handles all the messy email HTML details. And it can handle multiple templates, so you can have different styles for the same newsletter, and/or configure multiple instances with different styles/settings.

The latest version adds some powerful new features that make it even more useful for email workflows.

Test Email Sending

The HTML preview mode is useful, but nothing beats being able to actually view the email in an email app so you can see exactly how it will render. Now you can send test emails directly without going through Sendy. The new --test-send option does exactly that:

mdtosendy --test-send your-email@example.com your-email.md

This sends a test email directly via SMTP, bypassing Sendy entirely. Perfect for quick previews or testing your email design before creating a campaign. You’ll need to configure SMTP settings in your config.yml:

smtp:
  host: "smtp.gmail.com"
  port: 587
  domain: "gmail.com"
  user: "me@example.com"
  password: "your-app-password-here"
  auth: "plain"
  starttls: true

For Gmail, you’ll need to generate an App Password (not your regular password) at https://myaccount.google.com/apppasswords. Most other SMTP providers follow a similar pattern.

CDN Image Upload with Overwrite Control

The CDN image upload feature is a significant enhancement. You can add a cdn section to config (which can be inherited from the main config, or set per template), and when mdtosendy detects a local file path, it will be uploaded to the CDN and the url in the output HTML will be updated accordingly.

CDN uploads work with S3, SCP, or SFTP. See the example config in the repo for details.

You can configure how mdtosendy handles existing files on your CDN with the overwrite option:

cdn:
  url: "https://cdn.example.com"
  type: "s3"
  username: "your-access-key-id"
  password: "your-secret-access-key"
  path: "your-bucket-name"
  overwrite: ask  # Options: true, false, or ask/prompt

By default, mdtosendy uses original filenames (no timestamps) and prompts you when a file already exists. The prompt defaults to “Yes”, so you can just press Enter or type y to overwrite, or n to skip. If you choose not to overwrite, a timestamp will be added to the filename to avoid conflicts.

The overwrite setting supports three modes:

• true - Always overwrite without prompting
• false - Never overwrite, automatically add timestamps when files exist
• ask or prompt - Prompt for confirmation (default behavior)

This works with all three CDN types: S3, SCP, and SFTP. The file existence checking is smart enough to detect existing files before uploading.

Image Stack Tag

The new {% stack %} tag is perfect for creating multi-part images that need to be displayed as a seamless vertical stack. This is especially useful for sliced images or creating visual sections in your emails.

You can use it with markdown image syntax:

{% stack %}
[![](/images/image1.png)](https://example.com/link1)
[![](/images/image2.png)](https://example.com/link2)
[![](/images/image3.png)](https://example.com/link3)
{% endstack %}

Or with YAML for more structured definitions:

{% stack type="yaml" %}
images:
  - path: /images/image1.png
    url: https://example.com/link1
  - path: /images/image2.png
    url: https://example.com/link2
  - path: /images/image3.png
{% endstack %}

The stack tag creates a vertical stack of images with zero spacing between them, all full width of the content area. Each image can optionally have a link. Local images in stacks are automatically uploaded to your CDN if you have it configured, and the tag uses a table-based layout for maximum email client compatibility.

Demo Please!

Here’s an email generated from the demo.md file in the repository, using my own marked template, which uploads to my cdn.marked2app.com bucket on S3. The demo shows a single image uploaded to the CDN from a local file path, as well as 3 separate images combined into one stack, with 3 separate links.

Demo email

Getting Started

If you’re new to mdtosendy, installation is a one-liner:

curl -s https://github.com/ttscoff/mdtosendy/raw/main/bootstrap.sh | bash

For more details on all the features, configuration options, and examples, check out the mdtosendy repository on GitHub.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

When Apex reaches 1.0, I’m planning to include it in Marked 3. I realized that Marked has a lot of preprocessing features that were previously handled in Objective-C that would make sense to have in the core processor for both speed and accessibility from the command line.

So I’ve added a bunch of new flags and C API definitions to Apex that bring some of Marked’s capabilities directly into the processor. These are all available via command-line flags, configuration options, and the C API.

Hashtags

The --hashtags flag converts #tags in your Markdown into span-wrapped hashtags. By default, it uses the mkhashtag class, but you can use --style-hashtags to use mkstyledtag instead.

apex document.md --hashtags
apex document.md --hashtags --style-hashtags

This is smart enough to skip hashtags inside code blocks and HTML attributes, so you won’t get false matches in things like href="https://brettterpstra.com#anchor" or code examples.

Hashtags are disabled by default because they would conflict with headers if you’re not in the habit of putting a space after the # in an ATX header (e.g. #Header 1). This option is only for people who want to convert things like Bear notes with tag formatting. They can be enabled with --hashtags on the command line, by including hashtags: true in a config file, or by using the enable_hashtags boolean when using the C API.

Random Footnote IDs

When you’re combining multiple documents, footnote ID collisions can be a problem. The --random-footnote-ids flag generates hash-based footnote IDs using an 8-character hex prefix from the document content.

Instead of fn-1 and fnref-1, you’ll get fn-a7b3c9d2-1 and fnref-a7b3c9d2-1. Different documents get different hash prefixes, so you can safely combine them without conflicts.

Widon’t for Headings

The --widont flag prevents short widows in headings by inserting non-breaking spaces between trailing words. It works backwards from the end of the heading, combining words until the trailing portion exceeds 10 characters.

So a heading like “introduction to the topic” becomes introduction to the topic — ensuring that if the heading wraps, the trailing portion won’t be a short, lonely word on its own line.

Widon’t is disabled by default in all modes, as it might create potentially unexpected results if the user isn’t aware of it. It can be explicitly enabld with --widont, widont: true in config, or with the enable_widont boolean in the C API.

Code is Poetry

Code blocks without a programming language specified can be treated as poetry with the --code-is-poetry flag. This adds a poetry class to code blocks that don’t have a language specified, and automatically enables --highlight-language-only so only code blocks with languages get syntax highlighting.

Works for both fenced code blocks and indented code blocks.

Again, this is disabled by default as it has very specific use cases.

Proofreader Mode

The --proofreader flag converts ==highlight== and ~~delete~~ syntax into CriticMarkup highlight and deletion. It automatically enables CriticMarkup processing, so you can use this simpler syntax and still get the full CriticMarkup rendering.

Markdown in HTML Toggle

Marked has always processed markdown inside HTML blocks with markdown attributes. Now you can control this behavior with --markdown-in-html and --no-markdown-in-html. It’s enabled by default in unified mode, but you can toggle it for other modes or when you need stricter behavior.

Page Breaks

Two new flags for page break handling:

• --hr-page-break replaces <hr> elements with Marked-style page break divs

• --page-break-before-footnotes inserts a page break before the footnotes section

Both use Marked’s standard page break format with proper attributes for styling and identification.

Title from H1

When using --standalone, the --title-from-h1 flag extracts the text from the first H1 heading and uses it as the document title if no title is specified via --title or metadata. The H1 stays in the document body, but now it’s also in the <title> tag.

All Available Everywhere

All of these features are available through:

• Command-line flags (as shown above)
• Configuration files (config.yml, --meta-file)

• Document metadata (YAML front matter, MultiMarkdown metadata)

• The C API (via the apex_options struct)

This means you can set defaults in your config file, override per-document in metadata, or use command-line flags for one-off processing. The flexibility is there.

Why Build These Into Apex?

These features were originally preprocessing steps in Marked’s Objective-C code. Moving them into Apex provides:

1. Speed — C-based processing is faster than Objective-C string manipulation

2. Accessibility — Available from the command line without needing Marked

3. Consistency — Same behavior whether called from Marked or directly

4. Extensibility — Other tools can use these features via the C API

As Apex approaches 1.0, these features will make the integration with Marked a little easier while also making some of Marked’s capabilities available to anyone using Apex directly. I know none of these recent changes are killer features for most people, so this is just serving as documentation of the development process.

As always, as Apex develops, I’m very interested in what features you’d like to see. The goal is to have one universal processor that, at least for HTML output¹, can do everything that other Markdown flavors can do. If you have ideas or requests, or want to contribute to the development, please join me on GitHub!

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’ve been using my changelog script for years to generate release notes from git commit messages. It’s saved me countless hours and helped me maintain complete, informative changelogs across all my projects.

I wrote changelog in 2017 and mentioned it back in 2024. I’ve used it for every project I’ve worked on since then, and I’ve been improving it and making it work with more and more project types over the years.

Rust project support

The latest update adds support for Rust projects, which I’m just dipping my toes into. The script now automatically detects Rust projects in two ways:

1. Cargo.toml detection: If your project has a Cargo.toml file, it reads the name and version fields directly from it.

2. Rust source file scanning: For projects without a Cargo.toml (or as a fallback), it scans .rs files looking for version constants like const VERSION: &str = "1.0.0" and command names from Command::new("appname").

This means you can use the changelog script with any Rust project just by running changelog or changelog -u to update your CHANGELOG.md file, and it will automatically pull the version from your Cargo.toml or source files.

Other improvements

Along with Rust support, I’ve made a few other improvements:

• VERSION constant: The script now includes its own VERSION constant that stays in sync with the VERSION file, making it easier to track the script’s version.

• Code refactoring: I’ve extracted the version detection, git log parsing, and formatting logic into separate modules (VersionDetector, GitLogParser, and ChangelogFormatter) to make the codebase more maintainable.

• Better version detection: The script now has a more robust fallback chain for detecting versions, with Rust projects taking priority when detected, followed by Ruby gems, Xcode projects, and plain VERSION files.

• --since-version flag: You can now generate changelogs starting from a specific version tag using --since-version (or --sv for short). This is useful when you want to see changes since a particular release, and it supports partial version matching. For example, changelog --since-version 1.0 will find the most recent tag starting with “1.0” and generate a changelog from that point.

• --select flag: If you prefer an interactive approach, use --select (or -s) to pop up an fzf menu of all your git tags. This lets you visually choose which tag to use as the starting point for your changelog generation. Perfect for when you can’t remember the exact version number but know roughly when you want to start from.

• --only flag: Filter changelog output to show only specific change types. Use it like changelog --only new,fixed to see only new features and bug fixes, or changelog --only changed to see only breaking changes and modifications.

• --split flag: When used with --select or --since-version, this splits the changelog output by version tag, showing what changed in each release separately. This is great for generating comprehensive release notes that span multiple versions. You can control the order with --order asc (oldest first) or --order desc (newest first, default).

How it works

The script works exactly the same way it always has — you format your commit messages with prefixes like NEW: or FIXED:, or tags like @new, @fixed, @changed, etc., and it generates a changelog from commits since your last git tag. The only difference now is that it works seamlessly with Rust projects without any additional configuration.

The script is still designed to fit my personal workflow (including some nvUltra, Marked, and Bunch-specific formatting), but it’s open for anyone to hack on and adapt to their needs. All of my project-specific paths are gated by exact directory structures and won’t affect operation by anyone else.

If you’re working with a Rust, Xcode, Ruby, or any script project and want to automate your changelog generation, give it a try. It makes it so easy to build a changelog and release notes as you develop, and have them ready to go when you hit release time.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

BBEdit has a cool feature called Text Factories for automating repetitive text transformations. When Younghart mentioned it on the forum, it got me thinking.

While I can’t replicate the full power of Text Factories (which can chain multiple transformations, with all of BBEdit’s power), I could at least add a flexible regex search-and-replace system to md-fixup.

So that’s what I built: a YAML-driven regex replacement engine that lets you define custom patterns that run as part of an md-fixup pass. It’s not a replacement for Text Factories — it only does regex search and replace — but it offers a way to extend md-fixup with your own transformations.

How It Works

Replacements are defined in a YAML file and can be scoped to run before or after Markdown Fixup’s built-in rules. Each replacement can optionally run inside code blocks or YAML frontmatter, giving you fine-grained control over where transformations happen.

The replacement file lives in one of these locations (checked in order):

• .md-fixup-replacements in your current directory

• The path specified in your config file’s replacements_file: key

• ~/.config/md-fixup/replacements.yml (or $XDG_CONFIG_HOME/md-fixup/replacements.yml)

Setting Up Replacements

Here’s a simple example that fixes double spaces and normalizes HTTP links:

replacements:
  - name: "fix-double-spaces"
    pattern: "  +"
    replacement: " "
    timing: after
    in_code_blocks: false
    in_frontmatter: false

  - name: "normalize-http"
    pattern: "http://"
    replacement: "https://"
    timing: after

Each replacement has a few key properties:

• name: A human-readable identifier (useful for debugging)

• pattern: A Rust regex pattern (supports capture groups)

• replacement: The replacement string (use $1, $2, etc. for capture groups)

• timing: When to run—before or after the built-in rules

• in_code_blocks: If true, the pattern runs inside fenced code blocks

• in_frontmatter: If true, the pattern runs inside YAML frontmatter

A More Complex Example

Here’s one that swaps version numbers using capture groups:

replacements:
  - name: "swap-version"
    pattern: "(\\d+)\\.(\\d+)"
    replacement: "$2.$1"
    timing: before

This would turn “Version 1.2 is released” into “Version 2.1 is released”. The pattern captures two groups of digits separated by a dot, then swaps them in the replacement. Stupid example, of course (why would you ever do that?), but hopefully you get the idea.

Controlling Replacements

You can enable or disable replacements via your config file:

width: 80
replacements: true
replacements_file: ~/my-replacements.yml
rules:
  skip:
    - wrap

Or use command-line flags:

# Force enable
md-fixup --replacements file.md

# Force disable
md-fixup --no-replacements file.md

# Use a specific file
md-fixup --replacement-file ./custom.yml file.md

This regex replacement system is intentionally limited, and as mentioned, is no replacement for Text Factories. It only does regex search and replace, but it runs automatically as part of md-fixup’s fixup pass, which means you can integrate custom transformations into your existing workflow without switching tools.

If you need the full power of Text Factories, by all means use BBEdit. It’s an amazing text editor. But if you just need a few regex replacements to run alongside Markdown Fixup’s built-in rules, this might be exactly what you’re looking for.

Check out the latest version of Markdown Fixup on GitHub. Find installation and usage instructions there!

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I think a lot of people using Apex are going to want syntax highlighting of code blocks. Including a script like Highlight.js in your HTML output is fine, but I wanted Apex to be able to directly output HTML with the necessary spans and tables for highlighting. So, introducing the --code-highlight flag.

How It Works

Rather than bundling a syntax highlighting engine (which would bloat the binary and require constant updates for new languages), I decided to leverage external tools that you probably already have installed.

The new --code-highlight flag accepts either pygments or skylighting as arguments:

# Using Pygments (Python-based)
apex --code-highlight pygments input.md

# Using Skylighting (Haskell-based, used by Pandoc)
apex --code-highlight skylighting input.md

# Short forms work too
apex --code-highlight p input.md   # pygments
apex --code-highlight s input.md   # skylighting

When you specify a highlighter, Apex processes your Markdown normally, then makes a second pass over the HTML output. It finds all <pre><code> blocks, extracts the raw code content, pipes it through the external tool, and replaces the original block with the colorized HTML output.

Language Detection

Apex handles language specification in the standard way you’d expect. Just add the language identifier after the opening fence:

```python

def hello():
    print("Hello, world!")

```

The language is extracted from either the class="language-XXX" attribute on the code tag or the lang="XXX" attribute on the pre tag (depending on how cmark-gfm formatted it). This language is then passed to the external highlighter.

If you don’t specify a language, both Pygments and Skylighting will attempt auto-detection. Pygments is particularly good at this thanks to its -g (guess) flag. Skylighting will try its best but may fall back to plain text for ambiguous code.

Line Numbers

Sometimes you want line numbers in your code blocks, especially for tutorials or when referencing specific lines. The new --code-line-numbers flag has you covered:

apex --code-highlight pygments --code-line-numbers input.md

This passes the appropriate options to the highlighter (Pygments gets linenos=1, Skylighting gets the -n flag). The result is nicely numbered code that’s easy to reference.

Automatic Styling in Standalone Mode

When you use --code-highlight with --standalone and don’t specify a --css FILE option, Apex automatically embeds GitHub-style syntax highlighting CSS in the document head. This covers all the common class names used by both Pygments and Skylighting, so your highlighted code looks great out of the box.

apex --standalone --code-highlight pygments input.md > output.html

The embedded CSS uses a clean, GitHub-inspired color scheme that works well with light backgrounds. Keywords are red, strings are blue, comments are gray, and so on. If you want different colors, you can always override with your own stylesheet using the --css flag.

Multiple Stylesheets

Speaking of stylesheets, another improvement today is that --css now accepts multiple files. You can either use the flag multiple times or pass a comma-separated list:

# Multiple flags
apex --standalone --css base.css --css syntax.css input.md

# Comma-separated
apex --standalone --css base.css,syntax.css,custom.css input.md

All specified stylesheets are linked in the document head in the order provided. If you use --embed-css, all of them get embedded as inline <style> blocks.

Requirements

You’ll need one of the external tools installed and available in your PATH:

• Pygments: Install with pip install Pygments. The pygmentize binary needs to be accessible.

• Skylighting: Install with cabal install skylighting or get it with Homebrew (brew install skylighting). The skylighting binary needs to be accessible. If the specified tool isn’t found, Apex will print a warning and leave your code blocks unstyled (but otherwise functional).

Other Updates

A few other things landed alongside the syntax highlighting feature:

• ANSI art logo in --version output, because why not?

  

• Test runner badge mode (--badge) that outputs just the pass/fail count for CI badge generation

• Improved test output in errors-only mode now only shows suite titles for suites with failures

• Test infrastructure refactoring with new suite tracking helpers for cleaner, more maintainable tests

I think the syntax highlighting will be a very useful feature, at least for people publishing code. Integrating with external tools means Apex handles the Markdown parsing and document structure, while battle-tested highlighters handle the colorization. Best of both worlds.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Greetings and Salutations

The script now supports customizable greetings that can be set in your template configuration. You can define a default greeting in your config.yml:

template:
  greeting: 'Hey [Name,fallback=there],'
  # or use the alias:
  salutation: 'Hey [Name,fallback=there],'

The salutation key takes precedence if both are defined, which is useful if you want to keep things semantic. The greeting will automatically appear after the header image and before the first paragraph in your email.

You can also override it in the YAML frontmatter of individual emails:

title: My Email
greeting: 'Hello everyone,'

Or use a liquid tag to place it anywhere in your markdown:

{% greeting %}

This is the email content.

You can even provide a custom greeting directly in the tag:

{% greeting "Hi there" %}

The greeting text can contain Markdown or HTML and will be processed accordingly. The [Name,fallback=there] syntax is a Sendy merge tag that gets replaced when the email is sent.

Button Liquid Tags

One of the more tedious parts of creating email buttons has been remembering the exact syntax for applying classes. The new {% button %} liquid tag makes this much easier.

You can use it with named attributes:

{% button class="primary" text="Click Here" url="https://example.com" %}
{% button text="Click Here" url="https://example.com" %}

Or with positional arguments:

{% button "Click Here" https://example.com %}
{% button alt "Click Here" https://example.com %}

The second example uses the alt class, which maps to the secondary button style. You can also use alt2 for tertiary buttons. These classes (alt and alt2) are aliases for secondary and tertiary, making it quick to type common variants.

Reference-Style Links

Button tags also support markdown reference-style links, which is great for keeping your markdown clean:

[Forum]: https://forum.brettterpstra.com
[Markdown Web]: https://forum.brettterpstra.com/t/how-about-a-markdown-web/4412/12

{% button "Join the Conversation!" [Forum] %}
{% button alt "How about a Markdown Web?" [Markdown Web] %}

Reference matching is case-insensitive, so [Forum], [forum], and [FORUM] all work the same way.

Note that button creation and styling requires a Markdown processor that handles IALs, such as Kramdown or Apex. I recommend installing Apex for this tool.

I know this is a project with a niche audience, but I’m aware of a few people are already getting some use out of this. I know I personally love it. If you publish a newsletter or send marketing emails, let me know what you’d need to see before it was useful in your own situation.

Check the script out on GitHub.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Web excursions brought to you in partnership with Tower, the absolute best Git GUI for macOS.

moss://xmunch.com

Right in line with what I was thinking with my Markdown Web brainstorming. A protocol for content distribution that requires Markdown — portable, secure, and durable.

NSHipster/sosumi.ai: Making Apple docs AI-readable

A web app and MCP server for converting Apple API docs into AI-compatible formats. Another way to save on tokens and get better results.

karol-broda/snitch: a prettier way to inspect network connections

Great little CLI for inspecting network connections that’s friendlier than ss/netstat.

JustContent

Another (better?) take on markdownification. Very similar to Marky but I think it might get even better results. Works well as a curl command, and while it can output markdown the same way Gather or Marky does, it’s ostensibly designed as a better curl for your LLMs, reducing tokens and context.

How Markdown took over the world

Excellent article from Anil Dash documenting the rise and rapid ubiquity of Markdown.

(The banner image on this post is pretty amazing as well.)

If you’re using Git, you need Tower. Check it out today

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Tables in Markdown have always been a bit of a mess. Every processor handles them slightly differently, and when you start wanting advanced features like column spans or captions, you’re usually out of luck. I’ve been working on Apex, my unified Markdown processor, and I’m happy to say that tables are now pretty solid.

The Problem With Empty Cells

One of the trickier issues I ran into was how to handle empty cells versus colspan syntax. In many table implementations, consecutive pipes (||) create a column span. But what about cells that are just… empty? You know, with some whitespace between the pipes for alignment?

Previously, Apex was a little too eager to merge cells. If you had | | (an empty cell with spaces), it might get treated as part of a colspan. That’s not what anyone wants.

Now the rule is simple and predictable:

• || or ||| (consecutive pipes with nothing between them) = colspan
• | | (pipes with whitespace) = empty cell

This means your carefully aligned Markdown source stays readable without accidentally merging cells.

The « Marker for Explicit Colspans

Sometimes you want a colspan but you also want your source Markdown to look nice and aligned. That’s where the new << marker comes in:

| A   | B   | C   |
| --- | --- | --- |
| D   | <<  | <<  |

Each << indicates “this cell is part of a colspan from the left.” In this example, D spans all three columns. Your source stays perfectly aligned, and you get the colspan you wanted.

Row Spans with ^^

Column spans get all the attention, but row spans are just as useful. Use ^^ in a cell to merge it with the cell above:

| Department  | Employee |
| ----------- | -------- |
| Engineering | Alice    |
| ^^          | Bob      |
| ^^          | Charlie  |

Here, “Engineering” spans three rows. Stack multiple ^^ markers and the rowspan grows accordingly.

Relaxed Tables

In unified and kramdown modes, you don’t even need a separator row:

one | two | three
1 | 2 | 3
4 | 5 | 6

Apex figures out it’s a table and renders it. No |---|---|---| required.

Headerless Tables

Sometimes you just want data without a header row. Start with an alignment row:

| --- | :---: | ---: |
| left | center | right |
| a | b | c |

The alignment row sets the column alignment, and the rest is body data. No phantom header row cluttering up your HTML.

Row Header Columns

Need semantic row headers? Leave the first header cell empty:

|       | Q1  | Q2  |
| ----- | --- | --- |
| Sales | 100 | 120 |
| Costs | 80  | 90  |

Apex renders the first column of each body row as <th scope="row">, which is exactly what screen readers expect for accessible data tables.

CSV and TSV Tables

Don’t feel like typing all those pipes? Use a fenced code block with the table info string:

```table
header 1,header 2,header 3
data 1,data 2,data 3
```

Apex auto-detects whether it’s CSV or TSV and converts it to a proper table. You can even include an alignment row using keywords like left, center, right.

Multiple Caption Formats

Captions can go before or after tables, and Apex supports several syntaxes:

[My Table Caption]

| A | B |
|---|---|
| 1 | 2 |

Or Pandoc-style:

| A | B |
|---|---|
| 1 | 2 |

Table: My Table Caption

Or the Pandoc table attributes extension:

| A | B |
|---|---|
| 1 | 2 |

: My Caption {#table-id .my-class}

That last one even lets you attach IAL attributes directly to the table through the caption. Use --captions above or --captions below to control placement.

Table Footers

Need a footer section? Use a row of ===:

| Item   | Price |
| ------ | ----: |
| Widget | 10.00 |
| Gadget | 25.00 |
| ====== | ===== |
| Total  | 35.00 |

Everything after the === row goes into <tfoot>.

Per-Cell Alignment

Override column alignment on individual cells using colons:

| A      | B       | C        |
| ------ | ------- | -------- |
| :Left  | Right:  | :Center: |

The colons are stripped from the output and replaced with inline styles.

Wrapping Up

Tables were one of the areas where I really wanted Apex to shine. Between relaxed parsing, multiple colspan/rowspan syntaxes, CSV support, captions, footers, and per-cell alignment, I think it covers pretty much every table scenario I’ve ever needed.

Check out the Apex repository and the Tables documentation for more details. And if you find edge cases I haven’t covered, open an issue on GitHub. I’m always looking to make tables even better.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’ve made a couple of improvements to md-fixup, the opinionated Markdown formatting and linting tool I shared this week. The main additions are better emphasis handling and link conversion options.

Emphasis Handling

By default, md-fixup normalizes bold markers to __ (double underscore) and italic markers to * (single asterisk). So **bold** becomes __bold__ and _italic_ becomes *italic*. This keeps everything consistent in your Markdown files.

But what if you prefer the other style? You can use the --reverse-emphasis flag to swap them:

md-fixup --reverse-emphasis file.md

This will convert __bold__ to **bold** and *italic* to _italic_. Handy if you’re working with a different Markdown flavor or just have a preference.

And if you want to skip emphasis normalization entirely, just skip rule 25:

md-fixup --skip bold-italic file.md
# or
md-fixup --skip 25 file.md

Link Conversion

The new link conversion feature is one I should have had originally but kind of forgot. By default, md-fixup now converts all your links to numeric reference-style links, keeping your document body clean and all the URLs organized at the bottom.

Here’s what happens:

Before:

This is a [link](https://example.com) in the text.
Another [link](https://example.com) with the same URL.

After:

This is a [link][1] in the text.
Another [link][1] with the same URL.

[1]: https://example.com

Notice how the second link reuses the same reference number since it’s the same URL. It de-duplicates for you automatically.

Reference Links (Default)

Reference links are the default behavior (rule 28). Links get converted to [text][number] format, and all definitions are placed at the end of the document (rule 29, also default).

You can also put the link definitions at the beginning of the document instead. Just skip rule 29:

md-fixup --skip links-at-end file.md
# or
md-fixup --skip 29 file.md

This is useful if you prefer your reference definitions up top, or if you’re using a tool that reads links from the beginning.

Inline Links

If you prefer inline links instead, you can enable rule 30. This converts everything to [text](url) format and automatically disables the reference link behavior. Since inline links are disabled by default, the cleanest way to enable them is through a config file. Create ~/.config/md-fixup/config.yml:

rules:
  skip: all
  include:
    - inline-links

Or if you’re using the skip/include pattern already, just add inline-links to your include list. Inline links will override reference links when enabled.

Configuration Examples

Here are some practical configuration setups:

Default (reference links at end):

width: 60
overwrite: false
# No rules section needed - reference links are default

Reference links at beginning:

rules:
  skip:
    - links-at-end  # This puts links at the beginning

Inline links:

rules:
  skip: all
  include:
    - inline-links
    # Other rules to include

Skip emphasis conversion:

rules:
  skip:
    - bold-italic

Reverse emphasis markers:

md-fixup --reverse-emphasis file.md

This can’t be set in the config file yet—it’s command-line only for now.

What Gets Converted

The link converter handles:

• Inline links: [text](url) → [text][1]
• Reference links: [text][ref] → [text][1] (renumbered)
• Implicit reference links: [text] → [text][1] (if definition exists)
• Links with titles: [text](url "title") → [text][1] with [1]: url "title"

It also smartly ignores links inside code blocks and code spans, so your examples don’t get mangled.

I plan to continue modifying the link handling to maintain “implicit links” (links where there’s just text surrounded by square brackets and the exact text is used in a link definition); I do actually use those frequently and I think they’re great for readability. Stay tuned, I’m sure I’ll have another morning soon where I feel like hacking on that.

The emphasis normalizer handles nested cases too, like ***bold italic*** becoming __*bold italic*__ (or _**bold italic**_ in reverse mode). It’s aware of context and won’t mess with code blocks or other protected regions.

And Apex

Speaking of Markdown stuff, I also pushed v0.1.51 of Apex today. It adds support for : Caption syntax before tables (previously only after), with or without IAL attributes, and handles blank lines between captions and tables.

It fixes table and other parsing when files don’t end with a newline or use CR line endings. cmark-gfm already had great CRLF handling, but I broke some of it when building out the Apex extensions. Should be better now, and I’ve added regression tests to ensure it stays that way.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Web excursions brought to you in partnership with Backblaze. Back up everything.

A Collection of Cursor custom slash commands

A collection of custom slash commands for Cursor. All potentially useful, with some exhaustive examples.

zcaceres/markdownify-mcp: A Model Context Protocol server for converting almost anything to Markdown

A Model Context Protocol server for converting almost anything to Markdown. It can do YouTube videos to Markdown, which is worth trying out.

Atmospheric Computing

Cloud computing has been extremely successful, but it lost the values that drove personal computing. We can solve this by evolving forward.

Updatest

Trying this out and I’m really impressed. A worthy successor to MacUpdater (which ceased operations at the beginning of the month). Keeps all your Sparkle and Homebrew apps/utils up to date automatically, and can run in the background, menu bar only.

Backblaze securely backs up your entire computer to the cloud, affordably and reliably. I trust it with all my data. Check it out today.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I have some strong opinions about how Markdown should look. Liberal line breaks everywhere. ATX headers with exactly one space after the #. Consistent list indentation using tabs. Tables that are properly aligned. And on and on. So I made Markdown Fixup (md-fixup).

Building My Own Tool

I just wanted a tool to fix my own Markdown files up to match these preferences. But then I thought, maybe someone else out there has the same opinions, or at least could be swayed to think they were good ideas? So I decided to make it available to the world, just in case anyone’s tastes matched mine.

md-fixup is a comprehensive markdown linter and formatter that performs 27 different normalization and formatting rules. It solves some common issues you might run into with “it works in X.app but not in Y” by standardizing on a consistent set of rules.

I considered building this functionality directly into my Apex project, but I determined it was feature bloat and made more sense as a standalone tool. Keeping it separate means it can be used independently, works great in pipelines, and doesn’t add complexity to Apex itself. If you want to use it with Apex, you can always pipe it in (the Unix philosophy of doing one thing well).

Why Not Use Existing Tools?

There are a few good markdown linters available that can be configured to use similar rules — this one is just specific to my own preferences and easy to run. If your preferences happen to align with mine, you might find it useful.

Flexible Usage

The tool takes STDIN and can be used in a pipeline, and can output to STDOUT or overwrite files. Here’s a quick example:

# Process a file and output to stdout
md-fixup file.md

# Overwrite files in place
md-fixup --overwrite file.md

# Use in a pipeline
find . -name "*.md" | md-fixup --width 100

All linters can be enabled or disabled on the command line, via project config files, or via global config (in that order of precedence). So you can customize it to match your exact needs, even if they don’t perfectly align with my defaults.

Configuration

You can skip specific rules if you don’t want them:

# Skip wrapping and end-of-file newline rules
md-fixup --skip wrap,end-newline file.md

# Or use a config file
md-fixup --init-config

The config file lives at ~/.config/md-fixup/config.yml and lets you set defaults for width, overwrite behavior, and which rules to skip.

VS Code Extension

There’s a start of a VS Code extension in the repo, but I haven’t fully developed that yet. It’s on the roadmap, but for now the command-line tool works great.

Installation

You can install it with Homebrew:

brew tap ttscoff/thelab
brew install md-fixup

The release action is generating macOS and Linux binaries (x86, arm) so you don’t need any external tools to install via Homebrew.

You can also visit the GitHub repo for details on installing the Python version or building the Rust version from source.

All The Fixes

Here’s what md-fixup does:

• Normalizes line endings to Unix
• Trims trailing whitespace (preserves exactly 2 spaces for line breaks)
• Collapses multiple blank lines (max 1 consecutive, except in code blocks)
• Normalizes headline spacing (exactly 1 space after #)
• Ensures blank line after headline
• Ensures blank line before/after code block
• Ensures blank line before/after list
• Ensures blank line before/after horizontal rule
• Converts list indentation spaces to tabs consistently
• Normalizes list marker spacing
• Wraps text at specified width (preserving links, code spans, fenced blocks)
• Ensures exactly one blank line at end of file
• Normalizes IAL (Inline Attribute List) spacing for both Kramdown and Pandoc styles
• Normalizes fenced code block language identifier spacing
• Normalizes reference-style link definition spacing
• Normalizes task list checkbox (lowercase x)
• Normalizes blockquote spacing
• Normalizes $$ display and $ inline math block spacing (handles multi-line, preserves currency)
• Normalizes table formatting (aligns columns, handles relaxed and headerless tables)
• Normalizes emoji names (spellcheck and correct typos using fuzzy matching)
• Normalizes typography (curly quotes to straight, en/em dashes, ellipses, guillemets)
• Normalizes bold/italic markers (bold: always __, italic: always *)
• Normalizes list markers (renumber ordered lists, standardize bullet markers by level)
• Resets ordered lists to start at 1 (if disabled, preserves starting number)

Feedback Welcome

Feedback and code contributions are welcome! If you have opinions about Markdown formatting that differ from mine, I’d love to hear about them. And if you want to help build out the VS Code extension or add new features, pull requests are always appreciated.

See details on GitHub and take it for a spin!

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

One of the things I love about Howzit is how it bridges the gap between simple task lists and full automation. You can write quick (or complex) scripts right in your build notes and, with the latest updates, they can communicate back to Howzit in useful ways. The latest updates make this even easier with automatically-injected helper scripts and some powerful new directives.

The first thing I did was a major overhaul of the way Topics are processed. It now “streams” the topics in a sequential order, reevaluating conditions and variable substitutions after each executable directive or block is run. That means that the variables you pass from inside of run blocks can be used to control if/else logic in the rest of the topic being run, and it makes variables immediately available in the next task in the topic. Previously you would have had to incorporate multiple topics to use the variables effectively. Now they work the way you would expect in any scripting environment. (Yes, I’ll apply this idea to Bunch soon, too).

Here are couple of features made possible by this change:

Automatic Helper Script Injection

When you write a run block (those fenced code blocks with run as the language), Howzit automatically detects your script’s interpreter from the hashbang and injects helper functions. No setup required — just start using them.

Here’s what happens behind the scenes: Howzit sees your hashbang, figures out you’re using bash (or Ruby, Python, Fish, etc.), and automatically loads the appropriate helper script. The helpers are installed in ~/.config/howzit/support/ and made available via the HOWZIT_SUPPORT_DIR environment variable.

By the way, Howzit now runs out of ~/.config instead of ~/.local/share. It will automatically migrate files as necessary, with confirmation. You can force a migration with howzit --migrate.

For bash scripts, you get functions like log and set_var:

```run Build and Test
#!/bin/bash
log info "Starting build process..."
set_var BUILD_STATUS "in_progress"

# Do your build stuff
make build

if [ $? -eq 0 ]; then
  set_var BUILD_STATUS "success"
  log info "Build completed successfully"
else
  set_var BUILD_STATUS "failed"
  log error "Build failed"
fi
```

The same helpers work in Ruby, Python, Fish, and other languages—just with syntax that matches each language. In Ruby, it’s Howzit.logger.info() and Howzit.set_var(). In Python, it’s howzit.Howzit.logger.info() and howzit.Howzit.set_var(). You get the idea.

Controlling Log Output with @log_level

Sometimes you want verbose output during development, but quieter logs in production. The @log_level directive lets you control which messages from your scripts actually get displayed.

Log levels work like you’d expect: debug shows everything, info shows informational messages and above, warn shows warnings and errors, and error only shows errors. You can change the log level multiple times throughout a topic:

@log_level(debug)
@run(./verbose-script.sh) Development build with all messages

@log_level(warn)
@run(./production-script.sh) Production build, warnings only

This is especially useful when you have scripts that output a lot of debug information. Set the log level to warn or error and you’ll only see what matters.

Setting Variables with @set_var

Variables are super useful for making your build notes dynamic. You can set them in scripts using set_var, but now you can also set them directly in your build notes with the @set_var directive.

The basic syntax is straightforward:

@set_var(VERSION, "1.2.3")
@set_var(STATUS, "success")

Variables set this way work exactly like variables set in scripts — they’re available as ${VAR} in subsequent tasks and can be used in conditional blocks.

Command Substitution

Here’s where it gets interesting: @set_var supports command substitution. You can execute a command and use its output as the variable value:

@set_var(VERSION, `rake vver`)
@set_var(BUILD_DATE, $(date +%Y-%m-%d))

Both backticks and $() syntax work. The command output (with whitespace stripped) becomes your variable value.

Even better, you can reference other variables in your commands:

@set_var(PREV_VERSION, "1.2.2")
@set_var(NEXT_VERSION, `echo ${PREV_VERSION} | awk -F. '{print $1"."$2"."$3+1}'`)

The ${PREV_VERSION} gets substituted before the command runs, so you can build up complex values from simpler ones.

Putting It All Together

Here’s a practical example that combines everything:

## Deploy

@set_var(VERSION, `git describe --tags`)
@set_var(BRANCH, `git rev-parse --abbrev-ref HEAD`)

@log_level(info)
@if ${BRANCH} == "main"
  @run(./deploy-prod.sh ${VERSION}) Deploy to production
@else
  @run(./deploy-staging.sh ${VERSION}) Deploy to staging
@end

@log_level(debug)
```run Verify Deployment
#!/bin/bash
log debug "Checking deployment status..."
# More verbose logging here
```

The @set_var directives set up your variables from git commands, @log_level controls verbosity, and the conditional uses those variables to decide what to deploy. The run block at the end uses the helper functions to send messages back to Howzit.

Why This Matters

These features make Howzit build notes feel more like a real scripting environment while keeping the simplicity of markdown, and now scripts within a topic can communicate with each other, and topics can cascade variables between them. You can write complex automation without leaving your build notes file, and the helper scripts mean you don’t have to remember communication file formats or write boilerplate code.

The automatic injection means less friction — just write your script and use the helpers. The @log_level directive gives you control over noise. And @set_var with command substitution lets you build dynamic workflows that adapt to your project’s current state.

This latest release, along with the recent conditional blocks features, makes Howzit even more useful for me. Hopefully you’ll find it useful, too. See the project page for an overview, and check out the wiki for full documentation.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’ve been working on making Apex (my ultimate Markdown processor) easier to integrate into Xcode projects, and I’m excited to share what’s new. The biggest change is full Swift Package Manager (SPM) support, which makes adding Apex to your project as simple as clicking a button in Xcode.

While Apex is still in a 0.x state, I don’t suggest it be used in production, but if developers want to start testing it out in an application scenario, it should be easy to load in a Mac or iOS app. Once it gets to 1.0, it will be a lot less likely to have breaking changes, and the API won’t change in the 1.x series. I don’t foresee many, if any, changes to the API moving forward, but we’ll see how reception goes and what feedback arises.

Swift Package Manager Support

The easiest way to add Apex to your Xcode project now is through Swift Package Manager. Just open your project, go to the Package Dependencies tab, and add the Apex repository. Xcode handles the rest.

import Apex

let markdown = "# Hello World"
let html = markdown.apexHTML()

That’s it. No framework dragging, no manual linking, no build configuration tweaks. SPM takes care of everything.

The package supports both macOS 10.13+ and iOS 11+, so you can use Apex in your iOS apps too. I’ve bundled libyaml as part of the package to make iOS support work seamlessly, with worrying about system library dependencies.

Framework Build Options

If you prefer the traditional framework approach, that still works too. The CMake build now includes a module map in the framework, which means Swift can import the C API directly if you need it. The framework build is still the way to go if you’re integrating with existing CMake projects or need more control over the build process.

cmake -DBUILD_FRAMEWORK=ON ..
make

The framework gets installed to /Library/Frameworks by default, or you can customize the install location.

Better Swift Integration

I’ve improved the Swift API wrapper to make it more idiomatic. The ApexOptions struct now has a public initializer, so you can create options instances directly:

var options = ApexOptions()
options.pretty = true
options.generateHeaderIDs = true
let html = markdown.apexHTML(mode: .gfm, options: options)

The bridging between Swift and Objective-C has been cleaned up too. All the category methods on NSString are now properly accessible from Swift, so you get the full API surface without any awkward workarounds.

Module Map for Direct C Access

If you need to use the C API directly from Swift, there’s now a module map that makes it straightforward:

import Apex

let opts = apex_options_default()
opts.pretty = true
// ... configure options ...
let html = apex_markdown_to_html(markdown, markdown.count, &opts)

This is useful if you need fine-grained control or want to use features that aren’t exposed through the higher-level Swift API yet.

Testing It Out

I’ve included a test script (test_spm.sh) that creates a temporary test project and verifies everything works. It does a clean build each time, so you can be confident the package builds correctly from scratch.

./test_spm.sh

The script tests all the main integration points—basic conversion, different modes, options, and standalone document generation.

One More Thing

While I was working on this, I also enabled emoji autocorrect by default in unified mode. So if you type :rocket: and it doesn’t quite match, Apex will try to find the closest match. It’s a small quality-of-life improvement that makes the emoji syntax a bit more forgiving.

The SPM package is ready to use in the latest release, and I’d love to hear how it works for you. If you run into any issues or have suggestions for improvements, let me know!

Learn more about Apex on the project page and in the Apex wiki. If you’re interested in Xcode integration, there’s a whole page for that.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I often come up with ideas in the hazy half-dream state before I wake up. Recently I was thinking about exactly how shitty the web has become. And also about how much I love plain text formats like Markdown. So what about a Markdown Web?

The idea is harkening back to the dawn of the web, but instead of basic HTML, everything is Markdown. The rendering is client side (with some plugins for extensibility) and the user gets to decide how the whole web looks simply by choosing a theme for their browser. All script and style tags are stripped, no hosted ads, no tracking. Sites can still run sponsors and use affiliate links, but banner ads are gone.

I know that a lot of the web depends on ads to survive. There have been a lot of micropayment options, and I think something like that could work, replacing the ad-based model entirely. Everything is paywalled, but at very affordable rates. That would require a lot more central processing than I’ve brainstormed thus far, so I’m leaving it as an open question.

I’m envisioning this as running on the same servers the web currently exists on, not building some independent blockchain web or anything. Although I’m open to brainstorming on that.

I’m posting this mind map in the hopes that it will start a conversation. Let me know what projects you know already exist around this, what you think it would require, and what your own imagination for a better web looks like. Add a comment to this post to start a conversation on the forum.

Mind map courtesy of MindNode Next and my Jekyll SVG Viewer.

Just thinking out loud here. Let me know what you think.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Apex has always supported Kramdown-style IAL (Inline Attribute Lists), but I’ve been steadily adding more Pandoc compatibility. The latest release brings several new features that make Apex work better with Pandoc-style markdown while maintaining backward compatibility.

Thanks to somelinguist for the suggestions!

Table Captions Get More Flexible

Table captions now support three different formats. You can use the existing [Caption] and Table: Caption syntax, plus the new Pandoc-style : Caption format:

| Col1 | Col2 |
|------|------|
| A    | B    |

: This is a Pandoc-style caption

Even better, IAL attributes in table captions are now extracted and applied to the table element itself. So you can do things like:

| Col1 | Col2 |
|------|------|
| A    | B    |

: My Table {#table-id .highlight}

This applies both the id="table-id" and class="highlight" attributes directly to the <table> element, not just the caption.

Pandoc-Style IAL Everywhere

One of the biggest changes is full support for Pandoc-style IAL syntax without the colon prefix. Where you used to need {: #id .class}, you can now use {#id .class} in all contexts:

• Block-level IALs after headings, paragraphs, and other blocks
• Inline IALs on links, images, emphasis, and other inline elements
• Pure IAL paragraphs
• Table captions

Both formats work, so your existing Kramdown documents continue to work while new Pandoc-style documents are fully supported.

Fenced Divs

Pandoc’s fenced divs are now supported in unified mode (enabled by default). You can create custom block containers with attributes:

::::: {#warning .alert}
This is a warning box with custom styling.
:::::

Fenced divs support nesting, attributes, and all the usual IAL features. You can control them with the --divs and --no-divs command-line flags.

Bracketed Spans

Bracketed spans let you create inline HTML spans with attributes using a simple syntax:

This is [some text]{.highlight} with a span.

The [text]{IAL} syntax converts to <span class="highlight">some text</span>. It supports all IAL attribute types—IDs, classes, and key-value pairs—and processes markdown inside the spans.

Reference links take precedence, so if [text] matches a reference link definition, it stays a link. Otherwise, it becomes a span. Bracketed spans are enabled by default in unified mode, and you can control them with --spans and --no-spans flags.

Image Attributes Get Smarter

Image support has been significantly enhanced. You can now use IAL syntax on both inline and reference-style images:

![alt text](image.jpg){#my-image .photo width=50%}

[ref]: image.jpg "Title" {#ref-image .thumbnail width=300px}
![alt][ref]

The width and height conversion follows Pandoc’s rules:

• Percentages like width=50% convert to style="width: 50%"
• Pixel values like width=300px convert to width="300" (the px suffix is stripped)
• Bare integers like width=300 stay as width="300"
• Other units like 5em or 10rem convert to style attributes
• Decimal pixel values like 100.5px also go to style attributes

This means you get clean, semantic HTML output that works well across different contexts. Reference image definitions also now preserve title attributes, so [ref]: url "title" {#id} includes the title in the final output.

Better IAL Detection

I’ve improved IAL detection throughout the codebase. IAL syntax with spaces (like { width=50% }) now works correctly, and IALs are properly stripped from output even when parsing fails, preventing raw IAL syntax from appearing in your HTML.

All of these features work together seamlessly. You can mix Kramdown and Pandoc syntax in the same document, use IALs everywhere, and get clean, semantic HTML output. The test suite has been expanded to cover all these new features, so everything should work reliably.

Check out the latest release for full release notes. And if you haven’t tried Apex yet, check out the Apex project and help me build the ultimate Markdown processor!

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

Happy New Year! I spent some time this morning developing some features for Howzit that I think will be really useful (at least for me).

Howzit is my tool for documenting my project structure/build/deploy/CI methods and instructions, with the ability to execute code from the Markdown documentation. I use it in every project I create, and it makes it really easy to come back to a project where I’ve forgotten exactly how it works. For example, every project has a “Deploy” topic where I detail the steps for deploying/publishing. In any project, I can type howzit deploy and get the instructions, and howzit -r deploy will just execute my automated deploy scripts.

I added a couple of advanced features this morning.

Script-to-Howzit Communication

Scripts can now communicate back to Howzit while they’re running. This lets scripts send log messages and set variables that can be used in subsequent tasks or conditional blocks.

The communication happens through a temporary file. Howzit sets the HOWZIT_COMM_FILE environment variable to point to this file, and your scripts can write to it using a simple format:

LOG:info:This is an info message
LOG:warn:This is a warning
LOG:error:Something went wrong
VAR:MY_VAR=some_value

For example, in a bash script:

#!/bin/bash
if [ -n "$HOWZIT_COMM_FILE" ]; then
  echo "LOG:info:Starting deployment process" >> "$HOWZIT_COMM_FILE"
  echo "VAR:DEPLOY_STATUS=in_progress" >> "$HOWZIT_COMM_FILE"
fi

# ... do your deployment ...

if [ -n "$HOWZIT_COMM_FILE" ]; then
  echo "LOG:info:Deployment complete" >> "$HOWZIT_COMM_FILE"
  echo "VAR:DEPLOY_STATUS=complete" >> "$HOWZIT_COMM_FILE"
fi

Variables set by scripts are merged into Howzit’s named arguments, so they’re available for variable substitution (${VAR}) in subsequent tasks and can be used in conditional blocks. Log messages are displayed through Howzit’s console logger at the appropriate log level.

This is particularly useful for scripts that need to communicate their status or set flags that affect later tasks. See the Script-to-Howzit Communication wiki page for complete details and examples.

Conditional Blocks

Howzit now supports conditional blocks, so you can include or exclude content and tasks based on conditions. Use @if and @unless directives to control what appears in your build notes.

Basic Conditional Blocks

The syntax is straightforward:

@if environment == "production"
@run(./deploy-prod.sh) Deploy to Production
@end

@unless $SKIP_TESTS == "1"
@run(./test.sh) Run Tests
@end

You can also use @elsif and @else for multiple branches:

@if env == "production"
Production setup
@elsif env == "staging"
Staging setup
@else
Development setup
@end

String Comparison Operators

Conditions support various string comparison operators. The newest addition is the fuzzy match operator **=, which matches if the search string’s characters appear in order within the target string. For example, "fluffy" **= "ffy" matches because the characters f, f, and y appear in order.

Other operators include == for exact equality, *= for contains, ^= for starts with, $= for ends with, and =~ for regex matching. See the Conditional Blocks wiki page for details on all comparison operators.

File Contents Conditions

You can now check file contents directly in conditions:

@if file contents VERSION.txt ^= 0.
Version starts with 0.
@end

@if file contents CHANGELOG.md *= "Breaking"
Changelog contains breaking changes
@end

The file path can be a literal path or a variable from metadata, named arguments, or environment variables. This makes it easy to check version files, configuration files, or any other file content as part of your conditional logic.

Special Conditions

Howzit also supports special conditions like git dirty, git clean, file exists, dir exists, and topic exists. You can even check the current working directory with cwd using string comparison operators.

Check out the Howzit project page for general details. For complete documentation on all condition types, operators, and examples, check out the Conditional Blocks wiki page.

Please enjoy, and may Howzit make your 2026 project development smooth!

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

To read more about the inspiration and initial development of mdtosendy, see the blog post I wrote a couple of days ago.

The Problem

Originally, mdtosendy used a single set of template files in ~/.config/mdtosendy/. If you wanted different styling or configuration options for different types of emails, you’d have to manually swap files or maintain multiple config directories. Not ideal.

The Solution: Template Directories

Now you can create multiple templates, each in its own directory under ~/.config/mdtosendy/templates/. Each template can have its own HTML template, CSS file, and configuration.

Creating a Template

Creating a new template is simple:

mdtosendy.rb --create-template mytemplate

This creates ~/.config/mdtosendy/templates/mytemplate/ with:

• email-template.html - copied from the default template
• styles.css - copied from the default styles
• config.yml - blank, so it uses the base config

Then use it with:

mdtosendy.rb --template mytemplate email.md

Child Templates

Even better, you can create child templates that inherit from a parent. This is perfect when you have a base design but want variations:

mdtosendy.rb --create-template darktheme --parent mytemplate

This creates a child template that:

• Inherits all config from the parent
• Inherits HTML and CSS files if they don’t exist in the child
• Lets you override just what you need

The child’s config.yml looks like:

parent: mytemplate

# Parent template config (commented out):
# ... all the parent's config as comments for reference

You can override specific settings in the child’s config, and if you don’t provide HTML or CSS files, it automatically uses the parent’s.

Configuration Hierarchy

The configuration system works in layers:

1. Base config (~/.config/mdtosendy/config.yml) - Your Sendy API settings, default list IDs, etc.
2. Template config (~/.config/mdtosendy/templates/NAME/config.yml) - Template-specific overrides
3. Child template config - Overrides parent template config

Each layer can override the previous, so you can have base settings for Sendy, template-specific list IDs, and child-specific styling tweaks.

Development Mode

I also added a --dev flag that generates an email-dev.html file for easier template development:

mdtosendy.rb --dev --template mytemplate

This creates ~/.config/mdtosendy/email-dev.html with:

• Linked CSS (not inlined) so you can edit styles and refresh
• Sample content showing all the elements
• A template info table showing which template and CSS file you’re using
• Proper wrapper and content-wrapper classes so the styling matches the final email

It’s much easier to iterate on designs when you can edit CSS and see changes immediately in the browser.

Button Variants

While building this, I also added support for button variants. You can now use:

• [Primary](url){:.button} - The default button
• [Secondary](url){:.button .secondary} - Alternative styling
• [Tertiary](url){:.button .tertiary} - Another alternative

Or use the aliases:

• .btn for .button
• .btn.alt for .button.secondary
• .btn.alt2 for .button.tertiary

The script automatically detects which variant to use and applies the correct CSS styles when converting to email HTML.

Backwards Compatibility

If you’re upgrading from an older version, the script automatically migrates your existing template files to templates/default/ on the first run, so nothing breaks.

The multi-template system makes mdtosendy much more flexible for managing different email designs, whether you need completely different templates or just variations on a theme. Check out the GitHub repo for the latest script and details.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

I’m excited to share that Apex version 0.1.41 has comprehensive support for Inline Attribute Lists (IALs), including inline IALs for span-level elements, key-value pairs, and Attribute List Definitions (ALDs). This brings Apex’s IAL support to full feature parity with Kramdown.

In case you haven’t been keeping up, Apex is my universal Markdown processor project. The goal is to create one Markdown processor that incorporates all the best features from other Markdown processors, like Pandooc, Kramdown, Maruku, MultiMarkdown, and more. One processor to rule them all. Learn more on the wiki.

What Are IALs?

Inline Attribute Lists are a Kramdown extension (inspired by Maruku) that let you add HTML attributes (IDs, classes, and custom key-value pairs) directly to Markdown elements. Instead of dropping into raw HTML every time you need to add a class or ID, you can use a simple {: attributes} syntax.

For block-level elements, IALs go on the line immediately after:

# My Heading
{: #section-1 .highlight}

This paragraph has custom attributes.
{: .important .note title="Important Note"}

For inline elements, IALs appear right after the element within the paragraph:

Here's a [styled link](https://example.com){:.button} with a class.

This has **bold text**{:.bold-style} and *italic text*{:.italic-style}.

What’s New

Inline IAL Support

Previously, IALs only worked for block-level elements. Now you can apply attributes to links, images, emphasis, strong text, and code spans—all inline within your paragraphs.

Here's a [button-style link](url){:.btn .btn-primary} that looks great.

You can even style **bold**{:.highlight} and *italic*{:.accent} text separately.

Code spans like `example`{:.code-inline} can have classes too.

Key-Value Pairs

Beyond IDs and classes, you can now add any custom HTML attributes using key-value pairs:

Paragraph with custom attributes.
{: title="Tooltip Text" lang="en" data-id="123"}

[External Link](https://example.com){:rel="nofollow" target="_blank"}

Attributes support quoted values (single or double quotes) and unquoted values for simple cases.

Attribute List Definitions (ALDs)

ALDs let you define reusable attribute sets and reference them multiple times. This is perfect for maintaining consistent styling across your document:

# Header 1
{:section-heading}

# Header 2
{:section-heading}

# Header 3
{:section-heading}

{:section-heading: #main .large .bold lang="en"}

All three headers in the example above get the same set of attributes from the ALD definition on the last line. Much cleaner than repeating attributes everywhere!

Nested Elements

One of the trickier features I implemented is support for nested inline elements with IALs:

**Bold text with *italic*{:.nested-italic} inside**{:.bold-wrapper}

Both the italic and bold elements get their respective classes, even when nested.

How It Works

The implementation uses element indexing to correctly match attributes to elements, even when multiple elements share the same content (like two links with the same URL). This ensures that each element gets the right attributes based on its position in the document.

For inline elements, the processing is recursive, so it handles nested structures correctly. The IAL syntax is extracted from the text nodes and attributes are attached to the corresponding AST nodes before HTML rendering.

Usage

IALs are available in Kramdown and unified modes. In unified mode (the default), they’re enabled automatically. To use Kramdown mode:

apex document.md --mode kramdown

Complete Documentation

I’ve created comprehensive documentation for IALs:

• Inline Attribute Lists Guide - Complete user guide with examples
• Syntax Reference - Quick reference in the syntax docs

The documentation covers all the edge cases, shows examples for every element type, and explains both block-level and inline IAL syntax in detail.

Try It Out

Grab the latest version of Apex and start adding attributes to your Markdown! Homebrew is updated, just follow the Installation instructions in the README. See the release notes for the latest details.

Whether you’re styling links, adding IDs for anchor navigation, or using ALDs to maintain consistent styling, IALs make it easy to add HTML attributes without leaving the comfort of Markdown syntax.

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.

It’s time for my yearly roundup of my favorite tools, hardware, and projects. I’m combining everything in one post this year. You might find something new, or you might just have your own preferences validated. Feel free to add your own suggestions in the comments!

It’s been an interesting year. I lost my job in April, and have spent the remainder of the year furiously coding, mostly on Marked 3. A lot of my top picks for the year are a result of that.

macOS Apps

Cursor

As skeptical as I am about AI in the world in general, I’ve almost mastered getting great results from Copilot and Cursor, Cursor being my tool of choice. Claude is good, but I like the interface of Cursor better.

I should also mention cmux, which has been helpful, but a lot of what I originally liked about it has already been incorporated into Cursor.

Cotypist

A little more AI. This one offers predictive text anywhere you’re typing. It’s very intelligent and generally completes my words and sentences like it’s reading my mind. It’s especially useful in Cursor, where it completes variable names and writes prompts basically magically for me.

Tower

More great improvements this year from my favorite Git client. The UI keeps getting better. They added support for Graphite (stacked PRs), plus other advanced functionality. Tower even released a rebuilt version of git-flow (git-flow-next)

One thing I discovered is that if you paste a full commit message into the commit subject field, with the message on the first line, a blank line, and then the commit body, it will automatically format it for you, breaking the body into the notes field. I have Cursor write my specialized changelog commits for me, then just paste them into Tower, where I have full control over what gets staged and committed.

Kaleidoscope

Still my favorite diff tool. I love it for resolving merge conflicts, but also for things like directory comparison/merging and image diffing. The image diff in Kaleidoscope got a huge update this year and is pretty spectacular.

KindaVim

This nifty utility lets you enter a limited “Vim mode” in any text field. I use it everywhere, allowing me to use Vim navigation when I’m typing in places like nvUltra or iTerm.

You can use b and e to move to word boundaries, f and t to jump to characters, and even dd or d$ to delete text. a and i work for returning to “insert mode” (ending Vim navigation), as well as o and O.

LeaderKey

Another really handy tool. I use LaunchBar for most app launching and navigation, but for some reason I’ve really enjoyed assigning key sequences to specific apps and URLs. With LeaderKey I can just hit Hyper-A, f, q to launch MailMate (I know it’s not mnemonically intuitive — long story). Once you have the muscle memory for it, it makes navigating and launching super fast.

I believe you can achieve the same effect with Keyboard Maestro conflict palettes, but LeaderKey is super easy to configure and, well, free¹.

DEVONthink

I’ve been a DEVONthink owner for over a decade, but never fully invested in it until this year. Researching my own health issues, saving my reading highlights, and creating a knowledgebase of PDFs and web pages has been really useful. And holy moly DEVONthink has an extensive feature set for building your database exactly the way that works for you.

The thing that really made me love it is that I can integrate everything with my plain text notes (in nvUltra), syncing between the two with zero effort.

Mona

I’ve deleted my Twitter account (yes, I refuse to call it X) and my Threads account. I dug in entirely to Mastodon, and after trying a bunch of native apps, I found Mona and it blew me away. Great functionality. You can find me on Mastodon at ttscoff@hachyderm.io and on Pixelfed (Instagram alternative) at ttscoff@pixelfed.social. Come find me with whatever client you choose.

I had 5x as many followers on Twitter than I do on Mastodon, but I get way more interaction on Mastodon than I ever did on Twitter. It’s a vibrant and active community and you should join if you haven’t.

TaskPaper

I know it’s not actively developed anymore, but I still rely heavily on TaskPaper for organizing my project todos. I keep a separate TaskPaper file in every project directory, which I interact with via Next Action, but when I want to manage the todo list, TaskPaper is still my go-to. I love OmniFocus for the rest of my life, but for coding projects, TaskPaper rules.

Typeface

I use the Setapp version of Typeface for all my font management these days. I spent years paying for expensive font management software, but none of the major players have kept up, and they’re mostly bloated apps these days. Typeface is a clean interface for viewing large font collections, with great preview and typography tools, and easy activation and deactivation of font families.

Hookmark

Hookmark is crazy useful, once you get in the habit of linking things. It lets you link anything to anything, and easily navigate between the current item and related documents, web pages, todo items, lines of code, and more. If you want to purchase, here’s my affiliate link.

If you’re a developer, check out this blog post for ways Hookmark is a vital tool for coding.

MailMate

I try pretty much every email client that comes out, but nothing has tempted me away from MailMate. It’s so powerful and flexible that I pay twice for it.

iTerm

Similar to email clients, I try every terminal emulator that comes out. There are a lot of cool options, but none of them have all the features that iTerm provides. It’s another one that’s free but I pay for anyway.

Setapp

There are a bunch of apps on Setapp that I use — more than enough to justify the cost. Marked is on there, and v3 will be automatically available to subscribers. I won’t list all of the apps, but check out the apps list to see what all you can get.

One highlight is CleanShot X, which is still the only screen capture app I need. It does everything so elegantly.

Another indispensable tool is Paletro, which gives me a type-ahead search of all menu items for the current app. I hit ⇧+⌘+P and access any function I need, in any app.

I also use Setapp for: TaskPaper, Typeface, BetterTouchTool, Permute, Downie, AlDente Pro, Ulysses, Forklift, Timing, NotePlan, Dash, CodeRunner, Default Folder X, Soulver, HoudahSpot, In Your Face, Hookmark, BoltAI, IconJar, Unite, SSH Config Editor, Trickster, KeyCue, and MindNode Next.

I own a lot of these apps outside of Setapp, but I use the Setapp version of those because it means the developers also gets a chunk of my subscription fee.

Web

Kagi

I just switched to Kagi as my default search engine at end of 2025. No ads, better AI stuff, great keyboard navigation, and you can report and exclude AI slop sites from your search results (which was my primary reason for switching). It’s a paid service, but it’s worth $5/mo (or $10 with unlimited searches), and you can also get a family plan that gets 6 people professional access for even less per person.

Readwise

I’ve been paying for Readwise all year. It’s an awesome way to handle read-it-later lists, with highlighting, tagging, and note-taking. I save all long-form articles I want to read to Readwise, and I use it as my RSS reader as well. I can sync it with other apps, turn highlights into flash cards, and I can access all of my reading on my Mac, iPhone, and iPad.

The Reader app works with your Readwise reading list, and offers a great reading experience with full keyboard control.

The browser plugins make saving articles and highlighting text right on web pages a breeze.

Apache Answer

I’ve switched Marked support over to Answer. I lost a little functionality like the ability to reply to email notifications and have the response go to the ticket instead of the user, but overall I’m finding it better than my previous Tender setup. Tender hasn’t been updated in like 10 years and their customer support is poor. Answer is free, and I run it on PikaPods for a couple bucks a month.

linkding

I’ve completely replaced Pinboard with linkding, running on my Synology and publicly accessible. With my card-based custom layout and complete API, it’s an excellent bookmark manager.

Umami

I’ve long used Fathom for privacy-focused web analytics, and it’s still an excellent option, but I’m running Umami in parallel right now. It’s a fantastic interface with lots of extra data, still completely privacy focused.

SaneBox

SaneBox has made my list for years. I’m so used to it tidying my email workflow that I don’t even think about it anymore, but would sincerely miss it if it were gone.

SaneBox sorts your email into trainable folders, automatically cleaning out your inbox so it only contains important emails. You can scan your @SaneLater folder when you have time, and you can train it to sort things like newsletters or promos into folders you may or may not ever look at.

Use this link to get a $25 credit.

iOS

I mostly use my iPhone for texting and gaming. And I play mostly the same games I’ve played for years, so I don’t have a long list of new stuff to share here. I use a ton of apps, but not many new or exciting ones, aside from this short list.

Drafts

I also really dug into using Drafts this year. When I wake up in the middle of the night with an idea, I just open Drafts and type it up to get it out of my head so I can fall back asleep. Then I can easily check it on my Mac when I’m up, and use Drafts actions to send it where it needs to go.

I use the Drafts Mac app as a scratchpad for what I’m going to do next when working on a project. It’s especially handy for sketching out AI prompts while another one is working.

Impressia

A great little client for Pixelfed. I do most of my Pixelfed interactions via Mona (it’s just a Mastodon server), but Impressia and the Pixelfed app are great for browsing.

Paprika

Paprika is the best recipe manager I’ve ever found. I’ve used it for a decade and it’s well-maintained and great for saving recipes, creating and sharing shopping lists, and for actually cooking in the kitchen with checklists and timers.

Super Monsters Ate My Condo

Still one of the best games I’ve ever played. As of 2025 it’s available in Apple Arcade.

Threes

I spend more time in this app than I do in any other. It’s a perfect puzzle game. It’s been around for as long as I can remember. It’s available on Arcade now, but the classic version is better for reasons I won’t go into.

Zen Pinball Party

This is OK on iPhone but great on iPad. A whole bunch of different pinball tables. The physics and gameplay differs between tables, so it’s really a bunch of apps in one. I generally focus on one table at a time and get really good at it, moving on when I get 3 stars or feel like I’ve reached my potential. I’ve cycled through most of them repeatedly.

Spark

Spark is my email client of choice on iPhone and iPad. It’s quite powerful, easy to use with multiple layouts, and has great snooze and quick reply features.

Spark incorporated more AI this year, but I don’t use it. I don’t think I’ll ever want AI to write emails for me.

Hardware

Living on unemployment and not having Marked 3 or nvUltra out yet, I haven’t had a lot of extra cash for hardware. I invested in a few things, though.

Homepod Mini

I’m really late to this scene, but I’m finally ridding my house of all Amazon products, and the Homepod was the least of all evils when it comes to home assistants. I’ve only purchased the minis at this point, and they fulfill all my needs just fine. There’s a little more latency than I had with Alexa, but far fewer privacy concerns.

I’ll be honest, my primary use for an assistant is controlling multiple timers in the kitchen hands-free. Siri is good at that. And the sound quality for playing music while cooking is exceptional.

M4 MacBook Pro

This is the greatest machine I’ve had since the 2012² MacBook Air, which I long considered Apple’s best product. I still love my first-gen Studio, but the combination of speed, battery life, and portability make the M4 MacBook a killer machine.

I have my Mac Studio paid off, but I’ll be paying on this beast for a while.

StarTech.com 4-Port USB-C Charging Station

I needed a powerful charging hub that could charge my laptop, phone, and iPad all at the same time, and I needed it to be mountable. I used to use nano tape to attach a charging hub to my bedside table, but to get a hub powerful enough to handle all these new devices, you have to get one that weighs too much to stick with tape. So I needed one I could screw in. This is the best one I found, complete with VESA mounting plate.

Projects

Bear & Glass

Christopher Gamblée Wallendjack and I launched a consulting firm this year. We’re still getting a foothold, but I’m excited about the possibilities. If you’re looking for help with automation and streamlining your business, drop us a line for a free consultation.

Readwise to DEVONthink

This script runs on my always-on Studio, and as I create highlights in Readwise, they automatically show up as annotated Markdown documents in my DEVONthink database. It’s been a really handy way to save articles.

SearchLink

I added URL Previews and link shortening to SearchLink this year. It’s still a tool I use every day and I think it might be the most useful thing I’ve ever created.

Off White

My stupid color picker for barely off-white and -black colors, now with gradients.

RNKD

This was a project I built for my own needs but made public. It allows you to create polls with text and images, and then share them with ranked choice voting. There are other polling services, but you often can’t use images (which is important for getting design feedback), and I couldn’t find any that offered ranked choice, which offers more usable results than just simple voting.

SVG Viewer

I wrote the BT SVG Viewer WordPress plugin for Allison Sheridan. It lets you embed large SVG diagrams in your posts, with full navigation, zooming, and text search. It was a fun project.

I also made a Jekyll plugin version with an editor that generates Liquid tags for you.

md-lipsum

I made a massive v4 update to my Markdown lipsum generator, and also published the random-words gem for generating your own tools.

Ripple

I went down a rabbit hole creating indeterminate progress indicators. This Ruby library and accompanying CLI is the result.

Apex

This in an ongoing big project: I started building my own Markdown processor late in the year. Apex is designed to be a permissive Markdown processor that incorporates syntax from man other tools into one unified processor. Pandoc, Kramdown, CommonMark, MultiMarkdown, plus advanced table syntax, index support for multiple syntaxes, and full bibliography support.

NA

I made a lot of updates to Next Action, my tool for command-line management of TaskPaper files. Among other improvements, I added support for TaskPaper search syntax, and updated my TaskPaper to MD script.

Howzit

My project documentation and task runner got a ton of updates. This is another tool I use daily. I’ve taught Cursor how to write Howzit-compatible build note files, so after I scaffold out a new project, it can automatically generate the build notes with runnable topics for me based on the project requirements.

Marked 3

As I mentioned, most of my time in 2025 has gone to Marked 3. It’s an insanely huge update to Marked 2, with completely rewritten DOCX, Scrivener, CriticMarkup, PDF export, writing tools, and much, much more. Coming soon, and the beta is public!

nvUltra

Fletcher and I made a lot of progress on nvUltra this year. The final piece of the puzzle should be solved by some things I’ve built for Marked, and as soon as that’s public I’ll start porting them to nvUltra, hopefully getting it out the door pretty quickly after the Marked release. The beta is basically public at this point, just contact me through the website for an invite.

Those are my highlights at the end of 2025. Not nearly a complete list of all the great apps and services I’ve tried and used this year, of course. Share your own favorites on the forum!

Like or share this post on Mastodon, Bluesky, or Twitter.

BrettTerpstra.com is supported by readers like you. Click here if you'd like to help out.

Find Brett on Mastodon, Bluesky, GitHub, and everywhere else.