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

The worst decline of democracy ever recorded could have been far worse.

The institutions that were supposed to be the brakes either surrendered or stumbled over each other. The people put themselves in the gears.

I don’t make this blog very political, which is odd given how political I am in my personal life. But this shouldn’t be a partisan post. This is about all of us.

Open Source Gave Me Everything Until I Had Nothing Left to Give - Kenneth Reitz

Not a perfect parallel to my own experience (I’ve never had a top open source project or gotten into keynoting) but this rings very familiar to me. My acclaimed “productivity” has been the result of some very trying bipolar episodes that plagued me for years, leading to burnout.

doing in Rust

A full port of my Ruby project, Doing, to Rust. Coming along nicely.

A command line tool for remembering what you were doing and tracking what you’ve done — stored as plain text, versioned with your project.

Steno — Your keyboard slows you down.

Steno is a native macOS voice-to-text app. Hold a key, speak, release — text appears instantly in any app. Sub-second transcription, voice commands, text snippets, and dictation history. Built with Swift for speed and accuracy.

Impressive AI-driven dictation with great privacy features and local-only mode (Apple Intelligence).

Automating iOS Shortcuts - The Cron Job Way

Today’s unnecessary and over-engineered thing is automating iOS (and macOS) Shortcuts using the same syntax that’s used to schedule cron jobs.

Check out Setapp today and get access to the best Mac and iOS apps out 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.

The keyboard is the most powerful tool we have when using our Macs, which is why I’ve curated what might seem like an overwhelming combination of keyboard utilities that I use daily.

Each of these tools enhances my productivity in unique ways, so whether you’re looking to streamline your workflow or just want to explore some interesting keyboard hacks, I hope the following links and descriptions can help you find something valuable.

Keyboard Navigation

When it comes to navigating my system with speed and precision, a few key utilities stand out. I use Superkey to enhance my existing keyboard shortcuts, making application navigation smoother and more efficient. It searches text on the screen and simulates a mouse click anywhere there’s matching text. It allows me to access features and functions without ever taking my fingers off the keyboard. For those looking for a similar solution, Wooshy offers a compelling alternative, providing seamless keyboard control for navigating all UI elements in an app.

Another indispensable tool in my toolkit is KindaVim, which brings Vim-like key bindings to any application, allowing me to navigate text with great efficiency. It’s perfect for those who appreciate the keyboard-centric ease of Vim.

KindaVim isn’t perfect, but it’s constantly improving. But as an example, if I use V and h/j/k/l in MultiMarkdown Composer to make a selection, when I hit X to kill the selection, the cursor jumps up a few paragraphs. It’s a bit jarring, but for basic Vim navigation like h/j/k/l/u/d/a/i, etc., it’s perfect, and enhances every app I write in.

There are always keyboard shortcuts for common menu items in any Mac app. I frequently access menu bars with ⇧+⌘+? and use the help field to find menu items, and try to memorize ones that have the keyboard shortcut indicated on them. I have an as-of-yet-unpublished script based on NiftyMenu that scans any app for every available shortcut and generates Dash cheatsheets or Cheaters pages for it.

Speaking of menu item keyboard shortcuts, Paletro is amazing. It gives me a ⇧+⌘+P shortcut in any app, with fuzzy type-ahead searching for any menu item. I use it daily.

Lastly, Scrolla is a game-changer for scrolling through documents and long text, enabling me to keep my hands on the keyboard whenever I need to go through lengthy content.

Keyboard Modifications

For deeper customization, I rely on a mix of tools that modify key functions and introduce new shortcuts.

BetterTouchTool is a powerhouse for managing trackpad gestures and keyboard shortcuts, letting me create personalized commands that fit my workflow perfectly.

Karabiner-Elements takes it a step further with its ability to remap keys at the system level, modifying their behavior. I’ve set up my Hyper key using this tool, which unlocks numerous possibilities for shortcuts and personalizations (check out my Karabiner mods for some advanced tweaks).

Additionally, my DefaultKeyBindings.dict file is essential for crafting custom keyboard shortcuts tailored to my preferences. MacOS’s built-in key mapping features allow for sophisticated combinations that further enhance my efficiency. Coupled with Keyboard Maestro, which automates repetitive tasks and creates amazing automations, I’m able to truly streamline my text editing.

