Blog

Let the Merge Make the Tag

2026-11-05T12:00:00-08:00

I’ve tagged a release before merging it more than once. The pull request looked ready, so I created the tag, wrote the notes, and then merged. The tag pointed at the commit on the release branch instead of the merge commit. Each time, I had to delete the tag and the release and make them again.

The fix wasn’t to be more careful. It was to stop tagging by hand.

Make the merge the release step

My projects already use a release branch named after the version, such as release/1.1.6. That branch only bumps the version number and moves the changelog notes under the new heading. So the merge of that pull request is the moment the release is ready, and a workflow can do the rest.

In GitHub Actions, the trigger is a pull request that was closed and merged into the main development branch from a branch that starts with release/.

on:
  pull_request:
    types: [ closed ]
    branches: [ develop ]

jobs:
  release:
    if: github.event.pull_request.merged && startsWith( github.head_ref, 'release/' )
    runs-on: ubuntu-latest
    permissions:
      contents: write

The job reads the version from the branch name and creates the release on the merge commit, which is github.event.pull_request.merge_commit_sha. Using gh release create with --target set to that commit creates the tag in the same step.

Check before you publish

A release that runs on its own should refuse to run when something doesn’t match. Mine stops if:

the branch name isn’t a valid version
the version in the code doesn’t match the branch
a release with that tag already exists
the changelog has no section for that version

The release notes come from that changelog section, so the notes on GitHub match what’s in the repository.

One catch with built files

For a theme, the release also needs a ZIP. I had a separate workflow that built it whenever a release was published. A release created with the workflow’s own GITHUB_TOKEN doesn’t trigger other workflows, so that ZIP never appeared. Building and attaching the ZIP in the same workflow that creates the release fixed it.

Now a release is one action: merge the release pull request. The tag lands on the right commit every time, and I don’t have to remember the order.

Keeping a Homelab Change Log You’ll Actually Use

2026-11-04T12:00:00-08:00

After an evening of changing network settings, it’s easy to remember the fix and forget the two changes that came before it. A short log makes it easier to reconstruct what happened when a service breaks days later.

Keep the entry small

Start with the date and the system you touched. Write what changed, how you verified it, and what you would reverse if it caused trouble. A sample entry might read like this.

Moved the test web app behind the reverse proxy. Confirmed the homepage and one static asset over HTTPS from a second network. The previous proxy configuration is saved with the project’s configuration history.

Include details that will help your future self, such as a config path or an affected port. Keep passwords and tokens out of the log. A plain Markdown file is enough. The value comes from writing the entry while the change is fresh and being able to find it when you need it.

ClassicPress Customizer: postMessage or Refresh?

2026-11-03T12:00:00-08:00

When I add a setting to a ClassicPress theme, I start by asking what has to change in the preview. A color picker feels better when you can see the color as you move it. A sidebar setting may change which template loads and what markup it produces. Those two settings call for different preview behavior.

Transport	What happens in the preview	When I’d use it
`refresh`	The preview reloads and PHP renders the page with the pending settings.	Template changes, switching sidebar layouts, or settings that change what PHP outputs.
`postMessage`	The preview receives the pending value and JavaScript updates the page in place.	Text, colors, and other changes that affect elements already in the page.

I start with refresh and use postMessage where the immediate feedback is worth maintaining a small JavaScript handler. Both let you preview a pending change before publishing it. The transport changes how the preview updates. It doesn’t change how you register, sanitize, or save the setting.

Use refresh when PHP owns the layout

Imagine a setting that switches between a sidebar and a full-width page. If the full-width template leaves out the sidebar entirely, switching back involves more than changing a CSS class. The sidebar markup and widgets have to be rendered again. I’d keep that setting on refresh, which is the default. That way, the preview uses the same PHP templates as the live site.

If reloading the entire preview is distracting and PHP can render the change as a self-contained section, consider selective refresh. It can replace that section using server-rendered markup. It’s worth a look when you need PHP to stay in charge but only part of the page needs updating.

Use postMessage for a footer credit

Here’s a complete preview example for plain footer text. Register the setting and control in your theme’s functions.php. Replace the example text domain with your theme’s own.

