Markdown comments drive auto-captured screenshots in Rails help docs

A developer building Jelly solved the chronic problem of stale documentation screenshots by embedding capture instructions directly into Markdown source files. Special HTML comments specify a target URL, capture mode (element, full page, or viewport), and a CSS selector, which a Rake task then executes against the running app via headless Chrome through Capybara and Cuprite. Options like click, wait, crop, and hide handle interactive states like popovers and dismiss noise like dev toolbars.

A single command, rails manual:build, regenerates every screenshot and rebuilds the help pages as ERB views with breadcrumbs and navigation derived from the Markdown sources. Because docs and code live in the same repo, UI changes and their documentation can ship in the same commit, and screenshots never silently drift out of sync with the product.

The author notes that handling edge cases — scrolling, animation timing, cropping out irrelevant regions — was the bulk of the work, but the resulting drop in friction means the help centre now gets updated far more often than when each screenshot required manual capture and cropping.