docs: add VHS-based interactive screenshot generation #1862

HankyStyle · 2026-02-09T18:03:24Z

Description

This PR adds support for generating interactive GIF screenshots for cz init and cz commit commands using VHS (Video Home System), a tool for generating terminal GIFs from code.

Why VHS?

VHS is a modern tool for generating terminal recordings as GIFs.
Benefits:

Reproducible: Tape files ensure consistent output
Version-controlled: Configuration is code
Cross-platform: Works on macOS, Linux, and Windows

Checklist

I have read the contributing guidelines

Was generative AI tooling used to co-author this PR?

Yes (antigravity + Claude Sonnect 4.5)

Code Changes

Add test cases to all the changes you introduce
Run uv run poe all locally to ensure this change passes linter check and tests
Manually test the changes:
- Verify the feature/bug fix works as expected in real-world scenarios
  - Tested python scripts/gen_cli_help_screenshots.py locally
  - Verified both init.gif and commit.gif are generated correctly
- Test edge cases and error conditions
  - Tested with missing VHS installation (proper error message)
  - Tested with missing tape files (proper warning message)
- Ensure backward compatibility is maintained
  - Existing gen_cli_help_screenshots() function unchanged
- Document any manual testing steps performed
  - See "Steps to Test This Pull Request" section below
Update the documentation for the changes

Expected Behavior

Local Generation: Running python scripts/gen_cli_help_screenshots.py should generate:
- 11 SVG files in docs/images/cli_help/ (CLI help screenshots)
- docs/images/init.gif (interactive demo of cz init)
- docs/images/commit.gif (interactive demo of cz commit)
CI/CD: When documentation workflow runs:
- VHS is installed automatically
- GIF screenshots are generated alongside SVG screenshots
- Both file types are committed to the repository

Steps to Test This Pull Request

Prerequisites

# Install VHS
brew install vhs  # macOS
# or follow: https://github.com/charmbracelet/vhs#installation

Local Testing

# 1. Checkout this branch
git checkout feat/interactive-screenshots

# 2. Run the screenshot generation script
python scripts/gen_cli_help_screenshots.py

