A better-looking, faster, searchable website (in many steps of varying degrees of difficulty)
After an afternoon of work a month or two ago to prove to myself that converting a Next.js-powered Tailwind UI template to a WordPress theme wouldn’t cause me deep and intense regret, it was just a matter of finding the hours to power through and build it. And here we are! A lot has changed:
Generator improvements
I always felt there should be a multi-step process walking through the generator options, and now there is! I think this is the most important user-facing change, and one that should help people who wouldn’t otherwise set up things like their theme slug or function prefix to choose ones that will make their lives easier.
While the original _tw website used Alpine.js for some interactivity, I’ve really gone all-in on Alpine since then. The new generator dialog uses Alpine’s corresponding headless component, and Alpine also powers things like the placeholders that update dependent on the values entered earlier in the form.
I also created JavaScript versions of the PHP functions that convert the theme name to a slug so that the form could preview the slug and function prefix in real time and exactly as they’ll appear in the theme, for all of you using accents, apostrophes and the like in your theme names.
On using Tailwind UI, again
The original _tw website used Tailwind UI components for its design, and those components look dramatically different today compared to several years ago; an overhaul was long overdue.
But Tailwind UI has also begun releasing website templates, some of which I’ve really liked. When they released Syntax, I saw in it everything from my mental roadmap for the _tw documentation section. Syntax’s landing page lists the template as being powered by these technologies:
- Next.js
- Tailwind CSS
- Headless UI
- React
- Markdoc
- TypeScript
Of the technologies on that list, the only one I knew I could support in a WordPress theme was Tailwind itself. But I really liked how it looked and worked! And sometimes that’s enough to press forward.
Converting a Next.js-powered Tailwind UI theme to WordPress
I got the template running locally, and then I began copying chunks of HTML into a WordPress theme. Things moved more quickly than I expected, right up to the point I needed to create the highlight-on-scroll on-page navigation. Without anything I could lean on from the template code, I built some functionality—forced IDs for all headings, creation of the two-level menu tree—directly into the WordPress theme. The rest was built using Alpine, with the on-page navigation of the Alpine docs themselves serving as inspiration and a rough starting point.
That left two elements of the Next.js template that would require new tools: search, and the ability to navigate between documentation pages without resetting the location of the scrollable navigation sidebar.
Enter Algolia…
From past experience building search-as-you-type functionality, Algolia felt like the easiest lift. WebDevStudios’ Algolia plugin for WordPress is great, and I’ve customized it enough in the past that I wouldn’t be starting from scratch.
On some projects I’ve used that plugin only for the indexing side, creating a custom JavaScript front end rather than use theirs. In this case, I valued getting this site online sooner over going custom. But should I ever feel the need to gold plate some connectors, there are connectors here that could be a bit shinier.
…and also Turbo
Turbo is part of Hotwired, replacing Turbolinks, which is no longer maintained. If you’ve never used either, it provides a more single-page-app–like experience to websites that aren’t single page apps (which turns out to be a helpful thing when you’re trying to make a WordPress theme feel like a website that uses Next.js).
Without any customization, Turbo makes site navigation feel significantly faster by updating the DOM to match that of the next page to which a visitor navigates rather than doing a full page load.
But it can go further than that, only updating a subset of the DOM. This solved the problem I described above—the ability to navigate between documentation pages without resetting the location of the scrollable navigation sidebar—by letting me target the content of the documentation page, leaving the rest of the page untouched, scroll position included.
Switching to Rank Math
I’ve been using Yoast’s SEO plugin for years, but I’ve grown frustrated with the lack of first-class block editor support (as represented by the metabox panel that loads at the bottom of the editor like a vestigial structure from the classic theme days). I probably would have stayed the course due to inertia alone, but this thread from Seth Rubenstein echoed what I was feeling and gave me the permission I didn’t know I needed to switch to Rank Math.
And it was really easy! No further notes.
Trying to make WATT Stack happen
For the last year or so I’ve remained committed to WordPress and Tailwind as the core of my approach to building sites, but I’ve also increasingly gone all-in on Alpine and Turbo. In the second half of this year, I’d like to write more about the benefits I’ve found in using all four together (and some of the hiccups I’ve encountered along the way).
And that’s it for now! Getting this done has been blocking everything else I’ve wanted to work on for so long that I’m excited to see what I’ll be able to get done now that I can work on other things.