From 081dce6184c7d11776c1fb0f2cf426d254700639 Mon Sep 17 00:00:00 2001 From: Scott Chacon Date: Mon, 3 Nov 2025 12:20:17 +0100 Subject: [PATCH] cli documentation Add class to CLI output container and remove pre vertical padding t --- CLI-DOCS.md | 164 + app/(docs)/[[...slug]]/page.tsx | 2 + app/components/CliBlock.tsx | 63 + app/components/ResizableIframe.tsx | 22 + app/components/remark-cli.ts | 69 + app/global.css | 17 + cli-examples-run.json | 10 + .../cli-tutorial/branching-and-commiting.mdx | 244 + .../cli-tutorial/editing-commits.mdx | 41 + .../initializing-a-repository.mdx | 26 + .../docs/cli-guides/cli-tutorial/meta.json | 12 + .../cli-tutorial/operations-log.mdx | 28 + .../docs/cli-guides/cli-tutorial/rubbing.mdx | 182 + .../cli-tutorial/tutorial-overview.mdx | 22 + .../cli-tutorial/updating-the-base.mdx | 88 + content/docs/cli-guides/installation.mdx | 32 + content/docs/cli-guides/meta.json | 8 + content/docs/commands/but-base.mdx | 51 + content/docs/commands/but-branch.mdx | 124 + content/docs/commands/but-commit.mdx | 53 + content/docs/commands/but-describe.mdx | 41 + content/docs/commands/but-forge.mdx | 64 + content/docs/commands/but-init.mdx | 33 + content/docs/commands/but-mark.mdx | 46 + content/docs/commands/but-mcp.mdx | 38 + content/docs/commands/but-new.mdx | 33 + content/docs/commands/but-oplog.mdx | 43 + content/docs/commands/but-publish.mdx | 64 + content/docs/commands/but-push.mdx | 115 + content/docs/commands/but-restore.mdx | 48 + content/docs/commands/but-rub.mdx | 67 + content/docs/commands/but-snapshot.mdx | 43 + content/docs/commands/but-status.mdx | 67 + content/docs/commands/but-undo.mdx | 32 + content/docs/commands/but-unmark.mdx | 30 + content/docs/commands/groups.json | 35 + content/docs/commands/meta.json | 31 + content/docs/meta.json | 5 +- package.json | 5 +- pnpm-lock.yaml | 39 +- public/cache/cli-output/0000fdfa2b5ec92b.html | 30 + public/cache/cli-output/01f7bcfe8175a154.html | 24 + public/cache/cli-output/03420f08f4e2df55.html | 28 + public/cache/cli-output/06337d5a688f418c.html | 41 + public/cache/cli-output/194379d8cf135c2d.html | 51 + public/cache/cli-output/1de5d82a8ddf7ce1.html | 30 + public/cache/cli-output/1df4a75e976dd98d.html | 41 + public/cache/cli-output/1eccbe4db529d72f.html | 34 + public/cache/cli-output/22fb3e53f7ffdf99.html | 26 + public/cache/cli-output/24b3331a2def26d5.html | 38 + public/cache/cli-output/24f5456cca204e8d.html | 38 + public/cache/cli-output/278d679c366756a7.html | 20 + public/cache/cli-output/2f4817399ff46441.html | 51 + public/cache/cli-output/500825cb80f612de.html | 730 +++ public/cache/cli-output/50aed1645949b06d.html | 38 + public/cache/cli-output/577ab5c5f0035947.html | 24 + public/cache/cli-output/61a4ed332fc62e70.html | 45 + public/cache/cli-output/682139bab4bdc57d.html | 24 + public/cache/cli-output/69330060f4f79ec5.html | 39 + public/cache/cli-output/6e0c1402c16f5f6d.html | 51 + public/cache/cli-output/6fad05e228ab9095.html | 38 + public/cache/cli-output/711027350744cca1.html | 24 + public/cache/cli-output/79a511563972cc8f.html | 24 + public/cache/cli-output/8350792b8d9d13f6.html | 39 + public/cache/cli-output/85004f4877113a64.html | 24 + public/cache/cli-output/860ebbd1902dc6d4.html | 24 + public/cache/cli-output/8b9c7d07db297441.html | 24 + public/cache/cli-output/8df04f3225dfabd3.html | 24 + public/cache/cli-output/8e0965d4ad557bc8.html | 31 + public/cache/cli-output/8ee36a00318dadf8.html | 38 + public/cache/cli-output/9184aa27f8f241fd.html | 24 + public/cache/cli-output/927c817ed73b68c7.html | 24 + public/cache/cli-output/95763a83f458be55.html | 26 + public/cache/cli-output/9d97a568b3786b14.html | 33 + public/cache/cli-output/a52570b3640e3743.html | 24 + public/cache/cli-output/a7d718a609ef2081.html | 20 + public/cache/cli-output/b5b56bebb89dedc3.html | 35 + public/cache/cli-output/bbbd3383f636a9b4.html | 41 + public/cache/cli-output/bd4f40610e40f1b5.html | 24 + public/cache/cli-output/bfafb0a0ab77bc27.html | 52 + public/cache/cli-output/c197f357f5e62892.html | 24 + public/cache/cli-output/d5ab704c72c309c6.html | 39 + public/cache/cli-output/d68eac2e6f9222fb.html | 35 + public/cache/cli-output/d80e33b45a9aaf22.html | 24 + public/cache/cli-output/d82bd6f8faa2d86e.html | 38 + public/cache/cli-output/de43f2edf09f5070.html | 41 + public/cache/cli-output/de923765534564a6.html | 24 + public/cache/cli-output/e9ed409178fbcced.html | 32 + public/cache/cli-output/f2990f43c97b0a13.html | 26 + public/cache/cli-output/f2a12b1e97a21933.html | 20 + public/cache/cli-output/f3c56e67a1e24971.html | 42 + public/cache/cli-output/f53ff654c67d268e.html | 41 + public/cache/cli-output/f7e1c84e128c0e56.html | 35 + public/cache/cli-output/f93e374ac2785a90.html | 34 + .../cli-output/tmp-9d45d3b700cc0d9a.html | 4824 +++++++++++++++++ public/cli-examples/but-st-c43eb45a.html | 33 + public/llms-full.txt | 4246 +++++++++++---- scripts/sync-commands.sh | 140 + scripts/update-cli-outputs.js | 429 ++ source.config.ts | 3 +- tailwind.config.js | 17 + 101 files changed, 13092 insertions(+), 1188 deletions(-) create mode 100644 CLI-DOCS.md create mode 100644 app/components/CliBlock.tsx create mode 100644 app/components/ResizableIframe.tsx create mode 100644 app/components/remark-cli.ts create mode 100644 cli-examples-run.json create mode 100644 content/docs/cli-guides/cli-tutorial/branching-and-commiting.mdx create mode 100644 content/docs/cli-guides/cli-tutorial/editing-commits.mdx create mode 100644 content/docs/cli-guides/cli-tutorial/initializing-a-repository.mdx create mode 100644 content/docs/cli-guides/cli-tutorial/meta.json create mode 100644 content/docs/cli-guides/cli-tutorial/operations-log.mdx create mode 100644 content/docs/cli-guides/cli-tutorial/rubbing.mdx create mode 100644 content/docs/cli-guides/cli-tutorial/tutorial-overview.mdx create mode 100644 content/docs/cli-guides/cli-tutorial/updating-the-base.mdx create mode 100644 content/docs/cli-guides/installation.mdx create mode 100644 content/docs/cli-guides/meta.json create mode 100644 content/docs/commands/but-base.mdx create mode 100644 content/docs/commands/but-branch.mdx create mode 100644 content/docs/commands/but-commit.mdx create mode 100644 content/docs/commands/but-describe.mdx create mode 100644 content/docs/commands/but-forge.mdx create mode 100644 content/docs/commands/but-init.mdx create mode 100644 content/docs/commands/but-mark.mdx create mode 100644 content/docs/commands/but-mcp.mdx create mode 100644 content/docs/commands/but-new.mdx create mode 100644 content/docs/commands/but-oplog.mdx create mode 100644 content/docs/commands/but-publish.mdx create mode 100644 content/docs/commands/but-push.mdx create mode 100644 content/docs/commands/but-restore.mdx create mode 100644 content/docs/commands/but-rub.mdx create mode 100644 content/docs/commands/but-snapshot.mdx create mode 100644 content/docs/commands/but-status.mdx create mode 100644 content/docs/commands/but-undo.mdx create mode 100644 content/docs/commands/but-unmark.mdx create mode 100644 content/docs/commands/groups.json create mode 100644 content/docs/commands/meta.json create mode 100644 public/cache/cli-output/0000fdfa2b5ec92b.html create mode 100644 public/cache/cli-output/01f7bcfe8175a154.html create mode 100644 public/cache/cli-output/03420f08f4e2df55.html create mode 100644 public/cache/cli-output/06337d5a688f418c.html create mode 100644 public/cache/cli-output/194379d8cf135c2d.html create mode 100644 public/cache/cli-output/1de5d82a8ddf7ce1.html create mode 100644 public/cache/cli-output/1df4a75e976dd98d.html create mode 100644 public/cache/cli-output/1eccbe4db529d72f.html create mode 100644 public/cache/cli-output/22fb3e53f7ffdf99.html create mode 100644 public/cache/cli-output/24b3331a2def26d5.html create mode 100644 public/cache/cli-output/24f5456cca204e8d.html create mode 100644 public/cache/cli-output/278d679c366756a7.html create mode 100644 public/cache/cli-output/2f4817399ff46441.html create mode 100644 public/cache/cli-output/500825cb80f612de.html create mode 100644 public/cache/cli-output/50aed1645949b06d.html create mode 100644 public/cache/cli-output/577ab5c5f0035947.html create mode 100644 public/cache/cli-output/61a4ed332fc62e70.html create mode 100644 public/cache/cli-output/682139bab4bdc57d.html create mode 100644 public/cache/cli-output/69330060f4f79ec5.html create mode 100644 public/cache/cli-output/6e0c1402c16f5f6d.html create mode 100644 public/cache/cli-output/6fad05e228ab9095.html create mode 100644 public/cache/cli-output/711027350744cca1.html create mode 100644 public/cache/cli-output/79a511563972cc8f.html create mode 100644 public/cache/cli-output/8350792b8d9d13f6.html create mode 100644 public/cache/cli-output/85004f4877113a64.html create mode 100644 public/cache/cli-output/860ebbd1902dc6d4.html create mode 100644 public/cache/cli-output/8b9c7d07db297441.html create mode 100644 public/cache/cli-output/8df04f3225dfabd3.html create mode 100644 public/cache/cli-output/8e0965d4ad557bc8.html create mode 100644 public/cache/cli-output/8ee36a00318dadf8.html create mode 100644 public/cache/cli-output/9184aa27f8f241fd.html create mode 100644 public/cache/cli-output/927c817ed73b68c7.html create mode 100644 public/cache/cli-output/95763a83f458be55.html create mode 100644 public/cache/cli-output/9d97a568b3786b14.html create mode 100644 public/cache/cli-output/a52570b3640e3743.html create mode 100644 public/cache/cli-output/a7d718a609ef2081.html create mode 100644 public/cache/cli-output/b5b56bebb89dedc3.html create mode 100644 public/cache/cli-output/bbbd3383f636a9b4.html create mode 100644 public/cache/cli-output/bd4f40610e40f1b5.html create mode 100644 public/cache/cli-output/bfafb0a0ab77bc27.html create mode 100644 public/cache/cli-output/c197f357f5e62892.html create mode 100644 public/cache/cli-output/d5ab704c72c309c6.html create mode 100644 public/cache/cli-output/d68eac2e6f9222fb.html create mode 100644 public/cache/cli-output/d80e33b45a9aaf22.html create mode 100644 public/cache/cli-output/d82bd6f8faa2d86e.html create mode 100644 public/cache/cli-output/de43f2edf09f5070.html create mode 100644 public/cache/cli-output/de923765534564a6.html create mode 100644 public/cache/cli-output/e9ed409178fbcced.html create mode 100644 public/cache/cli-output/f2990f43c97b0a13.html create mode 100644 public/cache/cli-output/f2a12b1e97a21933.html create mode 100644 public/cache/cli-output/f3c56e67a1e24971.html create mode 100644 public/cache/cli-output/f53ff654c67d268e.html create mode 100644 public/cache/cli-output/f7e1c84e128c0e56.html create mode 100644 public/cache/cli-output/f93e374ac2785a90.html create mode 100644 public/cache/cli-output/tmp-9d45d3b700cc0d9a.html create mode 100644 public/cli-examples/but-st-c43eb45a.html create mode 100755 scripts/sync-commands.sh create mode 100644 scripts/update-cli-outputs.js diff --git a/CLI-DOCS.md b/CLI-DOCS.md new file mode 100644 index 0000000..1f667b4 --- /dev/null +++ b/CLI-DOCS.md @@ -0,0 +1,164 @@ +# CLI Output Management System + +This system automatically captures and caches CLI command outputs in MDX files, converting them to SVG format for consistent rendering. + +## Setup + +1. Configure `ansi-run.json` with your example project path and starting commit hash: + +```json +{ + "exampleProjectPath": "/path/to/example/project", + "startingHash": "initial-commit-hash", + "config": { + "cacheDir": "content/cache", + "outputFormat": "svg" + } +} +``` + +2. Install dependencies: +```bash +pnpm install +``` + +## Usage + +### Adding CLI Commands to MDX + +Use special `cli` code blocks in your MDX files: + +```mdx +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.json` configuration +- 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 + +### How It Works + +1. **Processing**: The script finds all ````cli` blocks in MDX files +2. **Execution**: Commands are run in your configured example project +3. **Caching**: Output is converted to SVG and stored with a content hash +4. **Updates**: MDX blocks are updated with hash references +5. **Rendering**: The CliBlock component renders cached SVGs or shows placeholders + +### File Structure + +``` +├── 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 +``` + +### Example Workflow + +1. Create a new MDX file with CLI commands: +```mdx +# Status Command + +Check your workspace status: + +```cli +but status +``` +``` + +2. Run the update script: +```bash +pnpm update-cli +``` + +3. 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 +``` + +4. Your MDX file is now updated: +```mdx +# 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" +pnpm update-cli +``` + +## Commands + +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 ./scripts/sync-commands.sh + + diff --git a/app/(docs)/[[...slug]]/page.tsx b/app/(docs)/[[...slug]]/page.tsx index 5d509ae..9955b5e 100644 --- a/app/(docs)/[[...slug]]/page.tsx +++ b/app/(docs)/[[...slug]]/page.tsx @@ -8,6 +8,7 @@ import { Callout } from "fumadocs-ui/components/callout" import { TypeTable } from "fumadocs-ui/components/type-table" import { Accordion, Accordions } from "fumadocs-ui/components/accordion" import ImageSection from "@/app/components/ImageSection" +import CliBlock from "@/app/components/CliBlock" import type { ComponentProps, FC } from "react" interface Param { @@ -103,6 +104,7 @@ export default async function Page(props: { params: Promise }): Promise>, APIPage: openapi.APIPage }} diff --git a/app/components/CliBlock.tsx b/app/components/CliBlock.tsx new file mode 100644 index 0000000..a01ebe4 --- /dev/null +++ b/app/components/CliBlock.tsx @@ -0,0 +1,63 @@ +import fs from 'fs/promises'; +import path from 'path'; + +interface CliBlockProps { + hash?: string; + height?: string; + lang?: 'cli' | 'ansi'; + children: React.ReactNode; +} + +export default async function CliBlock({ hash, height, lang = 'cli', children }: CliBlockProps) { + // If no hash, render as regular code block + if (!hash) { + return ( +
+
$ {children}
+
+ Run pnpm update-cli to generate output +
+
+ ); + } + + // Determine which directory to use based on lang + const dir = lang === 'ansi' + ? path.join(process.cwd(), 'public/cli-examples') + : path.join(process.cwd(), 'public/cache/cli-output'); + const htmlPath = path.join(dir, `${hash}.html`); + + try { + // Read the HTML file content + const fullHtmlContent = await fs.readFile(htmlPath, 'utf8'); + + // Extract content from body tag if present (for full HTML documents) + const bodyMatch = fullHtmlContent.match(/]*>([\s\S]*)<\/body>/i); + const htmlContent = bodyMatch ? bodyMatch[1] : fullHtmlContent; + + return ( +
+
+
$ {children}
+
+
+
+
+
+ ); + } catch (error) { + // HTML file not found, show placeholder + const errorMessage = lang === 'ansi' + ? 'Output not found. Run ./scripts/sync-commands.sh to sync examples.' + : 'Output cache not found. Run pnpm update-cli to generate.'; + + return ( +
+
$ {children}
+
+ {errorMessage} (hash: {hash}{height && `, height: ${height}`}) +
+
+ ); + } +} \ No newline at end of file diff --git a/app/components/ResizableIframe.tsx b/app/components/ResizableIframe.tsx new file mode 100644 index 0000000..fbe8df6 --- /dev/null +++ b/app/components/ResizableIframe.tsx @@ -0,0 +1,22 @@ +interface ResizableIframeProps { + src: string + title: string + sandbox: string + className?: string + fixedHeight?: string +} + +export default function ResizableIframe({ src, title, sandbox, className, fixedHeight }: ResizableIframeProps) { + const height = fixedHeight || '200px' + const minHeight = fixedHeight ? undefined : '200px' + + return ( +