Launchers

When it comes to launching apps and managing my clipboard, LaunchBar reigns supreme in my daily workflow. I’ve experimented with every launcher out there, but nothing has stuck quite like LaunchBar. Its intuitive interface complements my muscle memory, allowing me to access apps, files, and even perform quick calculations without losing focus.

With LaunchBar, I can access my entire clipboard history across reboots, copying things back into the pasteboard or pasting them directly. And I can double-tap the option key to “Instant Send” any selected file to LaunchBar, then hit tab to open it in an app or perform a custom action on it. Combined with KindaVim’s ability to navigate Finder with ease and SuperKey’s ability to select any file I can see on my screen, it’s crazy how useful LaunchBar is.

Though LeaderKey might seem redundant alongside LaunchBar, it offers the benefit of static, single-key sequences for launching frequently used applications and URLs. This has also become a part of my muscle memory, enabling quick access without sifting through multiple options. Combining these tools gives me a powerful launching and navigating experience.

Text Expansion

In the realm of text expansion, I’ve been a longtime user of TextExpander, with its snippet search capabilities and reminders making it an indispensable part of my writing process. I’ve also started using TextBlaze, but I’ve found myself confusingly using both tools at once. TextExpander’s ability to run shell scripts gives it an edge that can’t be ignored, and its expansion after whitespace is something that TextBlaze doesn’t quite match.

My current favorite text expansion tool, however, is Cotypist. This innovative tool offers automatic text completion as I type in any application. It predicts my inputs with uncanny accuracy, making it my go-to for prose writing. I don’t have to create a ton of snippets, it just figures out what I’m typing and fills in the blanks. It works great in apps like Cursor, too, completing instructions and prompts accurately.

Window Management

For window management, Moom is my weapon of choice. It allows me to move and resize windows with ease, using keyboard shortcuts that fit seamlessly into my workflow. The grid mode, in particular, lets me draw sizes and positions for windows on the fly, making multitasking a breeze and alleviating the need to have a thousand shortcuts for different positioning.

Web Browsing

In my browsing experience, Vimium has become indispensable. It enhances productivity in my favorite browsers by adding Vim-style navigation to web pages. If I type F, it tags every visible link with key sequences, enabling navigation that feels quick and fluid.

Coupled with my preferred search engine, Kagi, which provides the ability to navigate search results entirely with the keyboard, my online experience is streamlined. While DuckDuckGo offers similar shortcuts, Kagi’s advanced AI slop filtering adds to its appeal, making it a superior choice for my digital searches.

I hope you’ve found something new in all of this. I’d love to hear about your own favorite keyboard tools and shortcuts: please share them over at the forum and let’s master the keyboard!

Here’s a combined list of every app mentioned in this post:

• KindaVim
• Superkey
• Wooshy
• Scrolla
• Brett’s Keybindings
• Keyboard Maestro
• Moom
• BetterTouchTool
• Karabiner-Elements
• TextExpander
• TextBlaze
• Kagi
• Vimium
• Cotypist
• LeaderKey
• LaunchBar
• My Karabiner mods
• Dash
• NiftyMenu
• Cheaters
• Paletro

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 can render Markdown to the terminal (-t terminal or -t terminal256) with ANSI colors and themes. As of 0.1.100, it can also draw images inline when stdout is a real TTY: your ![alt](path-or-url) images show up as actual graphics instead of only link-style text.

What actually draws the image

Apex does not embed a rasterizer. It looks for an external viewer on your PATH, in this order:

1. imgcat (iTerm2-style inline images)
2. chafa
3. viu
4. catimg

The first one that exists wins. If none are found, or something fails, or you are piping output (not a TTY), you get the same link-style fallback as a normal terminal link: styled alt text plus the URL in parentheses.

Remote http:// and https:// images are downloaded with curl (temp file under TMPDIR or /tmp, then deleted). There is a size cap and timeout so runaway downloads do not blow up your session.

Flags and metadata

