This system automatically captures and caches CLI command outputs in MDX files, converting them to SVG format for consistent rendering.
- Configure
ansi-run.jsonwith your example project path and starting commit hash:
{
"exampleProjectPath": "/path/to/example/project",
"startingHash": "initial-commit-hash",
"config": {
"cacheDir": "content/cache",
"outputFormat": "svg"
}
}- Install dependencies:
pnpm installUse special cli code blocks in your MDX files:
Here's how to check status:
```cli
but status
```The output will be automatically captured and cached.
### Restore Commands
To restore to a specific state before running commands, add a restore comment:
```mdx
{/* restore [commit-hash] */}
```cli
but status
This will run but restore [commit-hash] before executing the cli command.
### Updating CLI Outputs
Run the update script to process all MDX files and update CLI outputs:
```bash
pnpm update-cli
This will:
- Read your
ansi-run.jsonconfiguration - Change to your example project directory
- Restore to the starting hash
- Process all MDX files in
content/docs/ - Execute CLI commands and capture outputs
- Convert outputs to SVG using ansi2html
- Cache outputs in
content/cache/[hash].svg - Update MDX files with hash references: ```cli [hash]
- Report any changes detected
- Processing: The script finds all ````cli` blocks in MDX files
- Execution: Commands are run in your configured example project
- Caching: Output is converted to SVG and stored with a content hash
- Updates: MDX blocks are updated with hash references
- Rendering: The CliBlock component renders cached SVGs or shows placeholders
├── ansi-run.json # Configuration
├── content/
│ ├── cache/ # Cached SVG outputs
│ │ ├── abc123def456.svg
│ │ └── def789ghi012.svg
│ └── docs/ # MDX documentation files
│ └── commands/
│ └── status.mdx
├── scripts/
│ └── update-cli-outputs.js # Main processing script
└── app/
└── components/
├── CliBlock.tsx # Rendering component
└── remark-cli.ts # MDX transformer
- Create a new MDX file with CLI commands:
# Status Command
Check your workspace status:
```cli
but status
```
2. Run the update script:
```bash
pnpm update-cli
- The script will show output like:
Processing: content/docs/commands/status.mdx
Found CLI command: but status
New CLI block found: but status
Updated: content/docs/commands/status.mdx
- Your MDX file is now updated:
# Status Command
Check your workspace status:
```cli [abc123def456]
but status
```
5. When rendered, users see the actual command output in SVG format.
## Troubleshooting
- **Missing outputs**: Run `pnpm update-cli` to generate missing cache files
- **Outdated outputs**: The script will detect hash changes and notify you
- **Command failures**: Failed commands will still be cached to show error output
- **Path issues**: Ensure your `ansi-run.json` paths are absolute and correct
### Updating CLI Outputs
Run the update script to process all MDX files and update CLI outputs:
```bash
export CLICOLOR_FORCE=1
export GIT_AUTHOR_DATE="2020-09-09 09:06:03 +0800"
export GIT_COMMITTER_DATE="2020-10-09 09:06:03 +0800"
export NO_BG_TASKS=1
git config gitbutler.testing.changeId 42
pnpm update-cli
The command "man pages" are copied from ../gitbutler/cli-docs so that changes to the commands docs can be included in changes with the code.
To update the command man-pages, you can run:
pnpm update-manpagesYou can also simply run ansi-senor <command> and ansi-senor will output an html file that you can copy to the public/cli-examples/ directory and reference in a doc with this syntax:
but setup