Dev Blogs
Adding blogs & changelogs to shortsorpants.app

Adding blogs & changelogs to shortsorpants.app (opens in a new tab)

Reed Moseng—

Why?

This is pretty meta, but I figured it would be a fitting blog post to talk about how I added blog posts to this website!

Getting it done took a bit longer than I expected, but I think it was time well spent because this was my first real foray into frontend stuff. I’ve done hardware, firmware, android, iOS, watchOS, and backend, but I’ve always been a bit intimidated by frontend and javascript in general (I’m used to languages with types). But I see how much people are able to get done in this space, and how quickly they’re able to do so, so I’m intrigued. Plus, doing new things for the first time is always the slowest, the hardest, but also the most rewarding.

And since this is my first time doing it, it’s much more of a record of my experience than it is a tutorial, so take these steps with a grain or two of 🧂.

How did we get here?

So, I originally had one mega blog post with the entire journey, but I decided to break it up. To get the whole story, check out:

  1. Building a simple API with Next.js
  2. Nextifying shortsorpants.app

Choosing a blog framework

I had my new site up and running, but I still had no way to post blogs. In my extensive checking out of the excellent Vercel Templates (opens in a new tab), I ran across a bunch of blog examples, but this one (opens in a new tab) seemed like the simplest and most official. It and a bunch of other examples used Nextra (opens in a new tab) to turn markdown into rendered blogs or docs, complete with navigation, syntax highlighting, and search. So, Nextra it is.

Choosing a Nextra template

Nextra has two templates: blog, and docs. Naturally, I started by using blog. This was the wrong choice. I quickly realized that the docs for that template were incomplete (opens in a new tab), and it supported way less customization than the docs template, so I switched over to that.

Even though docs and blogs are usually pretty different reading experiences, I realized the docs layout would actually work out great for listing and reading blogs, and also allowed a natural way for me to add Shorts or Pants documentation in the future.

Blogs -> Changelogs

This got me thinking: I don’t have any blog content yet (this was before I wrote this post), but I do have all my changelogs from past releases on GitHub, in markdown. I had been wanting to have a public changelog for a while, but wasn’t sure of the easiest and cheapest method for doing this. This was perfect. So for about the fifteenth time in this project, I switched gears.

Grabbing my release notes

First, I needed to grab all my markdown release notes from GitHub. I found this thing to help: changelog-from-release (opens in a new tab). This produced a single markdown changelog containing all my releases, including alphas and betas. I only wanted to have pages for the public releases, so I need to filter out the alphas and betas. I knew exactly what I needed to do (filter out release tags containing -alpha and -beta), but wasn’t sure how.

Filtering out alpha and beta releases

Their README mentions (opens in a new tab) how to ignore specific release tags, but substituting '^nightly$' with '^alpha$' wasn’t excluding alpha releases. I adjusted the regex to get this working (I’m not ashamed to admit, I have very rarely had to interact with regex, so I checked out a guide to make this happen). Turns out, ^ refers to the start of the string, and $ refers to the end of the string, so the pattern above wouldn’t match one of the releases I was trying to exclude (such as v1.0.2-alpha002). Instead I just wanted to filter out tags that included either -alpha or -beta, and the following did the trick:

./changelog-from-release -i ‘-(alpha|beta)’ > CHANGELOG.md

NOTE: that will only work if you have downloaded and moved the changelog-from-release (opens in a new tab) binary into the root of your repo, and have the GITHUB_TOKEN environment variable already set.

Adding individual release note pages to the site

So now I have this big markdown file with the release notes for all public releases. I just need to move the content from each release into its own .mdx file in pages/blogs (I’ll talk about Nextra config in a sec).

In moments like these, every bone in my body screams AUTOMATTEEEE THISSSSSSS!!!! (opens in a new tab), but I really didn’t want to overload this already overloaded project. I had a manageable enough number of public releases that copying and pasting would only take a few minutes, and doing it a few times manually will give me ideas about how best to automate it in the future (when I make new releases). So I transcribed over the portions of the release notes for individual releases into mdx files. And the result looked great!

Indicating the latest release and ordering the changelogs