• --no-terminal-images turns inline rendering off entirely (always link-style).
• --terminal-image-width N sets the maximum width in character cells (default 50). This is separate from --width, which wraps prose.

You can also set terminal.inline_images / terminal_inline_images and terminal.image_width / terminal_image_width in metadata or config.

Installing the viewers (macOS)

iTerm2 ships imgcat on your PATH when you use its utilities, so you may already have the first choice. The others are a quick Homebrew install:

# Optional: pick one or more (Apex uses the first available on PATH)
brew install chafa viu catimg

On Linux, use your distro packages or the projects’ install notes; the same binary names apply.

Other stuff

Since 0.1.95, this line of releases also landed a bunch of other work. Highlights:

• CSV/TSV includes with custom delimiters ({delimiter=X} or {;}) across iA Writer, Marked, and MultiMarkdown include styles.
• Metadata handling improved: mode-aware extraction, better MultiMarkdown / Unified / Kramdown behavior, and standalone HTML now emits generic metadata as proper <meta name="..."> tags.
• MultiMarkdown includes and transclusions accept embedded delimiter overrides without breaking on braces in paths.
• Swift tooling: ApexC exposes the C API for SwiftPM, collision fixes for apex_* symbols, and NSString.defaultApexOptions() for plugins that need low-level options.
• HTML output shape: --to xhtml serializes void elements in XML style (<br />, self-closing meta/link, and so on). --to strict-xhtml goes further for full documents: with --standalone it adds polyglot XHTML scaffolding (XML declaration, XHTML namespace, application/xhtml+xml metadata). Use one or the other; they target different strictness levels.
• Homebrew formula updates for recent releases.

If you want the full blow-by-blow, see the project changelog 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.

If you write documentation, tutorials, or notes that include keyboard shortcuts, you know how annoying consistency can be. Sometimes you want plain text like Shift-Command-K, sometimes you want nice symbolic output like ⇧⌘K, and sometimes you want HTML keycaps.

This project started as a Jekyll plugin, then became a WordPress plugin, and now I’m offering it as a CLI and Automator Actions you can use anywhere.

What the scripts do

The project ships two Ruby scripts that parse keyboard shortcut text and normalize it into consistent output, following Apple’s guidelines by default:

• kbd.rb outputs HTML keycap markup.
• kbd-text.rb outputs plain text shortcuts.

Both scripts accept flexible input formats, including:

• Keybinding Symbol style: "$@k"
• Text style: "shift cmd k"
• Hyphenated style: "Shift-Command-k"
• Multiple combos separated by " / "

For keybinding style:

In practice, this means you can type shortcuts however you naturally type them, and the tool will clean and format them for you.

Download and install as Quick Actions

Grab the latest release from:

• Latest release download

Then install:

1. Download KBD Automator Actions.zip.
2. Unzip it.
3. Double-click each .workflow file.
4. Confirm installation when macOS prompts.

After that, the actions show up as Services/Quick Actions for text handling.

Add keyboard shortcuts for the Services

Once installed, assign your own hotkeys:

1. Open System Settings.
2. Go to Keyboard.
3. Click Keyboard Shortcuts.
4. Select Services on the left.
5. Find Text -> KBD *.
6. Click the shortcut field on the right.
7. Press the shortcut you want.

That is it. You now have a fast shortcut-to-formatted-shortcut pipeline available from anywhere.

Configuration

The scripts read config from:

• ~/.config/kbd/config.yaml

You do not need to create this manually. The first time either script runs, it writes this file with default values.

Available keys under kbd::

• use_modifier_symbols (default: true)
  • true: prefer symbols like ⌘, ⌥, ⇧
  • false: use words like Command, Option, Shift
• use_key_symbols (default: true)
  • true: use symbolic key names where possible
  • false: use text key names
• use_plus_sign (default: false)
  • false: combine modifier symbols with no separator (⇧⌘K)
  • true: join with + (⇧+⌘+K)

Build and release it yourself

If you want to generate or ship your own builds, the repo includes Rake tasks for:

• building self-contained scripts
• generating signed Automator workflows
• packaging release zip files
• bumping versions and publishing GitHub releases

Project link:

• ttscoff/kbd 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.

