docs: add VHS-based interactive screenshot generation

.github/workflows/docspublish.yml

@@ -20,14 +20,16 @@ jobs:
         run: |
           uv --version
           uv sync --frozen --group base --group script
+      - name: Install VHS
+        uses: charmbracelet/vhs-action@v2
       - name: Update CLI screenshots
         run: |
           uv run --no-sync poe doc:screenshots
       - name: Commit and push updated CLI screenshots
         run: |
           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/cli_interactive
 
           if [[ -n "$(git status --porcelain)" ]]; then
             git commit -m "docs(cli/screenshots): update CLI screenshots" -m "[skip ci]"

docs/README.md

@@ -9,7 +9,7 @@
 [![Codecov](https://img.shields.io/codecov/c/github/commitizen-tools/commitizen.svg?style=flat-square)](https://codecov.io/gh/commitizen-tools/commitizen)
 [![prek](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json&style=flat-square&color=brightgreen)](https://github.com/j178/prek)
 
-![Using Commitizen cli](images/demo.gif)
+![Using Commitizen cli](images/cli_interactive/commit.gif)
 
 ---
 

docs/commands/commit.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-![Using Commitizen cli](../images/demo.gif)
+![Using Commitizen cli](../images/cli_interactive/commit.gif)
 
 The `commit` command provides an interactive way to create structured commits. Use either:
 

docs/commands/init.md

@@ -14,7 +14,7 @@ cz init
 
 When you run `cz init`, Commitizen will guide you through an interactive setup process:
 
-![init](../images/init.gif)
+![init](../images/cli_interactive/init.gif)
 
 ## Configuration File
 

docs/images/commit.tape

@@ -0,0 +1,116 @@
+Output cli_interactive/commit.gif
+
+Require cz
+
+# Use bash for cross-platform compatibility (macOS, Linux, Windows)
+Set Shell bash
+
+Set FontSize 16
+Set Width 878
+Set Height 568
+Set Padding 20
+Set TypingSpeed 50ms
+
+Set Theme {
+  "name": "Commitizen",
+  "black": "#232628",
+  "red": "#fc4384",
+  "green": "#b3e33b",
+  "yellow": "#ffa727",
+  "blue": "#75dff2",
+  "magenta": "#ae89fe",
+  "cyan": "#708387",
+  "white": "#d5d5d0",
+  "brightBlack": "#626566",
+  "brightRed": "#ff7fac",
+  "brightGreen": "#c8ed71",
+  "brightYellow": "#ebdf86",
+  "brightBlue": "#75dff2",
+  "brightMagenta": "#ae89fe",
+  "brightCyan": "#b1c6ca",
+  "brightWhite": "#f9f9f4",
+  "background": "#1e1e2e",
+  "foreground": "#afafaf",
+  "cursor": "#c7c7c7"
+}
+
+# Hide initial shell prompt
+Hide
+
+# Wait for terminal to be ready
+Sleep 1s
+
+# Set a clean, simple prompt (while hidden)
+Type "PS1='$ '"
+Enter
+Sleep 300ms
+
+# Create a clean temporary directory for recording
+Type "rm -rf /tmp/commitizen-demo && mkdir -p /tmp/commitizen-demo && cd /tmp/commitizen-demo"
+Enter
+Sleep 500ms
+
+# Initialize git repository
+Type "git init"
+Enter
+Sleep 500ms
+
+Type "git checkout -b awesome-feature"
+Enter
+Sleep 500ms
+
+# Create a dummy file to commit
+Type "echo 'test content' > example.py"
+Enter
+Sleep 300ms
+
+Type "git add example.py"
+Enter
+Sleep 300ms
+
+# Clear the screen to start fresh
+Type "clear"
+Enter
+Sleep 500ms
+
+# Show commands from here
+Show
+
+# Now run cz commit
+Type "cz commit"
+Sleep 500ms
+Enter
+
+# Wait for first prompt to appear
+Sleep 1s
+
+# Question 1: Select the type of change (move down to "feat")
+Down
+Sleep 500ms
+Enter
+Sleep 1s
+
+# Question 2: Scope (optional, skip)
+Enter
+Sleep 1s
+
+# Question 3: Subject
+Type "awesome new feature"
+Sleep 500ms
+Enter
+Sleep 1s
+
+# Question 4: Is this a BREAKING CHANGE? (No)
+Enter
+Sleep 1s
+
+# Question 5: Body (optional, skip)
+Enter
+Sleep 1s
+
+# Question 6: Footer (optional, skip)
+Enter
+Sleep 1s
+
+# Wait for commit success message
+Sleep 2s

docs/images/init.tape

@@ -0,0 +1,111 @@
+Output cli_interactive/init.gif
+
+Require cz
+
+# Use bash for cross-platform compatibility (macOS, Linux, Windows)
+Set Shell bash
+
+Set FontSize 16
+Set Width 878
+Set Height 568
+Set Padding 20
+Set TypingSpeed 50ms
+
+Set Theme {
+  "name": "Commitizen",
+  "black": "#232628",
+  "red": "#fc4384",
+  "green": "#b3e33b",
+  "yellow": "#ffa727",
+  "blue": "#75dff2",
+  "magenta": "#ae89fe",
+  "cyan": "#708387",
+  "white": "#d5d5d0",
+  "brightBlack": "#626566",
+  "brightRed": "#ff7fac",
+  "brightGreen": "#c8ed71",
+  "brightYellow": "#ebdf86",
+  "brightBlue": "#75dff2",
+  "brightMagenta": "#ae89fe",
+  "brightCyan": "#b1c6ca",
+  "brightWhite": "#f9f9f4",
+  "background": "#1e1e2e",
+  "foreground": "#afafaf",
+  "cursor": "#c7c7c7"
+}
+
+# Hide initial shell prompt
+Hide
+
+# Wait for terminal to be ready
+Sleep 1s
+
+# Set a clean, simple prompt
+Type "PS1='$ '"
+Enter
+Sleep 300ms
+
+
+# Create a clean temporary directory for recording
+Type "rm -rf /tmp/commitizen-example && mkdir -p /tmp/commitizen-example && cd /tmp/commitizen-example"
+Enter
+Sleep 500ms
+
+# Clear the screen to start fresh
+Type "clear"
+Enter
+Sleep 500ms
+
+# Show commands from here
+Show
+
+# Now run cz init in the clean environment
+Type "cz init"
+Sleep 500ms
+Enter
+
+# Wait for welcome message and first prompt
+Sleep 500ms
+Sleep 1s
+# Question 1: Please choose a supported config file
+# Default is .cz.toml, just press Enter
+Enter
+Sleep 1s
+
+# Question 2: Please choose a cz (commit rule)
+# Default is cz_conventional_commits, just press Enter
+Enter
+Sleep 1s
+
+# Question 3: Choose the source of the version
+# Default is "commitizen: Fetch and set version in commitizen config, just press Enter"
+Enter
+Sleep 1s
+
+# Question 4: Choose version scheme
+# Default is semver, just press Enter
+Enter
+Sleep 1s
+
+# Question 5: Please enter the correct version format
+# Default is "$version", just press Enter
+Enter
+Sleep 1s
+
+# Question 6: Create changelog automatically on bump
+# Default is Yes, just press Enter
+Enter
+Sleep 1s
+
+# Question 7: Keep major version zero (0.x) during breaking changes
+# Default is Yes, just press Enter
+Enter
+Sleep 1s
+
+# Question 8: What types of pre-commit hook you want to install?
+# Default is [commit-msg], just press Enter to accept
+Enter
+Sleep 1s
+
+# Wait for completion message
+Sleep 3s

pyproject.toml

@@ -302,7 +302,10 @@ all.help = "Run all tasks"
 all.sequence = ["format", "lint", "check-commit", "cover"]
 
 "doc:screenshots".help = "Render documentation screenshots"
-"doc:screenshots".script = "scripts.gen_cli_help_screenshots:gen_cli_help_screenshots"
+"doc:screenshots".parallel = [
+    { script = "scripts.gen_cli_help_screenshots:gen_cli_help_screenshots" },
+    { script = "scripts.gen_cli_interactive_gifs:gen_cli_interactive_gifs" },
+]
 
 "doc:build".help = "Build the documentation"
 "doc:build".cmd = "mkdocs build"

scripts/gen_cli_help_screenshots.py

@@ -37,8 +37,5 @@ def _export_cmd_as_svg(cmd: str, file_path: Path) -> None:
     print("Saved to:", file_path.as_posix())
 
 
-# TODO: generate the screenshot of cz init interactive mode
-# TODO: generate the screenshot of cz commit interactive mode
-
 if __name__ == "__main__":
     gen_cli_help_screenshots()

scripts/gen_cli_interactive_gifs.py

@@ -0,0 +1,39 @@
+import subprocess
+from pathlib import Path
+
+
+def gen_cli_interactive_gifs() -> None:
+    """Generate GIF screenshots for interactive commands using VHS."""
+    vhs_dir = Path(__file__).parent.parent / "docs" / "images"
+    output_dir = Path(__file__).parent.parent / "docs" / "images" / "cli_interactive"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    vhs_files = list(vhs_dir.glob("*.tape"))
+
+    if not vhs_files:
+        print("No VHS tape files found in docs/images/, skipping")
+        return
+
+    for vhs_file in vhs_files:
+        print(f"Processing: {vhs_file.name}")
+        try:
+            subprocess.run(
+                ["vhs", vhs_file.name],
+                check=True,
+                cwd=vhs_dir,
+            )
+            gif_name = vhs_file.stem + ".gif"
+            print(f"✓ Generated {gif_name}")
+        except FileNotFoundError:
+            print(
+                "✗ VHS is not installed. Please install it from: "
+                "https://github.com/charmbracelet/vhs"
+            )
+            raise
+        except subprocess.CalledProcessError as e:
+            print(f"✗ Error processing {vhs_file.name}: {e}")
+            raise
+
+
+if __name__ == "__main__":
+    gen_cli_interactive_gifs()