add_action( 'customize_register', function ( $customize ) {
    $customize->add_section( 'example_footer', array(
        'title' => __( 'Footer', 'example-theme' ),
    ) );

    $customize->add_setting( 'example_footer_credit', array(
        'default'           => '',
        'sanitize_callback' => 'sanitize_text_field',
        'transport'         => 'postMessage',
    ) );

    $customize->add_control( 'example_footer_credit', array(
        'section' => 'example_footer',
        'label'   => __( 'Footer credit', 'example-theme' ),
        'type'    => 'text',
    ) );
} );

add_action( 'customize_preview_init', function () {
    wp_enqueue_script(
        'example-customizer-preview',
        get_theme_file_uri( 'assets/js/customizer-preview.js' ),
        array( 'customize-preview' ),
        wp_get_theme()->get( 'Version' ),
        true
    );
} );

Render the saved value in the footer template. Keep the element present when the credit is empty so the preview script can still find it.

<span id="example-footer-credit"><?php
    echo esc_html( get_theme_mod( 'example_footer_credit', '' ) );
?></span>

Save this as assets/js/customizer-preview.js in the theme:

wp.customize('example_footer_credit', function (setting) {
    setting.bind(function (value) {
        var credit = document.getElementById('example-footer-credit');
        if (credit) {
            credit.textContent = value;
        }
    });
});

The JavaScript treats the value as text, just as the PHP template escapes it for HTML. In the Customizer, type a new credit and clear it again. Both should update without reloading the preview. Publish a normal credit and open the site outside the Customizer to check the PHP output. Finally, try an unsaved edit and close the Customizer without publishing. The live site should still show the saved credit.

If the control changes but the preview stays still, check that the script loaded inside the preview frame and that the setting and element IDs match. Setting postMessage stops the normal reload, so the handler has to do the visible work.

ClassicPress setting implementation · Customizer handbook on live preview and selective refresh

Merriment, a ClassicPress Theme

2026-11-02T12:00:00-08:00

Merriment is the Christmas theme I built for ClassicPress. A snowy header, a holly background, and evergreen and red accents give it a holiday look as soon as you activate it.

You can still choose a left sidebar, a right sidebar, or a single column. I wanted the theme to work for a regular blog that needs a seasonal look, with space for the same kinds of posts and conversations it carries the rest of the year.

View Merriment in the Luthemes portfolio.

Doing the Work No One Sees

2026-11-01T12:00:00-08:00

And whatsoever ye do, do it heartily, as to the Lord, and not unto men;

— Colossians 3:23 (KJV)

Some of the work that helps people most is easy to miss. After fixing a problem, I can take a few minutes to record which setting changed and how I tested it. The next person who runs into the issue may never know who wrote those notes, but they’ll have somewhere to start.

This verse gives me a reason to care about that last step. There’s satisfaction in leaving a task in a condition that helps someone else, even when the only visible result is a few lines in a shared document.

I think the same applies to cleaning up after a meal or putting tools back where the next person can find them. These jobs are small enough to overlook. They’re also specific places where I can pay attention and do something with care.

Introducing Novaris: An Early Look

2026-10-31T12:00:00-07:00

I’ve been working on a project called Novaris, a flat-file CMS and framework for building websites with PHP and Markdown. It’s still early in development, but I wanted to introduce it here because it’s already part of how I build this site.

My background is in making themes and working with WordPress and ClassicPress. I enjoy that work, and it has given me plenty to think about when it comes to content, templates, and the steps between writing a post and publishing it. Novaris gives me a place to explore those ideas in a project of my own.

Starting with files

The part I keep coming back to is having the content in files I can open in an editor. A post has a title, a date, and its Markdown text together in one place. I can keep it in Git, look at what changed, and move it with the rest of the site.

For a personal blog like this one, that feels like a comfortable way to work. I can write a few paragraphs, check the preview, and keep going. The templates handle how the post looks, while the content stays readable on its own.

Building it through this site