If you want the full docs, start with the wiki.

Time Budgets

You can now set time budgets per tag and see how much you have left as you track work.

doing budget dev 100h
doing budget meetings 10h
doing budget
doing budget dev --remove

Totals output now shows remaining budget per tag and an overall “total budgets left” footer when budgets are configured. The byday export also includes budget info in daily and grand totals.

More Flexible Totals Grouping

Totals can now be grouped by tags or sections, and you can repeat grouping flags to control output order.

doing show --totals --by section --by tags
doing show --totals --by tags --by section

There are also aliases for section grouping (project, p), so this works too:

doing show --totals --by project

New Totals Formats, Including Averages

You can now pick the totals time format directly from the command line with --totals_format.

doing show --totals --totals_format hmclock
doing show --totals --totals_format natural

There is also a new averages mode that appends hours/minutes and average hours per day to the total line.

doing show --totals --totals_format averages

That gives you output in the spirit of:

Total tracked: 26:03 (26h 3 min, 8.12h/day)

You can set a default with the totals_format config key and still override it per command when needed.

Better Export Consistency

Totals grouping now carries through exports more consistently, including HTML, Markdown, JSON, Day One, template, and wiki outputs. JSON totals also gained budget-related fields (budget, remaining, remaining_formatted) for each tag, which makes downstream automation easier.

For details on output and display options, see wiki pages like Displaying Entries, Time Tracking, and Configuration.

Other Stuff

• Ruby 4 compatibility improved by falling back to reline when readline is unavailable.
• Dashed aliases now work for underscore flags and subcommands (--only-timed, --tag-sort, doing tag-dir, etc.).
• Interactive finish handling was fixed for section filters that can resolve to multiple values.
• Time range parsing and normalization got several fixes (done --from, noon/12pm edge cases, and reset formatting issues).
• Non-interactive runs no longer reopen /dev/tty for defaults.
• Human totals box formatting and table alignment were cleaned up.
• A few config and test harness rough edges were fixed.

As usual, if you run into anything odd, open an issue or PR. This was a nice round of polish plus some features that should make time reporting much more useful day to day.

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.

Dropzone is a menu bar productivity tool that gives you a faster way to move, copy, and share files, launch apps, and trigger all sorts of time-saving drag-and-drop actions without breaking your flow.

The newly released Dropzone 5 is a substantial update and has been redesigned for macOS Tahoe with a cleaner interface, smoother animations and support for Liquid Glass.

The update also adds several workflow-focused improvements. Multiple grids make it easy to separate actions by project or context, deeper grid customization gives you more control over categories, columns, and layout, and folder-based actions can now display the custom icons and colors you’ve assigned in Finder, which makes it easier to identify your folders in Dropzone at a glance.

If you like to automate from the command line, Dropzone 5 includes a powerful command line tool for Terminal integration too. You can run actions, manage files in Drop Bar, and switch between grids via the command line tool, making Dropzone 5 a better fit for scripted workflows than ever before.

Dropzone 5 is available as a free download from Aptonic, with a Pro upgrade available that adds more advanced features.

For a limited time, the Pro upgrade is available at a 30% discount with the coupon code LAUNCH.

Visit Aptonic’s website to learn more and download Dropzone 5.

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.

The Unite Pro giveaway has ended, and I have winners to announce!

The winners!

Congratulations to:

• Sven Sackers
• Michael Steadman
• Jake Bordens
• David Banham

You should have received an email with details, please let me know if you didn’t hear anything!

But I didn’t win!

If you didn’t win, sorry, but Unite Pro is still worth checking out. Turn your favorite websites into apps with Unite Pro! You might not have won, but you can still save 20% at bzgapps.com/unite with code Brett.

By the way, Unite Pro is also available on Setapp, along with hundreds of other amazing apps. You should probably get a subscription.

That’s the end of this giveaway series for now!

If you want to suggest an app you’d like to see in this series, let me know on via email or on Mastodon, and join the email list for notifications!

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.

• Firefox via the Firefox extensions marketplace
• Chrome via Chrome Web Store

Hope you find it useful!

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 Fabric, the best way to organize your notes, tasks, and projects in one place.