I wanted to be able to indicate the latest release’s changelog for two reasons:

  1. It is the version you’ll get if you download Shorts or Pants (opens in a new tab) right now, and it is also the version most users are on (unless the release just dropped).
  2. I wanted to be able to link to /changelogs/latest in various places rather than hardcoding a release and having that as a dependency in the release process.

I tried a few approaches here, but I wanted one that didn’t involve editing individual release note files to indicate one to be the latest. This was because that is an easy error opportunity (could easily make a typo, forget to unmark the previously latest notes, etc). Also, it doesn’t enforce the fact that only one release note can be the latest one (it shouldn’t even be possible to mark two changelogs as the latest).

I also wanted to control the order the changelogs were displayed in the sidebar. I wanted the latest to be first, and highlighted, with the ability to go back in time in reverse chronological order all the way back to 1.0.

Nextra’s default behavior orders pages alphabetically, which is not what I want, so I landed on explicitly placing the latest changelog at the top, then a separator, then the rest of the notes in the order I wanted. Here’s the file that made that happen:

src/pages/changelogs/_meta.json
{
  "v1_6_2": "1.6.2 (Latest)",
  "---": {
    "type": "separator"
  },
  "v1_6_1": "1.6.1",
  "v1_6": "1.6",
  "v1_5": "1.5",
  "v1_4_1": "1.4.1",
  "v1_4": "1.4",
  "v1_3": "1.3",
  "v1_2": "1.2",
  "v1_1_1": "1.1.1",
  "v1_1": "1.1",
  "v1_0_3": "1.0.3",
  "v1_0_2": "1.0.2",
  "v1_0_1": "1.0.1",
  "v1_0": "1.0"
}

This does mean I need to edit this file with every release, but this could be done in a very predictable way, and easily automated.

Adding the redirect for /changelogs/latest

Now that all my changelogs were exactly where I told them to be, I needed to get that latest link working so I can put it places. I’m sure there are multiple ways to do this, but the simplest one seemed to be adding a redirect to my Next.js config. Here’s my final next.config.js, which also includes the Nextra config:

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  redirects() {
    return [
      {
        source: '/changelogs/latest',
        destination: '/changelogs/v1_6_2',
        permanent: false
      }
    ]
  }
}
 
const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx',
})
 
module.exports = withNextra(nextConfig)

(Not) preparing for automation

I ended up with three places I need to modify when adding a new release note file. Not ideal, but absolutely automatable later. For now, I added the following instructions to the README and called it a day:

  1. Add the page content as an mdx file to src/pages/changelogs. Follow the conventions of other files.
  2. Update src/pages/changelogs/_meta.json to add and indicate the latest version, and move the previous latest one down
  3. Update /changelogs/latest redirect in next.config.js

With that, I pushed to production. Check out my changelogs right here (opens in a new tab)!

Adding the first blogs

Now that I've added changelogs to my website, I can add blog support super easily. I had originally wanted to have the first blog be about recent updates to Shorts or Pants, but I realized I had just gone through this whole project and all its details were fresh in my mind. More importantly, I figured this could help out other app devs with not nearly enough time get their sites up a bit more smoothly than me. Or at the very least, document what work like this looks like!

I ended up writing three blogs about this process:

  1. Building a simple API with Next.js
  2. Nextifying shortsorpants.app
  3. Adding blogs & changelogs to shortsorpants.app (this one!)

Adding them was straightforward and very similar to adding changelogs. I just needed to add them to /blogs instead of /changelogs, and add a similar /latest redirect. I also updated the pages/_meta.json to use article-style typesetting for the blogs:

src/pages/_meta.json
{
  "blogs": {
    "title": "Dev Blogs",
    "type": "page",
    "theme": {
      "typesetting": "article"
    }
  },
  "changelogs": {
    "title": "Release Notes",
    "type": "page"
  }
}

So, I finished typing this sentence, did a bunch of proofreading, and pushed to prod!

Get Shorts or Pants for iPhone and iPad (opens in a new tab)

Sign up for the newsletter (opens in a new tab)

Thanks for reading!

Next-ifying shortsorpants.app