built with ☕

Stencil, Markdown, and web components in Markdown

I’ve had an idea floating around for a while: MDX is great, but I hate all of the steps around configuring / building React components with it. If I’m writing Markdown, HTML is valid in Markdown, and Web Components are valid HTML, so why not just stick Web Components in Markdown and call it a day?

That was the idea, anyway, I just never got around to trying it. I still don’t quite grok the actual Web Components spec, but I have used Stencil, and figured with some free time today I’d give it a shot. This is the result: Web Components in Markdown. It works! Of course it does. Probably the biggest difference between it and MDX (besides, React, obviously), is that Web Components in HTML can only accept string values, so in this example rather than passing an array of image sources, I passed a comma separated list, e.g:

<picture-gallery images="https://source.unsplash.com/lvh5L46VWuA/600x600, https://source.unsplash.com/TjbedCFPQdc/600x600, https://source.unsplash.com/caM2RdHVAoc/600x600"></picture-gallery>

One other nice thing here is you can stick fallback HTML into the <picture-gallery> part, and you get fallback content. If the JS loads, yay, a gallery. If not, whatever. I made an example of that here:

You can see the code behind the site on Github, it’s slap-dash but it is functional.

Rush - ing a repo

Some notes on moving an existing Git repository into a Rush monorepo structure:

• The last monorepo setup I did was with Lerna. I much prefer the documentation and incredibly verbose configuration files of Rush. Lerna certainly has it’s place in specific setups but not the one I was trying to set up.
• One point that wasn’t clear: if you have an existing repo you want to add rush to, you have to initialize it with rush init --overwrite-existing. Minor point but the error message from just running rush init didn’t make it clear that I should, and the documentation is a little vague on what --overwrite-existing is going to do (and it sounds worse than it is).
• I used their suggestion of creating a package structure two levels deep. In this case /apps/[appname] and /tools/[toolname]. We’ll likely add a /libraries down the line, and migrate some more apps over.

Seems like a decent tool, so far. The requirements here are low, I’m not trying to create an omni-repo of all of our back and front-end projects, just colocating some already related pieces of code in a happy way, and setting up a future state so more projects can become more closely related in the future.

From Netlify CMS to Forestry

I’ve used Netlify CMS on and off on this site (and previous iterations of it) and while I think it’s a really great idea, the execution of the application is incredibly lacking, for a few reason:

• The documentation is… not good. It’s ok, and I’m always hesitant to complain about documentation too much given how often I’ve dealt with software that included absolutely zero public documentation, but if I have to dig through Github issues to find answers to configuration problems that’s not a project I would be quick to recommend.

• Running the admin panel locally is annoyingly hard. This has been fixed in later releases but still feels clunky.

• You have to configure all of your fields in a YAML file, then commit them, then go make changes to the content. If you’re like me and you just move code and content independently this creates a lot of mismatched fields and inconsistency. That’s a me thing, but I don’t think it’s uncommon if you’re working with all of your content in Markdown files.

• Sorting never seemed to work, and all of my files were ordered somewhat randomly when I opened the CMS.

• Folders, in content and in the media library, didn’t really work either. I like to store my posts by year/month/title.md to cut down on how many I have to look at at once, and Netlify CMS just makes them one big list.

To be clear, the very good idea behind Netlify CMS is that it is a light UI wrapper around your Markdown files, and it requires zero installation. You put a script tag on a static page and it does the rest. There’s no database, no deployment steps, you can directly edit the YAML front matter and Markdown content of your files and commit the changes to Git, at which point if you have a static site and Netlify hooked up, everything deploys and your site is updated. For a while there wasn’t a lot of good options in this market, but now there’s a few, so I started looking at alternatives this weekend. Among the interesting options:

• Typemill - A CMS for Micro Publishing | Typemill

• Pico - A stupidly simple, blazing fast, flat file CMS.

• Grav - A Modern Flat-File CMS | Grav CMS

But all of those started with “download” or “get started by installing”. Then I found Forestry.io, which runs the UI on their servers (headless, the kids call it), but against your Github content. Getting started was similar to setting up a site on Netlify, you connect your Github account, pick the repo, pick the default branch. After that you give forestry some config settings (which it saves in a .forestry folder in the repo) and your content, assuming you already have some, sort of magically appears. You can then configure your media library (which, annoyingly, also doesn’t use folders but at least saves correctly to folders if you configure it to), and you can use existing content to build out a reusable front matter structure. I picked one of my “album a day” posts and forestry did (most of) this for me:

(I added the Draft field after, since the post I picked didn’t have that in the front matter already).