Tokie

Ok, this is cool. A macOS file manager that turns your folder into a database for better file management, with some very cool integration with your AI agent, built-in Markdown editor, custom fields for file management, and a ton of other capabilities.

A proposal for Markdown on ATProto

Providing a Lexicon for putting Markdown in the ATmosphere.

Fits nicely into my thoughts about a Markdown Web and has a fair amount of thought and feedback already in the spec.

GitHub Actions for WordPress

I know this has a limited audience, but if you develop WordPress plugins and haven’t explored 10up’s GitHub actions, you really should. The deploy one is infinitely useful and means you never have to deal with SVN after intial repo setup.

rhsev/matterbase

Ralf keeps putting out cool stuff: “A database-like TUI for querying frontmatter and YAML in Markdown notes with field filters, full-text search, and table view. For macOS and Linux.”

Let Fabric be your second brain, with an all-in-one AI workspace and smart organizer for all your projects, ideas, notes & links. 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’m excited to offer the next giveaway, 4 licenses ($39.99 value each) for Unite Pro. Unite has long been my favorite way to create Single Site Browsers (SSBs), sandboxing things like Facebook and MindMeister while adding app-like functionality. The latest version, Unite Pro, is out now, and I have free copies!

From the developer:

We’ve taken everything we’ve learned since 2017 and rethought it for modern macOS. The result is faster, more flexible, and significantly more powerful — while staying true to what makes Unite valuable: turning web apps into genuine Mac-native experiences.

Check out the Unite Pro site for more info.

Sign up below to enter. Winners will be randomly drawn on Friday, March 13, at 12pm Central. The drawing is for 4 licenses ($39.99 value each) for Unite Pro, one per winner. Note that if you’re reading this via RSS, you’ll need to visit this post on brettterpstra.com to enter!

New rule: All signups must have a first and last name in order to be eligible. Entries with only a first name will be skipped by the giveaway robot. A lot of the vendors in this series require first and last names for generating license codes, and your cooperation is appreciated!

Sorry, this giveaway has ended.

If you have an app you’d love to see featured in this series of giveaways, let me know. Also be sure to sign up for the mailing list or follow me on Mastodon so you can be (among) the first to know about these!

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 silly idea I had. I don’t like to keep a bunch of icons in my Dock, preferring to use Bunch along with a simple set of persistent Dock apps. I do keep Firefox in the Dock, but I use a bunch of browsers for different purposes, so what if I could access all of them from the Dock without polluting it?

I use Choosy as my default browser. It allows me to pop up a menu or select a default browser whenever I open a link, based on custom rules. There are multiple variations of this idea, but Choosy is the original and still my favorite.

Choosy has a url scheme that you can use to pop up browser menus, among other things. So getting a menu of all my browsers is as easy as setting up a Shortcut to open x-choosy://prompt.all/URL. For this purpose, I’m using the Kagi search page as my URL, since that’s where most of my browsing sessions start.

You can also just open x-choosy://prompt.all/ to open a browser without opening a web page.

Then you can just right click on the Shortcut in the Shortcuts app and “Add to Dock,” position it where you want it, and you’re done. One click to open any of your browsers. I tried adding a custom icon to it, but failed, so I just have a “Shortcuts” icon in my Dock.

When I click the shortcut in the Dock, I get the Choosy browser menu, with my running browsers highlighted but all of my browsers accessible.

There’s probably a way to get it to work well as a Share item for URLs, but the fact is that if I’m opening a URL, I already have Choosy as a share option, and if I’m opening from a browser, I have a Choosy plugin to do it. I just want all of my browsers in my Dock without adding 10 icons to it permanently.

As a side note, I also set up an Open URL action in LeaderKey to do the same thing. When you hold down ⌘ while the browser picker is open, shortcut overlays appear on the browsers, so you can open any browser with a keyboard shortcut, making launching any browser keyboard-based. Of course, this is somewhat useless if you use a launcher like Alfred or LaunchBar, as your browsers are all a few keystrokes away anyway, so I’m just experimenting to see what my brain likes best…

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 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 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 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.

Update: The extension has been approved for Firefox, install it from the store.

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.