How do I best write articles that help readers use the Homebrewery? Well, up until now that meant opening up a new Homebrewery document, writing out some markdown and CSS, copying that into WordPress (the CodePro plugin) and uploading a screenshot of the preview pane to paste into the article to show the result.
That’s a lot of steps, but also fairly static for readers. Ideally, I could use something like an embed of Homebrewery, something like CodePen, so that readers could tinker with values right then & there.
I have long wanted to create something like a little mini-HB editor, but the difficulty and time to do so was prohibitive. Well, this past week I basically prompted my way there with Copilot/GPT:
The experience was smooth– I never really ran into an issue, just an occasional change in direction. I reviewed large parts of it, but I’m certainly no expert especially when building out the WordPress integration. The component is a Lit web component, and builds to an ES Module and WordPress plugin. It has a Storybook for documentation. It’s not currently hosted on Github or other platform, yet, but likely will be after I’ve had some time to test it.
I hope that by making it available as an ES Module and WP plugin that someone else will take it up and use it in their blogs or whatever. If you are reading this and it’s still not available on Github a week after posting this, ping me on Discord or Github and ask– I’ve likely forgot about it.
What does it do?
Well, for starters, it has the three panels: Markdown/CSS, HTML, and Preview. The key benefit over using HB directly is that you can see the relevant rendered HTML right next to your Markdown, rather than opening the browser’s Inspector and having to navigate that. Don’t get me wrong, you’ll still very likely be using that tool on the regular, but as a teaching aid it is nice to surface that HTML more concisely.
The Preview panel takes an array of stylesheets and applies them. Right now, that array is basically the “Blank” and “PHB” themes available in HB. Those two are layered (just like in HB), so you get a pretty good approximation (if not exact) of what is happening in HB. A third stylesheet called “Simplify” is optionally layered at the top, and removes some of the page padding/margin and a few other things so that the Preview doesn’t have a lot of extra whitespace we don’t care about in most instances here. If seeing a full page as it would exist in HB is necessary, the “Simplify” stylesheet can be left off by the author.
Most importantly, it’s editable by readers. So if a post author is talking about colors and has some values dropped in to the CSS editor, you can go ahead and change them to see the effect. Or change length values. Or drop in some text from your own brew and see how that effects it.
Some Examples
Let’s make a table:
It’s so easy to type in that table and show the HTML structure of the whole thing, plus the preview of it. And now you can change that 10% in the first column and see what it does. Or remove the ^ or it’s whole row, and see how it interacts of cell merging across rows.
Let’s talk images:
Yeah, URLs work, so go ahead and throw your own images into these things.
What does it not do?
Well, probably several things. But the one at top of mind is that \page doesn’t work. The editor doesn’t support breaking documents into multiple pages. Possibly it will need an option to support that in the future, for articles about page numbering or other cross-page features. But I will have to cross that bridge later.
What now?
For now I’m just going back through some old posts (mostly in the Almanac) to switch to this editor, away from CodePro + screenshots. Then I hope to start writing a bit more since this reduces the effort by quite a bit. I can imagine this will help with authoring from mobile, too, which is big. And if anyone is reading this, and the editor is not working for you or you have suggestions, find me on Github or Discord.
P.S.
I used GPT extensively to create this editor, which I know has lots of meaning. To be clear, I don’t use AI to create anything on this blog or really write anything outside of code, or to generate images. This disclaimer isn’t an attempt at being absolved, but just an FYI.