GoKawiilI think this might be the neatest thing I’ve built in Jelly that nobody will ever notice.
If you’ve ever maintained a help centre or documentation site for a web application, you’ll know the particular misery of screenshots. You write a lovely help article, carefully capture a screenshot of the feature you’re documenting, crop it, maybe add a border and a shadow, upload it, and it looks great. 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.
Or maybe that’s just me.
Either way, I decided to fix it. The help centre in Jelly has a build system where screenshots are captured automatically from the running application, and they update themselves whenever you rebuild.
Markdown with a twist
The help articles are written in Markdown, which gets processed into HTML via Redcarpet and then rendered as ERB views in the Rails app. So far, so ordinary. But scattered through the Markdown are comments like this:
<!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section --> 
That HTML comment is an instruction to the screenshot system. It says: “go to the inbox page for the Acme Tools demo team, find the element matching #inbox-brand-new-section , and capture a screenshot of it.” The image tag below it is where the result ends up.
How it works
Under the hood, it’s a Rake task that fires up a headless Chrome browser via Capybara and Cuprite. It scans every Markdown file for those SCREENSHOT comments, groups them by team (so it only needs to log in once per team), navigates to each URL, and captures the screenshot.
... continue reading