How to add a changelog page to your site without building one
You shipped something. Now you want a changelog page that lists it, and the ones before it, at a URL you can send people.
The obvious move is to build one. A route, a table, some markdown, a bit of styling. Two hours, maybe three. It’s genuinely not hard, which is kind of the problem. Because it’s not hard, it never gets prioritized. Six months later, the link in your footer still goes nowhere.
There are a few ways around this. They all have tradeoffs.
Option 1: a markdown file in your repo
Create CHANGELOG.md, write entries newest first, commit it.
Cost: zero. You already have the repo.
Where it breaks: it’s for developers. The people reading a file in your repository are usually developers, and your users probably aren’t. It also doesn’t live on your marketing site, and the format naturally pushes you toward commit-level detail because that’s what a changelog file looks like.
You end up with a list of changes instead of a list of things a user would care about.
Keep it if you’re building a library. If you’re building software with a login screen, I’d look elsewhere.
Option 2: a blog category
Tag posts as “updates” and point your footer at the tag page.
Cost: near zero if you already have a blog.
Where it breaks: blog posts feel like work. A blog post feels like it needs an intro, some structure, and a point. A release note might need two sentences.
Once the two get mixed together, every update starts feeling like a writing assignment. And writing assignments get skipped.
There’s another problem too. Your actual blog posts now sit next to things like “fixed a bug in exports.” Neither one gets the attention it deserves.
This can work if you ship rarely. For a product that’s shipping every week, I’d keep the two separate.
Option 3: a hosted doc
Make a public page in a document tool, update it as you go, and link to it.
Cost: ten minutes.
Where it breaks: it doesn’t really feel like part of your product. It’s someone else’s domain, someone else’s design, and someone else’s branding. That’s probably fine for an internal document. It feels a little strange as the page you’re sending a prospect to.
It’s also easy to forget about. Anything that lives outside your normal working path tends to disappear from the routine.
Still, if you need something today, this is perfectly reasonable.
Option 4: build the page yourself
Add a route to your site. Store the entries in a database or markdown. Render them using your existing design system.
Cost: a few hours to build. Then ongoing.
Where it breaks: mostly after you’ve finished building it.
Someone has to add an editor, or you keep writing raw markdown. Someone has to deal with RSS when a user asks for it. Someone eventually has to fix the parser because a code block broke the page.
None of these things are particularly difficult. They’re just things you now have to maintain.
Build it yourself if the changelog is important enough to be part of your product experience. Otherwise, you’re probably spending time building infrastructure for something that isn’t your product.
Option 5: a hosted page plus an embed
Write the update once. It gets published to a hosted page, and the same content can appear inside your site through an embed.
Cost: minutes to set up.
Where it breaks: you depend on another service, and you may end up with a subdomain unless you configure your own.
Those are real tradeoffs. But for a small team, they’re usually less important than whether you’ll actually keep publishing.
The bigger advantage is that the same update can live in multiple places without being written multiple times.
Which one should you pick?
I’d start with one question: is the page the destination, or is it the source?
If it’s just a destination (a URL you send someone when they ask what’s new), pick whatever you’ll actually maintain. A simple page that’s updated every week is more useful than a beautiful one that’s been untouched for six months.
If the changelog is also supposed to reach existing users, things change. Now you need the same update to show up in more than one place. That’s where a hosted page plus an embed starts making more sense.
The embed is the part people underrate
A changelog page gets read by people who go looking for it. That’s mostly prospects doing some research or existing users who already know the page exists.
Most users aren’t going to visit your changelog on their own. They’re inside your product trying to get something done. If you want them to see what’s new, the update needs to reach them there.
So think of the two as separate jobs: the page is the record, and the embed is the delivery. You want both if communication with existing users is part of the goal.
Three things to get right on day one
Whatever you choose, there are a few things that are annoying to change later.
Pick a stable URL. /changelog is simple, memorable, and easy to share. Don’t put it behind a login or bury it three levels deep.
Link to it from the right places. Put it in the footer for prospects. Put it somewhere inside the product for users.
Set a minimum, not a maximum. Decide what the smallest acceptable update looks like. Two sentences and a date is enough.
The goal isn’t to create the world’s best changelog. It’s to still have one six months from now.
ReleasesHQ gives you the hosted page and the embed from one publish, plus drafts generated from your merged pull requests. The script tag is one line and mounts itself.