# 3. Verify generated files
ls -lh docs/images/*.gif
open docs/images/init.gif
open docs/images/commit.gif

Additional Context

codecov · 2026-02-09T18:04:38Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.98%. Comparing base (dd972c9) to head (64cce9e).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1862   +/-   ##
=======================================
  Coverage   97.98%   97.98%           
=======================================
  Files          60       60           
  Lines        2686     2686           
=======================================
  Hits         2632     2632           
  Misses         54       54

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

HankyStyle · 2026-02-09T18:05:49Z

lol. I found that I can't edit this PR title name after I created it.
Please help me change it to feat(docs): add VHS-based interactive screenshot generation or other better naming.

Lee-W · 2026-02-10T03:24:50Z

not really a feat (at least not to commitizen itself), so I changed it to docs

bearomorphism · 2026-02-10T14:50:46Z

lol. I found that I can't edit this PR title name after I created it. Please help me change it to feat(docs): add VHS-based interactive screenshot generation or other better naming.

I heard from my friend that some github preview features have so terrible UI that people cannot find where to edit the PR title.

bearomorphism

Thank you for your contribution of this great documentation improvement! The new gifs look beautiful!

Nothing is really blocking this PR but the comments related to demo.gif.

bearomorphism · 2026-02-10T14:57:59Z

docs/images/commit.gif

Please replace all occurrences of demo.gif in the docs with this and remove demo.gif.

Maybe put all vhs generated file under some dedicated folder, for example, docs/images/vhs/, and put all *.tape files outside images/ directory since they are just data for generating the .gif files.

bearomorphism · 2026-02-10T15:05:38Z

.github/workflows/docspublish.yml

          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          git add docs/images/cli_help
+          git add docs/images/cli_help docs/images/*.gif


We can put all files generated by the command in a dedicated folder.

bearomorphism · 2026-02-10T15:06:19Z

docs/images/commit.tape

+# VHS documentation https://github.com/charmbracelet/vhs
+#
+# Output:
+#   Output <path>.gif               Create a GIF output at the given <path>
+
+#
+# Settings:
+#   Set FontSize <number>           Set the font size of the terminal
+#   Set FontFamily <string>         Set the font family of the terminal
+#   Set Height <number>             Set the height of the terminal
+#   Set Width <number>              Set the width of the terminal
+#   Set LetterSpacing <float>       Set the letter spacing of the terminal
+#   Set LineHeight <float>          Set the line height of the terminal
+#   Set Theme <json|string>         Set the theme of the terminal
+#   Set Padding <number>            Set the padding of the terminal
+#   Set TypingSpeed <time>          Set the typing speed of the terminal
+


I think we don't need these comments?

bearomorphism · 2026-02-10T15:06:47Z

docs/images/init.tape

+# VHS documentation https://github.com/charmbracelet/vhs
+#
+# Output:
+#   Output <path>.gif               Create a GIF output at the given <path>
+
+#
+# Settings:
+#   Set FontSize <number>           Set the font size of the terminal
+#   Set FontFamily <string>         Set the font family of the terminal
+#   Set Height <number>             Set the height of the terminal
+#   Set Width <number>              Set the width of the terminal
+#   Set LetterSpacing <float>       Set the letter spacing of the terminal
+#   Set LineHeight <float>          Set the line height of the terminal
+#   Set Theme <json|string>         Set the theme of the terminal
+#   Set Padding <number>            Set the padding of the terminal
+#   Set TypingSpeed <time>          Set the typing speed of the terminal
+


bearomorphism · 2026-02-10T15:10:30Z

scripts/gen_cli_help_screenshots.py

+    """Generate GIF screenshots for interactive commands using VHS."""
+    images_root = Path(__file__).parent.parent / "docs" / "images"
+
+    vhs_files = ["init.tape", "commit.tape"]


Instead of hard-coding the tape files, we can just list all *.tape files under the dedicated folder and process them. Also, we don't need to check the existence of vhs_path in the following for loop if we use this approach.

Or we can just write a shell script in docspublish.yml

For example,

vhs docs/images/*.tape

(not sure if the above script works, but you probably know what I mean)

bearomorphism · 2026-02-10T15:13:02Z

scripts/gen_cli_help_screenshots.py

+
+    for vhs_file in vhs_files:
+        vhs_path = images_root / vhs_file
+        if vhs_path.exists():


is_file() should be used if you want to check whether a file exists

bearomorphism · 2026-02-10T15:15:23Z

scripts/gen_cli_help_screenshots.py

Either rename this file or make your change a separate script. I prefer to make it a separate script.

bearomorphism · 2026-02-10T15:22:27Z

As a follow up, this can also be used to regenerate bump.gif, which can be in a separate PR

HankyStyle added 4 commits February 10, 2026 01:09

docs: add VHS tape for cz init interactive demo

858386a

docs: add VHS tape for cz commit interactive demo

b7a8604

ci(gen_cli_help_screenshots): add gen_interactive_screenshots function

73dd4e1

ci(workflow): add VHS support to documentation workflow

64cce9e

HankyStyle requested review from Lee-W, noirbizarre and woile as code owners February 9, 2026 18:03

github-actions bot added pr-status: wait-for-review type: feature A new enhacement proposal labels Feb 9, 2026

Lee-W changed the title ~~Feat/interactive screenshots~~ docs: add VHS-based interactive screenshot generation Feb 10, 2026

Lee-W approved these changes Feb 10, 2026

View reviewed changes

bearomorphism self-requested a review February 10, 2026 15:02

bearomorphism reviewed Feb 10, 2026

View reviewed changes

Uh oh!

docs: add VHS-based interactive screenshot generation #1862

Are you sure you want to change the base?

docs: add VHS-based interactive screenshot generation #1862

Conversation

HankyStyle commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Why VHS?

Checklist

Was generative AI tooling used to co-author this PR?

Code Changes

Expected Behavior

Steps to Test This Pull Request

Prerequisites

Local Testing

Additional Context

Uh oh!

codecov bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

HankyStyle commented Feb 9, 2026

Uh oh!

Lee-W commented Feb 10, 2026

Uh oh!

bearomorphism commented Feb 10, 2026

Uh oh!

bearomorphism left a comment

Choose a reason for hiding this comment

Uh oh!

bearomorphism Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

bearomorphism Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

bearomorphism Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bearomorphism Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

bearomorphism Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bearomorphism Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

bearomorphism Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

bearomorphism Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

bearomorphism commented Feb 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

HankyStyle commented Feb 9, 2026 •

edited

Loading

codecov bot commented Feb 9, 2026 •

edited

Loading

bearomorphism Feb 10, 2026 •

edited

Loading

bearomorphism Feb 10, 2026 •

edited

Loading