Same, I've added a .#screenshots derivation. High up-front effort but almost zero maintenance afterwards.
Bonus: since you're generating screenshots programmatically anyway, you can generate a pair of each with your app's light/dark theme, and swap them in/out depending on prefers-color-scheme: dark. <picture> elements work in GitHub READMEs, too: https://github.com/CyberShadow/CyDo#readme
show comments
spuz
The only problem with this idea I can forsee is that the application and therefore the screenshots can change but the documentation does not. For example, if the documentation says press "Options > Customize" but the application is updated so this becomes "Preferences > Advanced" then the screenshot will show the new text but the documentation will still show the old labels. This would be very confusing as it would be hard to correlate what is being shown on the screenshot with the text. If the user saw the old screenshot they could more easily identify that they were looking at an out of date documentation.
Having said that, have a process to automatically grab screenshots is going to make it significantly easier for a developer to update the docs so the motivation to keep the text up to date is going to be much higher.
Nashooo
Hey, you need to make your code examples horizontal scrollable on mobile! I could still guess their content based on context clues but still.
amiga386
If the author is reading this, please note your code blocks don't scroll (and in fact overflow the white text onto the white background) on mobile layouts. You need an "overflow-x: scroll" or such.
furyofantares
Very cool.
For the small casual games I've been vibe coding, I always start from a place where the application has a CLI where it can run headless, rendering to offscreen texture, with a a screenshot command as well as performance instrumentation. It takes no time to include all this, and gives the agent a way to automate the ui and inspect important things. It also lets me trivially have the agent update screenshots.
Not as neat as being part of the build process, but I will now add that.
show comments
merelysounds
This is very useful in mobile projects.
App stores require screenshots, but generating N images for NUMBER_OF_SCREEN_SIZES times NUMBER_OF_LOCALIZATIONS can be a chore.
In the past I wrote my own scripts for that, today tools like Fastlane[1] help.
I use Fastlane for my logic puzzle game Nonoverse[2], you can see sample screenshots in its App Store page.
I also automated App Preview video recording, complete with multiple scenes. If anyone wants to read more let me know, perhaps this is a good topic for an article.
Can we please agree that the OS should not send any event to applications while a screenshot is being made?
It is very annoying if you press a screenshot button and suddenly menus disappear. Or much worse, the application sends a "screenshot taken" message back to the social media platform.
show comments
LeoDaVibeci
I've needed this so many times. BTW this should be a meme: "I think this might be the neatest thing I’ve built in X that nobody will ever notice."
Mackser
Super cool! Love that you can declare the screenshots inline in the markdown document.
For my desktop app I created a solution that generates screenshots in multiple languages, light/dark mode, removes noise and adds Windows/macOS window frames.
It's currently a separate script (which is a pain to maintain). I should look into making it a part of the markdown/mdx. Thanks for the inspiration!
schneems
This is neat. I wrote https://github.com/zombocom/rundoc. It has a similar feature. The main driver is to produce tutorials so it also puts the output of commands run back in the document.
cocoto
Wouldn’t a real live render approach work in this case? Have a live preview of your tool inside a rectangle. If the tool is light it should be optimal visually: it will respect browser rendering settings like accessibility parameters or custom addons.
show comments
taspeotis
I’ve wondered about doing screenshots from the e2e test run, even keeping docs/ all together in the same repo so when you update the documentation and need a new screenshot you add a new test
maderalabs
Nice! I actually started to build this exact thing a couple years back, and ended up abstracting it out to something more generic with https://picshift.io/. That said, I still love the screenshot use case - the original name of this project was ScreenSync ;)
show comments
Biganon
You should set DEBUG=False in your Django settings.
efortis
same here, but linking to the screenshots used for pixel diffing, which get committed to the repo.
NoMethodError at /self-updating-screenshots
undefined method `name' for nil:NilClass
Ruby title-for: in handle, line 12
Web GET interblah.net/self-updating-screenshots
followed by a very detailed traceback when I try to access the page
xp84
Bravo. This is incredibly useful, and really improves the quality of documentation, especially for many applications whose design and UI are always in flux.
willm
I approve of this approach.
The docs for Textual (TUI library for Python) build screenshots along with the docs. Technically not really screenshots, they are SVGs, but principle is the same. They never get out of date.
You can get responsive design in "screenshots" with this. Super nice, and people can copy paste, look at the code (useful for dev tools), etc.
dhruv3006
This is very cool - I think I will try having this in https://voiden.md/.
show comments
ekjhgkejhgk
> Your users might not notice, but you know, and it gnaws at you.
The users WILL DEFINITELY notice if the screenshots don't match what they have in front of their eyes.
davidtio
Interesting app, definitely will reduce a lot of work updating documentation.
npodbielski
I do not know why but looking at the title I was sure that this involves something like webserver that updates static file it serves by some external webhook.
Why wouldn't you want to version the screenshots along with the text? That's a feature, not a bug.
At best, this seems to require an unpublished draft state for all automatic screenshot updates until explicitly approved so that mistakes don't leak out to everyone else.
At worst, this is an unrealistic level of discipline to keep things in sync that is far greater than just updating the docs normally with the next major version release.
My alternative suggestion would be to make sure your test suite takes screenshots with every build. They're already perfectly organized and in the context of what you're documenting.
irishcoffee
I wrote a gui app once that ran on a safety-critical platform. I ended up stuffing a rendering of the gui (rendered offscreen) into shmem at I think 24hz, and rendered that screenshot into the safety critical application. I passed clicks (no typing for this gui) back from the statically rendered image updating on a cadence, to the offscreen GUI.
Worked well. Not quite the same as this, but that’s what this reminds me of.
show comments
erikmay
Awesome!
Now you could even go a step further and add satori to the pipeline to add content to the the fresh screenshot. This way annotation could be easily added to the screenshot.
devmor
Really love this, it should be standard practice!
immanuwell
nice, embedding the capture instructions right in the markdown as comments is a dead-simple solution that'll age way better than any fancy external tooling
Xmd5a
> Then you change the UI slightly – tweak a colour, move a button, update some copy – and suddenly every screenshot that includes that element is stale. You know they’re stale. Your users might not notice, but you know, and it gnaws at you.
Same, I've added a .#screenshots derivation. High up-front effort but almost zero maintenance afterwards.
Bonus: since you're generating screenshots programmatically anyway, you can generate a pair of each with your app's light/dark theme, and swap them in/out depending on prefers-color-scheme: dark. <picture> elements work in GitHub READMEs, too: https://github.com/CyberShadow/CyDo#readme
The only problem with this idea I can forsee is that the application and therefore the screenshots can change but the documentation does not. For example, if the documentation says press "Options > Customize" but the application is updated so this becomes "Preferences > Advanced" then the screenshot will show the new text but the documentation will still show the old labels. This would be very confusing as it would be hard to correlate what is being shown on the screenshot with the text. If the user saw the old screenshot they could more easily identify that they were looking at an out of date documentation.
Having said that, have a process to automatically grab screenshots is going to make it significantly easier for a developer to update the docs so the motivation to keep the text up to date is going to be much higher.
Hey, you need to make your code examples horizontal scrollable on mobile! I could still guess their content based on context clues but still.
If the author is reading this, please note your code blocks don't scroll (and in fact overflow the white text onto the white background) on mobile layouts. You need an "overflow-x: scroll" or such.
Very cool.
For the small casual games I've been vibe coding, I always start from a place where the application has a CLI where it can run headless, rendering to offscreen texture, with a a screenshot command as well as performance instrumentation. It takes no time to include all this, and gives the agent a way to automate the ui and inspect important things. It also lets me trivially have the agent update screenshots.
Not as neat as being part of the build process, but I will now add that.
This is very useful in mobile projects.
App stores require screenshots, but generating N images for NUMBER_OF_SCREEN_SIZES times NUMBER_OF_LOCALIZATIONS can be a chore.
In the past I wrote my own scripts for that, today tools like Fastlane[1] help.
I use Fastlane for my logic puzzle game Nonoverse[2], you can see sample screenshots in its App Store page.
I also automated App Preview video recording, complete with multiple scenes. If anyone wants to read more let me know, perhaps this is a good topic for an article.
[1]: https://fastlane.tools/
[2]: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
Speaking of screenshots.
Can we please agree that the OS should not send any event to applications while a screenshot is being made?
It is very annoying if you press a screenshot button and suddenly menus disappear. Or much worse, the application sends a "screenshot taken" message back to the social media platform.
I've needed this so many times. BTW this should be a meme: "I think this might be the neatest thing I’ve built in X that nobody will ever notice."
Super cool! Love that you can declare the screenshots inline in the markdown document.
For my desktop app I created a solution that generates screenshots in multiple languages, light/dark mode, removes noise and adds Windows/macOS window frames.
Wrote about it here: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
It's currently a separate script (which is a pain to maintain). I should look into making it a part of the markdown/mdx. Thanks for the inspiration!
This is neat. I wrote https://github.com/zombocom/rundoc. It has a similar feature. The main driver is to produce tutorials so it also puts the output of commands run back in the document.
Wouldn’t a real live render approach work in this case? Have a live preview of your tool inside a rectangle. If the tool is light it should be optimal visually: it will respect browser rendering settings like accessibility parameters or custom addons.
I’ve wondered about doing screenshots from the e2e test run, even keeping docs/ all together in the same repo so when you update the documentation and need a new screenshot you add a new test
Nice! I actually started to build this exact thing a couple years back, and ended up abstracting it out to something more generic with https://picshift.io/. That said, I still love the screenshot use case - the original name of this project was ScreenSync ;)
You should set DEBUG=False in your Django settings.
same here, but linking to the screenshots used for pixel diffing, which get committed to the repo.
https://github.com/ericfortis/mockaton/tree/main/pixaton-tes...
I'm sometimes getting
NoMethodError at /self-updating-screenshots undefined method `name' for nil:NilClass
Ruby title-for: in handle, line 12 Web GET interblah.net/self-updating-screenshots
followed by a very detailed traceback when I try to access the page
Bravo. This is incredibly useful, and really improves the quality of documentation, especially for many applications whose design and UI are always in flux.
I approve of this approach.
The docs for Textual (TUI library for Python) build screenshots along with the docs. Technically not really screenshots, they are SVGs, but principle is the same. They never get out of date.
https://textual.textualize.io/widgets/markdown/#example
Plus we had a visual diff on the top of that as a part of the CI pipeline. It prevented a bunch of mishaps ;)
I maintain an internal wiki, the contents were generated by each CI/CD and always reflects from latest running code.
Site appears to be down intermittently with a Django error
If author sees this: Turn off Django debug mode
For web projects, consider not doing screenshots at all and just embedding the html: https://kodare.net/2025/01/14/iframes-not-screenshots.html
You can get responsive design in "screenshots" with this. Super nice, and people can copy paste, look at the code (useful for dev tools), etc.
This is very cool - I think I will try having this in https://voiden.md/.
> Your users might not notice, but you know, and it gnaws at you.
The users WILL DEFINITELY notice if the screenshots don't match what they have in front of their eyes.
Interesting app, definitely will reduce a lot of work updating documentation.
I do not know why but looking at the title I was sure that this involves something like webserver that updates static file it serves by some external webhook.
shot-scraper is another project in this vein.
https://github.com/simonw/shot-scraper
Why wouldn't you want to version the screenshots along with the text? That's a feature, not a bug.
At best, this seems to require an unpublished draft state for all automatic screenshot updates until explicitly approved so that mistakes don't leak out to everyone else.
At worst, this is an unrealistic level of discipline to keep things in sync that is far greater than just updating the docs normally with the next major version release.
My alternative suggestion would be to make sure your test suite takes screenshots with every build. They're already perfectly organized and in the context of what you're documenting.
I wrote a gui app once that ran on a safety-critical platform. I ended up stuffing a rendering of the gui (rendered offscreen) into shmem at I think 24hz, and rendered that screenshot into the safety critical application. I passed clicks (no typing for this gui) back from the statically rendered image updating on a cadence, to the offscreen GUI.
Worked well. Not quite the same as this, but that’s what this reminds me of.
Awesome! Now you could even go a step further and add satori to the pipeline to add content to the the fresh screenshot. This way annotation could be easily added to the screenshot.
Really love this, it should be standard practice!
nice, embedding the capture instructions right in the markdown as comments is a dead-simple solution that'll age way better than any fancy external tooling
> Then you change the UI slightly – tweak a colour, move a button, update some copy – and suddenly every screenshot that includes that element is stale. You know they’re stale. Your users might not notice, but you know, and it gnaws at you.
F
Related: Sabotaging projects by overthinking, scope creep, and structural diffing – https://news.ycombinator.com/item?id=47890799