https://github.com/omachala/heroshot
Screenshot automation framework. Define once, regenerate forever. Visual picker, multi-viewport, light/dark mode, CI-ready.
https://github.com/omachala/heroshot
automation cli developer-tools documentation docusaurus mkdocs playwright screenshot technical-writing typescript vitepress
Last synced: about 1 month ago
JSON representation
Screenshot automation framework. Define once, regenerate forever. Visual picker, multi-viewport, light/dark mode, CI-ready.
- Host: GitHub
- URL: https://github.com/omachala/heroshot
- Owner: omachala
- License: mit
- Created: 2025-07-17T21:07:05.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-07T10:31:05.000Z (about 1 month ago)
- Last Synced: 2026-02-07T19:55:28.608Z (about 1 month ago)
- Topics: automation, cli, developer-tools, documentation, docusaurus, mkdocs, playwright, screenshot, technical-writing, typescript, vitepress
- Language: TypeScript
- Homepage: https://heroshot.sh
- Size: 42.9 MB
- Stars: 16
- Watchers: 0
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-nextjs - Heroshot - Screenshot automation CLI for documentation. Define screenshots once in config, regenerate all with one command using Playwright. Includes a Next.js integration. (Development Tool)
- awesome-docs - Heroshot
- awesome-vue - Heroshot - Automate documentation screenshots with Vue component integration and theme-aware output. (Components & Libraries / Dev Tools)
- fucking-awesome-vue - Heroshot - Automate documentation screenshots with Vue component integration and theme-aware output. (Components & Libraries / Dev Tools)
- awesome-technical-writing - Heroshot - Screenshot automation for documentation with a visual element picker and theme-aware output. (Useful Tools)
README
👆 This hero shot of heroshot.sh is taken by heroshot ⚡️
Your app changes constantly. New features, design tweaks, bug fixes. Meanwhile, the screenshots in your README and docs quietly become lies.
The manual fix is tedious: open browser, navigate, log in, screenshot, crop, save, commit. Now do that for every image. Now do it again next month.
**Heroshot fixes this.** Define your screenshots once - point and click, no CSS selectors - and regenerate them with one command whenever you need.
```bash
npx heroshot
```
First run opens a browser with a visual picker. Click what you want, name it, done. Screenshots land in `heroshots/`, config saves to `.heroshot/config.json`. Next run regenerates everything headlessly.
https://github.com/user-attachments/assets/f35600a6-9220-4bd2-a8c6-a6b4ee8a33d9
## Use in Your Docs
**VitePress** · [Full guide](https://heroshot.sh/docs/integrations/vitepress)
```ts
// .vitepress/config.ts
import { heroshot } from 'heroshot/plugins/vite';
export default defineConfig({ vite: { plugins: [heroshot()] } });
```
```vue
import { Heroshot } from 'heroshot/vue';
```
**Docusaurus** · [Full guide](https://heroshot.sh/docs/integrations/docusaurus)
```js
// docusaurus.config.js
plugins: [['heroshot/plugins/docusaurus', {}]];
```
```tsx
import { Heroshot } from 'heroshot/docusaurus';
;
```
**MkDocs** · [Full guide](https://heroshot.sh/docs/integrations/mkdocs)
```yaml
# mkdocs.yml
plugins:
- macros:
modules: [heroshot]
```
```jinja
{{ heroshot("dashboard", "Dashboard overview") }}
```
One component/macro, all variants - light/dark mode switches automatically, responsive sizes via srcset.
## One Screenshot - All Variants
6 screenshots from one config entry - always in sync with the live site.
## Learn More
| | |
| ------------------- | --------------------------------------------------------------------- |
| **Documentation** | [heroshot.sh](https://heroshot.sh) |
| **Getting Started** | [Quick start guide](https://heroshot.sh/docs/getting-started) |
| **Configuration** | [Config options](https://heroshot.sh/docs/config) |
| **CI/CD Setup** | [Automated updates](https://heroshot.sh/docs/guide/automated-updates) |
| **CLI Reference** | [All commands & flags](https://heroshot.sh/docs/cli) |
## Contributing
This is a community project aiming to solve screenshot automation end-to-end and any feedback is valuable. Open an [issue](https://github.com/omachala/heroshot/issues) for bugs, questions, or feature requests. Pull requests are more than welcome.
If you like it, give the repo a ⭐
## License
MIT