I’m using Novaris on benjlu.com, which gives me real content to work with as I develop it. A dated archive, a long tutorial, and a short poem all ask slightly different things of a theme. Having them here helps me see where the framework makes the work easier and where I still need to improve it.

The static export is another part I’m working with. It lets me turn the site into generated files that I can deploy. That gives me a reason to check the whole path from a Markdown post to the page a visitor opens, including its links, images, and stylesheets.

There’s more to work through

Novaris is still taking shape. I’m refining the code, working through rough edges, and figuring out which parts need better documentation. Using it for my own sites helps, but there’s plenty to learn about how someone else would set up a project and work with it.

For now, I want to share the process as I go. I’ll write about the decisions behind Novaris, the problems I run into, and the small improvements that make it easier to use. This introduction is a starting point for those posts, and a way to give a name to the project you’re already seeing here.

Submitting a Theme to WordPress.org

2026-10-30T12:00:00-07:00

After volunteering as a WordPress theme developer and reviewer, I think the most useful thing you can do before submitting a theme is to install the ZIP yourself on a clean site. By that point, you know every shortcut you took to get the theme running locally. A clean install helps you see what someone else will get when they download it.

1. Read the requirements before packaging

Start with the Theme Review Requirements. Check the required files and metadata for your theme type, then look through the fonts, icons, images, and libraries you ship. Keep a record of each bundled asset’s source and license. If you can’t confirm that you’re allowed to redistribute something under a compatible license, resolve that before you upload.

Look through the features as well. If a feature creates content that people should keep when they switch themes, such as a custom post type, put that functionality in a plugin. The theme can still control how the content looks.

2. Test the theme with someone else’s content

Activate the theme on a clean WordPress install and import the Theme Unit Test data. Browse a long post title, a post with no featured image, an archive page, and a page with nested comments if your theme displays them. Test the navigation at a narrow screen width and use the Tab key to check that you can see where focus goes.

Run the Theme Check plugin and investigate the results. Then go back to the pages a person will actually use. Theme Check can flag problems in the files, and a browser test can show you where a layout breaks or a menu is hard to use.

3. Build and test the ZIP

Put the installable files in a single theme folder. If your build process compiles CSS or JavaScript, make sure the compiled files are in the package and the theme points to those files. Leave local dependencies and development artifacts such as node_modules and .git out of the ZIP.

For example, if my-theme/ is a clean release folder, create the archive from its parent directory:

zip -r my-theme.zip my-theme/
unzip -l my-theme.zip

Check that my-theme/style.css is in the ZIP and that the paths match what the theme expects. Then install that exact ZIP through Appearance → Themes → Add New → Upload Theme on your test site. Activate it and repeat a few of your browser checks.

4. Upload and follow the review

Sign in to WordPress.org and submit your ZIP through the Theme Upload page. Address any errors the uploader reports. After a successful submission, follow the theme’s review ticket for feedback.

If a reviewer reports an issue, try to reproduce it first. Make the fix, increment the Version in style.css, rebuild and test the ZIP, and upload the new version through the same page. Reply on the ticket with what changed and how you tested it. A short note like “Fixed the mobile menu focus order and retested with the Tab key” gives the reviewer a specific check to repeat.

WordPress Theme Handbook submission guide · Theme update instructions

Introducing Chassis: Shared Building Blocks for My Themes

2026-10-29T12:00:00-07:00

When I’m building a theme, there are parts I want to spend time designing and parts I want to have ready to work with. The header needs to fit its content. The menu needs to open on a phone. A sidebar needs to move below the article when the screen gets narrow. Those details come up across projects.

Chassis brings that shared structure into one package for ClassicPress themes and Novaris sites. It provides compiled styles, JavaScript for navigation and code-copy buttons, and PHP helpers for common components. Each theme can set its colors, fonts, spacing, and other design choices in a chassis.json file.

Giving a theme its own look

The package includes the built CSS and JavaScript. Registering the appropriate service provider makes those assets available to the project. A theme’s design settings become CSS custom properties, so changing the header color or the space around the content can be as simple as editing JSON.

Here’s a small chassis.json example, placed in the theme’s root folder:

{
    "$schema": "https://raw.githubusercontent.com/techkodeninja/chassis/develop/schemas/chassis.schema.json",
    "color": {
        "header": {
            "background": "#1d3557",
            "text": "#ffffff"
        },
        "global": {
            "accent": "#e63946",
            "accent-text": "#ffffff"
        }
    },
    "font": {
        "heading": "Georgia, serif"
    },
    "spacing": {
        "content-padding": "l",
        "sidebar-gap": "xl"
    },
    "design": {
        "radius": "0.5rem"
    },
    "menu": {
        "toggle": "bottom-left",
        "hide-on-scroll": true
    }
}

I only need to include the values the theme changes. The schema helps an editor suggest settings, and a child theme can override individual values from its parent. Chassis also supports custom properties in the theme’s own stylesheet, loaded after the package styles.

The responsive breakpoints are fixed in the compiled package. The design file controls values such as colors, widths, and spacing that can be expressed as custom properties.

A mobile menu with room to adjust

The menu button sits at the bottom left on phones by default. A theme can move it to the bottom right or either side of the header through menu.toggle. Settings under menu.design control its background, text, border, and padding.

While scrolling down, the button hides to give the page more room. It returns when you scroll up, reach the top or bottom, open the menu, or tab to the button. Setting "hide-on-scroll": false keeps it visible.

The script also handles Escape, clicking outside the menu, and opening submenus on touch screens. Those interactions are useful to share because they need attention in every theme, regardless of its colors or typography.

Connecting ClassicPress and Novaris

For a ClassicPress theme built on Backdrop, registering the Chassis provider loads the main CSS, the ClassicPress stylesheet, the design settings, and the JavaScript. The platform stylesheet covers markup such as comments, captions, widgets, and gallery shortcodes.

On a Novaris site, the provider copies the built assets to public/assets/chassis. The theme prints them using styles() in the head and scripts() near the end of the page, with the Chassis styles before its own stylesheet. Novaris also gets button and badge template tags.

The underlying SCSS is still organized in eight numbered layers. I can use its Sass tools in custom theme partials when I need a shared spacing value or breakpoint helper.

Still taking shape

Chassis is developing quickly. I’m working toward a setup where a theme can start with the shared structure and spend more of its code on the design itself. The repository includes a theme-building guide and examples of the configuration.

There’s still verification to do. The current changelog notes that the Backdrop provider and ClassicPress stylesheet haven’t yet been tested on a live ClassicPress site, and the complete guide still needs an end-to-end walkthrough. I’ll keep refining those parts as I use the package in more projects.

Explore Chassis on GitHub · Build a theme with Chassis

Build Often, Release When Ready

2026-10-28T12:00:00-07:00

A small stylesheet tweak can be worth committing immediately even if the rest of the redesign needs another afternoon. When every commit deploys, it’s hard to save progress without also publishing it.

Give builds and releases different triggers

A push to a source branch can run the export and check that key pages and assets exist. The result tells you whether the project is ready to ship. A separate release action can publish when the whole set of changes is ready.

For a static site, the release record can be as simple as the source commit and the generated output it produced. If a problem appears later, that gives you a starting point for comparison. It also helps distinguish a successful publish to Git from a successful rollout at the hosting provider.

GitHub Actions supports starting a release workflow manually with workflow_dispatch. That gives a solo maintainer a straightforward way to choose when to go live. GitHub workflow run documentation

Starting Again After a Rough Week

2026-10-25T12:00:00-07:00

It is of the LORD’s mercies that we are not consumed, because his compassions fail not. They are new every morning: great is thy faithfulness.

— Lamentations 3:22–23 (KJV)

A rough week can make a small setback feel permanent. A plan to make time for prayer or quiet can disappear after a few late nights, and by the weekend it’s easy to wonder whether it’s worth trying again.

These words in Lamentations give me a different place to begin the morning. God’s mercy is already there when I wake up. I can open the Bible for a few minutes, say a short prayer, or make a call I’ve been putting off. Each is a real beginning.

There may still be things from last week to put right. The promise of fresh mercy gives me room to deal with them one at a time. Today’s small act of attention is something I can do even after several days when I didn’t manage it.