diff --git a/website/docs/guides/configuration.md b/website/docs/guides/configuration.md new file mode 100644 index 0000000..4ca2e2b --- /dev/null +++ b/website/docs/guides/configuration.md @@ -0,0 +1,170 @@ +--- +sidebar_position: 5 +title: Configuration +--- + +# Configuration + +Betamax supports configuration at multiple levels: CLI flags, `@set` directives in keys files, project config files, global config, and named presets. Settings are resolved in a strict precedence chain so you always know which value wins. + +## Precedence + +When the same setting is specified in multiple places, the highest-priority source wins: + +``` +CLI flags > @set directives > .betamaxrc > global config > preset > defaults +``` + +Once a value is set by a higher-priority source, lower-priority sources cannot override it. + +## Config File Format + +All config files use the same `key=value` format. Lines starting with `#` are comments. Blank lines are ignored. + +```bash +# Example config +theme=dracula +window-bar=colorful +border-radius=12 +margin=20 +padding=10 +shadow=true +``` + +### Available Keys + +| Key | Description | Example | +|-----|-------------|---------| +| `theme` | Color theme name | `dracula` | +| `preset` | Load a named preset | `polished` | +| `window-bar` | Window bar style | `colorful` | +| `bar-color` | Bar background color | `#1e1e1e` | +| `bar-height` | Bar height in pixels | `30` | +| `border-radius` | Corner radius in pixels | `12` | +| `margin` | Outer margin in pixels | `20` | +| `margin-color` | Margin background color | `#000000` | +| `padding` | Inner padding in pixels | `10` | +| `padding-color` | Padding background color | `#1e1e1e` | +| `shadow` | Enable drop shadow | `true` | +| `shadow-blur` | Shadow blur radius (0-100) | `15` | +| `shadow-offset-x` | Horizontal shadow offset (-200 to 200) | `0` | +| `shadow-offset-y` | Vertical shadow offset (-200 to 200) | `8` | +| `shadow-opacity` | Shadow opacity (0.0-1.0) | `0.4` | +| `shadow-color` | Shadow color | `#000000` | +| `output-dir` | Output directory for captures | `./captures` | + +:::note +Config file keys use **hyphens** (e.g. `bar-color`), while `@set` directives in keys files use **underscores** (e.g. `@set:bar_color:1e1e1e`). +::: + +## Project Config (`.betamaxrc`) + +Place a `.betamaxrc` file in your project to share settings across all keys files in that directory tree. + +Betamax searches for `.betamaxrc` starting from the current directory and walking upward. It stops when it finds the file or reaches a `.git` directory (the repository root). + +``` +my-project/ + .git/ + .betamaxrc # <-- found here + docs/ + demos/ + intro.keys # uses .betamaxrc from project root +``` + +Example `.betamaxrc`: + +```bash +# Project-wide defaults +theme=catppuccin-mocha +window-bar=colorful +border-radius=10 +margin=20 +padding=8 +shadow=true +output-dir=./docs/img +``` + +## Global Config + +A global config applies to all betamax invocations on your machine. It is loaded after `.betamaxrc`, so project settings take priority. + +**Location:** `~/.config/betamax/config` + +The path respects `XDG_CONFIG_HOME` if set: + +``` +${XDG_CONFIG_HOME:-$HOME/.config}/betamax/config +``` + +Example global config: + +```bash +# Personal defaults +theme=nord +shadow=true +shadow-blur=20 +``` + +## Presets + +Presets are named config files stored in a central location. Use them to switch between different styling profiles without editing project config. + +**Location:** `~/.config/betamax/presets/.conf` + +Create a preset: + +```bash +mkdir -p ~/.config/betamax/presets + +cat > ~/.config/betamax/presets/polished.conf << 'EOF' +window-bar=colorful +border-radius=12 +margin=30 +padding=10 +shadow=true +shadow-blur=20 +shadow-opacity=0.5 +EOF +``` + +Use a preset via CLI: + +```bash +betamax myapp -f demo.keys --preset polished +``` + +Or in `.betamaxrc`: + +```bash +preset=polished +``` + +Or in a keys file: + +``` +@set:theme:dracula +# preset is loaded from .betamaxrc or CLI +``` + +Presets are loaded after `.betamaxrc` and global config, so they fill in any values not already set. If a preset is not found, betamax prints a warning and continues. + +## Config Discovery Flow + +The full resolution order for a setting like `margin`: + +1. **CLI flag** `--margin 30` -- highest priority +2. **@set directive** `@set:margin:30` in the keys file +3. **`.betamaxrc`** `margin=30` in the nearest project config +4. **Global config** `margin=30` in `~/.config/betamax/config` +5. **Preset** `margin=30` in the loaded preset file +6. **Built-in default** `0` + +At each level, a value is only applied if it hasn't already been set by a higher-priority source. + +## See Also + +- [CLI Reference](/docs/cli-reference) - All command-line flags +- [Keys File Format](/docs/keys-file-format) - `@set` directive reference +- [Styling Options](/docs/guides/styling-options) - Visual customization guide +- [Themes](/docs/themes) - Built-in color themes diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md new file mode 100644 index 0000000..17a2809 --- /dev/null +++ b/website/docs/guides/troubleshooting.md @@ -0,0 +1,259 @@ +--- +sidebar_position: 6 +title: Troubleshooting +--- + +# Troubleshooting + +Common issues and how to resolve them. + +## Missing Dependencies + +Betamax checks for required tools at startup. If something is missing, you'll see a clear error. + +### Required + +| Tool | Purpose | Install (macOS) | Install (Linux) | +|------|---------|-----------------|-----------------| +| `tmux` | Headless terminal sessions | `brew install tmux` | `apt install tmux` | +| `bc` | Timing calculations | `brew install bc` | `apt install bc` | +| `python3` | Recording and GIF generation | Included with macOS | `apt install python3` | + +### Optional + +| Tool | Purpose | Install (macOS) | Install (Linux) | +|------|---------|-----------------|-----------------| +| `termshot` | PNG screenshots | `brew install homeport/tap/termshot` | See [termshot repo](https://github.com/homeport/termshot) | +| `aha` | HTML output | `brew install aha` | `apt install aha` | +| `ffmpeg` | GIF recording | `brew install ffmpeg` | `apt install ffmpeg` | +| `Pillow` | Decoration rendering | `pip install Pillow` | `pip install Pillow` | + +**Error examples:** + +``` +Error: bc is required for betamax timing calculations + Install with: brew install bc (macOS) or apt install bc (Linux) +``` + +``` +Error: termshot required for GIF recording +Error: ffmpeg required for GIF recording +``` + +You can also use `@require` in keys files to check for dependencies before execution: + +``` +@require:jq +@require:curl +``` + +If a required command is missing: + +``` +Error: Missing required commands: jq curl +``` + +## Validation Errors + +Betamax validates keys files before execution and reports errors with line numbers. You can also validate without running: + +```bash +betamax --validate-only myapp -f demo.keys +``` + +### Common Validation Errors + +**Missing values:** +``` +Error: Missing value for cols (line 3: @set:cols:) +``` + +**Invalid types:** +``` +Error: Invalid integer for delay: abc (line 5: @set:delay:abc) +Error: Invalid speed value: fast (must be numeric) (line 7: @set:speed:fast) +``` + +**Out of range:** +``` +Error: Speed must be between 0.25 and 4.0 (got: 10) +Error: shadow_blur must be 0-100 (got: 200) +Error: shadow_opacity must be 0.0-1.0 (got: 2.5) +``` + +**Invalid colors:** +``` +Error: Invalid color format for bar_color: red (expected RRGGBB or #RRGGBB) +``` + +**Unknown settings:** +``` +Error: Unknown setting: colour +``` + +**Unknown themes:** +``` +Error: Unknown theme: darkula (use: dracula, catppuccin-mocha, gruvbox-dark, nord, ...) +``` + +### Typo Detection + +Betamax suggests corrections for misspelled directives: + +``` +Warning: Unknown directive @slep (did you mean @sleep?) +Warning: Unknown directive @import (did you mean @source?) +``` + +## @source Import Errors + +The `@source` directive imports keys from other files. Several things can go wrong: + +**File not found:** +``` +Error: @source file not found: ./common/setup.keys + Referenced from: demo.keys +``` + +**Circular imports:** +``` +Error: Circular @source detected + File: /path/to/a.keys + Import chain: + -> /path/to/a.keys + -> /path/to/b.keys + -> /path/to/a.keys (circular) +``` + +**Depth limit exceeded (max 10 levels):** +``` +Error: @source depth limit exceeded (10 levels) + Circular import? Check: /path/to/deep.keys +``` + +Source paths are resolved relative to the file containing the `@source` directive. + +## @repeat Structure Errors + +``` +Error: Missing repeat count (line 5: @repeat) +Error: Invalid repeat count: abc (line 5: @repeat:abc) +Error: Repeat count must be positive (line 5: @repeat:0) +Error: Nested @repeat not supported (line 8: @repeat:3) +Error: @end without matching @repeat (line 10: @end) +Error: @repeat on line 5 has no matching @end (line 5: @repeat:3) +``` + +Betamax does not support nested `@repeat` blocks. To repeat nested sequences, use `@source` to import a file that contains its own `@repeat`. + +## tmux Session Issues + +### Orphaned Sessions + +If betamax is interrupted (e.g. `kill -9`), tmux sessions may be left running. Betamax uses an isolated tmux socket named `betamax`. + +**List orphaned sessions:** +```bash +tmux -L betamax list-sessions +``` + +**Kill all betamax sessions:** +```bash +tmux -L betamax kill-server +``` + +**Kill a specific session:** +```bash +tmux -L betamax kill-session -t betamax +``` + +### Session Already Exists + +Betamax kills any existing session with the same name before starting a new one. If you use custom session names (`-s`), ensure they don't conflict with other betamax runs. + +### Inspecting Sessions + +Use `--keep` / `-k` to keep the tmux session alive after betamax finishes: + +```bash +betamax -k myapp -f demo.keys +``` + +Attach to inspect: + +```bash +tmux -L betamax attach -t betamax +``` + +## Signal Handling + +Pressing `Ctrl+C` during betamax execution sends SIGINT. Betamax runs with `set -e`, so this will terminate the script. The tmux session should be cleaned up, but if it isn't, see [Orphaned Sessions](#orphaned-sessions) above. + +## GIF Recording Issues + +### No Frames Captured + +``` +Error: No frames captured +``` + +This means `@record:start` was used but no `@frame` directives (or `@sleep` with capture) generated any frames before `@record:stop`. Ensure your keys file includes timing and content between the record start and stop. + +### GIF Creation Failed + +``` +Error: Failed to create GIF +``` + +Check that `ffmpeg` is installed and working. Also verify that `termshot` is available for capturing individual frames. + +### GIF Filename + +``` +Error: Missing GIF filename for @record:stop +Error: GIF filename must end with .gif +``` + +The `@record:stop` directive requires a filename: `@record:stop:output.gif` + +## Platform Notes + +### macOS + +- Dependencies are available via Homebrew +- The default shell is zsh; use `--shell /bin/bash` if your keys file assumes bash +- `bc` is included with macOS by default + +### Linux + +- Install dependencies via your package manager (`apt`, `dnf`, `pacman`, etc.) +- Ensure your terminal supports truecolor (24-bit color) for accurate theme rendering +- If running in a headless environment (CI), tmux works without a display since it runs its own terminal + +### Truecolor Support + +Themes and color options require a terminal that supports truecolor (24-bit RGB). Most modern terminals do. To test: + +```bash +printf "\x1b[38;2;255;100;0mTruecolor test\x1b[0m\n" +``` + +If you see orange text, your terminal supports truecolor. + +## Timeout Errors + +``` +Error: Timeout waiting for pattern 'Ready' +``` + +The `--wait` / `-w` pattern wasn't found within the timeout period (default: 30 seconds). Solutions: + +- Increase the timeout: `--timeout 60` +- Verify the pattern matches what the application actually prints +- Check that the application starts correctly in tmux + +## See Also + +- [Getting Started](/docs/intro) - Installation and prerequisites +- [CLI Reference](/docs/cli-reference) - All command-line options +- [Keys File Format](/docs/keys-file-format) - Directive syntax reference diff --git a/website/docs/themes.md b/website/docs/themes.md new file mode 100644 index 0000000..63d441d --- /dev/null +++ b/website/docs/themes.md @@ -0,0 +1,143 @@ +--- +sidebar_position: 5 +title: Themes +--- + +# Themes + +Betamax includes 31 built-in color themes for styling GIF and PNG decorations (window bar, padding, margin). Themes set colors for the decorative areas around your terminal content -- the terminal content itself uses your termshot color palette. + +## Using Themes + +**CLI flag:** +```bash +betamax myapp -f demo.keys --theme dracula +``` + +**@set directive in a keys file:** +``` +@set:theme:catppuccin-mocha +``` + +**Config file (`.betamaxrc` or global config):** +```bash +theme=nord +``` + +### Overriding Theme Colors + +Explicit color settings take precedence over theme values. Set a theme for base colors, then override individual properties: + +``` +@set:theme:dracula +@set:bar_color:ff0000 +@set:margin:20 +``` + +This applies Dracula's padding and margin colors but uses a custom red bar color. + +## Dark Themes + +### Catppuccin + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `catppuccin-mocha` | `#1e1e2e` | `#1e1e2e` | `#11111b` | +| `catppuccin-macchiato` | `#24273a` | `#24273a` | `#181926` | +| `catppuccin-frappe` | `#303446` | `#303446` | `#232634` | + +### Gruvbox + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `gruvbox-dark` | `#282828` | `#282828` | `#1d2021` | + +### Tokyo Night + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `tokyo-night` | `#1a1b26` | `#1a1b26` | `#13141c` | +| `tokyo-night-storm` | `#24283b` | `#24283b` | `#1a1e2e` | + +### Solarized + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `solarized-dark` | `#002b36` | `#002b36` | `#001e26` | + +### Rose Pine + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `rose-pine` | `#191724` | `#191724` | `#12101a` | +| `rose-pine-moon` | `#232136` | `#232136` | `#1a1829` | + +### Everforest + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `everforest-dark` | `#2d353b` | `#2d353b` | `#232a2e` | + +### GitHub + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `github-dark` | `#0d1117` | `#0d1117` | `#010409` | +| `github-dark-dimmed` | `#22272e` | `#22272e` | `#1c2128` | + +### Ayu + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `ayu-dark` | `#0a0e14` | `#0a0e14` | `#050709` | +| `ayu-mirage` | `#1f2430` | `#1f2430` | `#171b24` | + +### Material + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `material` | `#263238` | `#263238` | `#1a2327` | +| `material-darker` | `#212121` | `#212121` | `#171717` | + +### Other Dark Themes + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `dracula` | `#282a36` | `#282a36` | `#1e1f29` | +| `nord` | `#2e3440` | `#2e3440` | `#242933` | +| `one-dark` | `#282c34` | `#282c34` | `#1e2127` | +| `monokai` | `#272822` | `#272822` | `#1e1f1c` | +| `kanagawa` | `#1f1f28` | `#1f1f28` | `#16161d` | +| `night-owl` | `#011627` | `#011627` | `#00101c` | +| `palenight` | `#292d3e` | `#292d3e` | `#1e212e` | +| `synthwave-84` | `#262335` | `#262335` | `#1a1726` | +| `cyberpunk` | `#000b1e` | `#000b1e` | `#000714` | + +## Light Themes + +| Theme | Bar | Padding | Margin | +|-------|-----|---------|--------| +| `catppuccin-latte` | `#eff1f5` | `#eff1f5` | `#dce0e8` | +| `gruvbox-light` | `#fbf1c7` | `#fbf1c7` | `#f2e5bc` | +| `solarized-light` | `#fdf6e3` | `#fdf6e3` | `#eee8d5` | +| `github-light` | `#ffffff` | `#ffffff` | `#f6f8fa` | +| `rose-pine-dawn` | `#faf4ed` | `#faf4ed` | `#f2e9e1` | +| `everforest-light` | `#fdf6e3` | `#fdf6e3` | `#f3ead3` | + +## Theme Properties + +Each theme sets three decoration colors: + +| Property | Description | +|----------|-------------| +| **Bar** (`bar_color`) | Window bar background color | +| **Padding** (`padding_color`) | Inner padding area around terminal content | +| **Margin** (`margin_color`) | Outer margin area (slightly darker/lighter than padding for depth) | + +Theme names are case-insensitive. Underscores and hyphens are interchangeable (`catppuccin_mocha` and `catppuccin-mocha` both work). + +## See Also + +- [Styling Options](/docs/guides/styling-options) - Window bars, shadows, padding, and more +- [Configuration](/docs/guides/configuration) - Config file locations and precedence +- [CLI Reference](/docs/cli-reference) - `--theme` flag and all options