Posting here, start to finish
Here’s the whole process of publishing a post on this blog now, comment section included.
I write the post, a markdown file with some front matter, same as any Hugo blog.
I run one command scripts/companion-thread content/weblog/posting-here-start-to-finish.md --space blogging with POPSICLEBOAT_TOKEN exported in my shell, it creates a discussion thread for the post over on Popsicle Boat and writes the thread’s URL back into the file. That’s the entire integration.
I push, Netlify builds the site, and the post goes up with a “Discuss this post” link at the bottom.
The part I like is what readers get. The replies don’t live in an iframe and don’t load from a script. When the site builds, it fetches the public replies from the thread and bakes them into the page as plain HTML with no JavaScript, no tracker, no third-party anything running on your machine. The conversation is just part of the page.
The page also keeps itself current. When someone replies, Popsicle Boat waits a couple of minutes. So a burst of replies becomes one build instead of five. It then pings my build hook. Netlify rebuilds, and the reply is sitting on the page about three minutes after it was written.
If a comment thread ever goes away, your page quietly drops the comments callout.
What it took to set up, once #
None of the above is the setup. The setup happened once, and it was three things.
1 - A token. The command talks to Popsicle Boat with a personal access token. I run the service, so I mint mine on the server: fly ssh console -a popsicleboat -C "sh -c 'cd /app && MIX_ENV=prod mix popsicleboat.create_api_token jake \"blog\"'". If you wanted one for your blog, I’d issue it to you. It’s shown once, you export it in your shell, and that’s the last time you think about it.
2 - A script. companion-thread is about a hundred lines of Python sitting in my blog’s repo. All it does is call one API endpoint with the post’s title and URL, then paste the thread URL it gets back into the front matter.
3 - A build hook. I pasted my Netlify build-hook URL into my Popsicle Boat profile. That’s the whole “keeps itself current” trick! Netlify, Vercel, and Cloudflare Pages all take the same ping, so pretty much any static host works.
I wrote earlier about getting this from ~5 steps down to about 2, at least after the initial setup: The token, the build hook, and the script to wire a new post with the URL. After that, you write, a script writes the thread’s URL into the front matter of the post. This is what those steps buy: write, push. The comments handle themselves.
Caveat: This is what works for my (this) blog. The command for updating the Hugo front matter is specific to mine. But once the instrumentation is in place, it’s a really pleasing and clean process to post a new entry (like this one) with comments baked in.
The setup for other blogs is laid out on popsicleboat.com/comments.