forestry also has a bundle of other options I don’t yet need but I’ve needed on past projects that are nice:

• It can run a preview version of the site so you can see changes in real time.

• Webhooks.

• User roles (once you go to a paid tier).

In general I recommend it, and editors like this are easy to recommend because they require almost no setup, and if you change your mind, you just go back to whatever other Markdown editing process you were using.

CDNs Aren’t as Useful as They Used to Be

When I was learning to be a web developer it was beaten into my head that if you were building a site and loading 3rd party scripts on it (e.g. jQuery, Bootstrap), you should load them from a CDN because if a user on your site had been to another site that used jQuery (likely) and they used the same version of jQuery (somewhat likely), and that other site also used the same CDN for jQuery (i.e. https://code.jquery.com/, which was pretty likely given we didn’t have as many widely available CDNs back then), then the browser would pull the version of jQuery you were requesting from the cache instead of downloading it again. Everyone wins! Except the first site to request jQuery that a user hit with an empty cache.

I’d gone on assuming that was functionally true but I needed it less and less as the sites I built started using npm packages and bundling everything at build time instead of requesting resources at run time. I thought it was true somewhat recently, when I decided we could load Google fonts from Google instead of bundling them because “if the user has it in the cache…”. But today I learned it’s not true at all:

If your sites request the global jQuery, modules from unpkg.com, font files from Google fonts or GA's (Google Analytics) analytics.js, users will redownload the resources no matter if they downloaded and cached them for other sites already.

What does this change mean for you? If your sites live on modern hosting that provides a CDN and supports HTTP/2, you can drop the third-parties and should ship all resources yourself. Relying on a third-party provides little value in 2020.

In fact it hasn’t been true in Safari for a long time (since 2013), but as of October 2020 it doesn’t work in Chrome either. It maybe never really worked like we dreamed it did, comments on Hacker News imply actual cache hits were very low. I chose to believe there was a golden age of a long lived minor version of jQuery that got heavily pulled from cache hits, but maybe I chose to believe that just so this little nugget in my brain wasn’t useless all along.

My Favorite Apple Watch App

An Album A Day

I think creating a new, active habit, one that requires time and attention, that you intend to do every day, is basically impossible. It requires either dropping an existing habit, or finding the kind of free time you only get after committing a crime, at which point the habits and hobbies you are allowed decrease considerably.

A new passive habit, that I’m game for. I’ve found myself in a rut musically lately, listening to the same songs and playlists on repeat way too often. To change that, I’m going to start a list of albums to listen to that are new to me, and listen to one a day. Since I make web-things and can’t not make a web-thing for something like this, I made a calendar for you to follow along at home. There’s no reviews or ratings or anything like that, just new music for my ears.

New about page

I’ve been lazy about putting a new about page on this site, because I wanted to make it look better than the plain text wall I had in the last design. I decided since I’m sitting at my home desk almost always these days, I’d make an interactive version for you to play along with.

So check it out, a new about page. It’s SVGs, HTML, CSS, and 3 teeny tiny JPEGs. The bigger your monitor, the more you can see. If you figure out how to get yourself on one of the screens, let me know.

Fuck Donald Trump

Days after, or even the day of the 2017 inauguration, I was in North Station and someone was singing just the chorus of “FDT” over and over.

That’s been in my head a lot for the last four years. I’m not sure it will ever leave, but maybe the mental play count drops a bit after today.

I’m still a tiny bit optimistic that four years of fuckery has engaged a lot of people in the Democratic process who weren’t before. I’m very, very, slightly hopeful that people finding channels outside of main stream media eventually swings towards hearing unheard voices, not amplifying the loudest and worst. If I can be glad for one little thing today, it’s seeing the President wearing a mask, because this never needed to be as difficult as it is.

Who uses Safari

I’ve saved this screenshot for the next time I need to have a debate about dropping older browser support. It’s from My PlayStation, and the browser is Safari (desktop and mobile!). Literally no way to view your account on an iOS device without downloading the app. Some light Google-ing says there’s over 100 million people with Playstation accounts so it’s unlikely I’m the only person annoyed by this.

Finding is better than folding

I was reading this thread on Reddit about how to structure your React files. In the past I would have said something like:

components/
	layout/
		component_name
	data/
		component_name
	other_domain/
		component_name
	...

and used an index.js in every folder for the root React component. These days I’m much more inclined to do:

components/
	component_name

because I find both deeply nested folders and files with the same name annoying. I also think it’s ideal if you can quickly move through files with linked structures (F12 in VS Code if you’re using Typescript) or search for files using the Command Palette rather than trying to guess from / down where a file might be.