Restarting The Blog

In February I “restarted” my blog using Docusaurus. I like markdown a lot, and we’ve been using it for Touchlab’s open source sites. Seemed like a natural fit for the personal site. And, honestly, it was fine, but deep down I like to tinker.

In the interest of not wasting a bunch of time, I’ve adopted a goal-oriented approach to my library choices. If something is working pretty good, move on. This isn’t my natural inclination. My natural inclination is to break out the docs of everything and start poking through it. However, running a dev business for ~13 years teaches you the value of concision, at least with your tool and library evaluation choices.

In a sea of great choices, you don’t really need to try all of them. As a friend put it years ago in regards to a game we were playing “I’m [him] more of a level-clearer, you’re [me] trying to finish”.

I had not intended to personally get so involved in the web dev effort, but back in 2019 my wife decided to become a full stack developer. Through that process, being sort of an “in-house TA”, I had to learn modern web dev and react. I was not (and am still not) a fan of Javascript. Typescript is great, but only in the context of making Javascript bearable. On its own, it would be a rather strange language. We just got back from Kotlinconf, and I am very excited about the possible future of Kotlin, WASM, and the web.

Yada yada. Anyway, modern web frameworks are amazing. And there are a lot of them. That’s great, but if you feel the need to review all of them, you’ll spend a lot of time doing it. If they were very different in features and capability, reviewing them all would make sense. However, it seems like there are several great options for a lot of domains in the web world, and static web builders are no exception.

Docusaurus is great for docs. I’ve heard some folks don’t like that it’s now one big react app, so while it feels like pages are discrete pages, it’s all being handled by React. I’m not sure what’s wrong with that, but it is kind of weird. Facebook is going to Facebook.

As we rolled everything out for the OSS sites, Tadeas from the team pinged me about Astro. I’d like to say my response was, “Wow, amazing, yes”, but it was more like, “Man, Kotlinconf is in like 2 weeks, we’ve got 1000 things to do, Docusarus works, even if not perfectly, blah blah blah”. Then of course I dug into that rather than working on my talk. For a bit, anyway.

So, Docusaurus has the single page app thing. It also ships with one default theme (that I’m aware of). The web design themes we’ve been exploring all use Tailwind for CSS. While I was initially skeptical of the approach, I can’t imagine not using that for projects. Getting Tailwind and Docusaurus to work together is rather unpleasant. It would be possible to create a Docusaurus theme for Tailwind, but that’s a huge amount of work, so instead I just kind of “jiggled the handle” and got it to work.

I do think Docusaurus is very extendable while trying to not quickly degrade into “everything is custom”. I also love the default markdown layout and code display. In particular, I love the copy and wrap icons.

One thing I’m particularly happy about is styling the code to look like it’s in Intellij, except if it’s Swift code, in which case it looks like Xcode!

https://kermit.touchlab.co/docs/configuration/NON_KOTLIN

Moving over to Astro, it’s kind of a different story. Astro generates static pages, not one big app, but even goes further. You can use React (and others), but by default, that code gets rendered at build time, or possibly on a server, rather than sending it to the client to be run. That kind of blew my mind at first, and I figured it would be really strange, but actually seems to work well. You can, of course, have that code run dynamically on the client as well, if needed. It’s an interesting mix.

For a website, Astro makes a lot more sense than Docusaurus. This template here is AstroWind, which is an Astro template using Tailwind. Looks great out of the box. However, it’s not great with docs, and the markdown styling is, well, just different. By default, I’d say it’s rather “chunky”. Pleasing, but “big”. However, code is not as good. I was missing the nice bits from Docusaurus (copy/wrap), and color styling.

Here’s some Kotlin:

object DefaultFormatter:MessageStringFormatter

/**
 * Tags are a formal part of Android, but not other systems. This formatter omits them.
 */
object NoTagFormatter:MessageStringFormatter {
    override fun formatTag(tag: Tag): String = ""
    override fun formatMessage(severity: Severity?, tag: Tag?, message: Message): String = super.formatMessage(severity, null, message)
}

/**
 * Just logs the message.
 */
object SimpleFormatter: MessageStringFormatter {
    override fun formatTag(tag: Tag): String = ""
    override fun formatMessage(severity: Severity?, tag: Tag?, message: Message): String = message.message
}

I added the copy and wrap buttons. They’re not 100% “done”, but they work. I’ll tinker more later.

I didn’t quite get the code style right. It’s an interesting system/library (that I don’t want to look up just now) that uses VSCode styles. It’s a neat trick, but it’s not easy to configure and definitely not 100% (I can’t figure out why some things are italics, for example). Also, personally painful, I haven’t found a good way to style Swift differently. In Docusaurus, that was a bit of a hack. In Astro, that hack isn’t possible.

But, hey. It’s a personal blog. My highest priority was to not spend a ton of time on this, and I didn’t.

So, anyway. Web tech is pretty good. I should blog more. Here’s the fam.