Skip to content

docs: Fix ANSI escape sequences in pack CLI leaking into documentation#940

Merged
AidanDelaney merged 1 commit into
buildpacks:mainfrom
lcampanella98:docs-fix-ansi-escape
Jun 7, 2026
Merged

docs: Fix ANSI escape sequences in pack CLI leaking into documentation#940
AidanDelaney merged 1 commit into
buildpacks:mainfrom
lcampanella98:docs-fix-ansi-escape

Conversation

@lcampanella98
Copy link
Copy Markdown
Contributor

@lcampanella98 lcampanella98 commented May 27, 2026

Fixes Issue

Problem

The get_pack_commands.go generator uses cobra/doc.GenMarkdownTreeCustom to produce markdown from the pack command tree. Some pack commands include ANSI color codes in their description strings (e.g. \x1b[94m...\x1b[0m) to improve terminal --help readability. These codes were passing through the generator unmodified and appearing as noise in the rendered documentation. See #891 for screenshots of the three affected places in the documentation. Which are:

https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/cli/pack_config_pull-policy/
https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/cli/pack_config_lifecycle-image/
https://buildpacks.io/docs/for-platform-operators/how-to/integrate-ci/pack/cli/pack_config_registries_default/

Solution

Added a post-generation step that walks the output directory and strips ANSI escape sequences (\x1b\[[0-9;]*m) from all generated .md files. This is the appropriate place to handle the conversion (rather than changing the pack CLI output) — the generator is the boundary between terminal output and markdown, and stripping color codes there keeps the fix localized without affecting the upstream CLI's terminal experience. The fix also future-proofs the documentation against newly added CLI ANSI escape codes.

Three generated markdown files were affected: pack_config_pull-policy.md, pack_config_lifecycle-image.md, and pack_config_registries_default.md.

Testing

  • Verified which files this change touched by running a diff between the pack cli directory tree before and after the change. There were 3 touched files:
➜  docs git:(main) ✗ diff -r /tmp/pack-cli-before /home/lorenzo/projects/docs/content/docs/for-platform-operators/how-to/integrate-ci/pack/cli | cat -v
diff --color -r /tmp/pack-cli-before/pack_config_lifecycle-image.md /home/lorenzo/projects/docs/content/docs/for-platform-operators/how-to/integrate-ci/pack/cli/pack_config_lifecycle-image.md
23c23
<   -u, --unset   Unset custom lifecycle image, and use the lifecycle images from ^[[94mdocker.io/buildpacksio/lifecycle^[[0m
---
>   -u, --unset   Unset custom lifecycle image, and use the lifecycle images from docker.io/buildpacksio/lifecycle
diff --color -r /tmp/pack-cli-before/pack_config_pull-policy.md /home/lorenzo/projects/docs/content/docs/for-platform-operators/how-to/integrate-ci/pack/cli/pack_config_pull-policy.md
17c17
< Unsetting the pull policy will reset the policy to the default, which is ^[[94malways^[[0m
---
> Unsetting the pull policy will reset the policy to the default, which is always
27c27
<   -u, --unset   Unset pull policy, and set it back to the default pull-policy, which is ^[[94malways^[[0m
---
>   -u, --unset   Unset pull policy, and set it back to the default pull-policy, which is always
diff --color -r /tmp/pack-cli-before/pack_config_registries_default.md /home/lorenzo/projects/docs/content/docs/for-platform-operators/how-to/integrate-ci/pack/cli/pack_config_registries_default.md
18c18
< Unsetting the default registry will reset the default-registry to be the official buildpacks registry, ^[[94mhttps://github.com/buildpacks/registry-index^[[0m
---
> Unsetting the default registry will reset the default-registry to be the official buildpacks registry, https://github.com/buildpacks/registry-index
  • Visually inspected the modified documentation pages with make serve

buildpacks#891)

The get_pack_commands.go generator uses cobra/doc.GenMarkdownTreeCustom to produce markdown from the pack command tree. Some pack commands include ANSI color codes in their description strings (e.g.
\x1b[94m...\x1b[0m) to improve terminal --help readability. These codes were passing through the generator unmodified and appearing as noise in the rendered documentation.

Added a post-generation step that walks the output directory and strips SGR ANSI escape sequences (\x1b\[[0-9;]*m) from all generated .md files. This is the appropriate place to handle the conversion
— the generator is the boundary between terminal output and markdown, and stripping color codes there keeps the fix localized without affecting the upstream CLI's terminal experience.

Three files were affected: pack_config_pull-policy.md, pack_config_lifecycle-image.md, and pack_config_registries_default.md.

Signed-off-by: Lorenzo Campanella <enzocampanella98@gmail.com>
@lcampanella98 lcampanella98 requested a review from a team as a code owner May 27, 2026 21:41
Copy link
Copy Markdown
Member

@AidanDelaney AidanDelaney left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great thank you!

@AidanDelaney AidanDelaney merged commit 5c2438c into buildpacks:main Jun 7, 2026
4 checks passed
github-actions Bot pushed a commit that referenced this pull request Jun 7, 2026
#891) (#940)

The get_pack_commands.go generator uses cobra/doc.GenMarkdownTreeCustom to produce markdown from the pack command tree. Some pack commands include ANSI color codes in their description strings (e.g.
\x1b[94m...\x1b[0m) to improve terminal --help readability. These codes were passing through the generator unmodified and appearing as noise in the rendered documentation.

Added a post-generation step that walks the output directory and strips SGR ANSI escape sequences (\x1b\[[0-9;]*m) from all generated .md files. This is the appropriate place to handle the conversion
— the generator is the boundary between terminal output and markdown, and stripping color codes there keeps the fix localized without affecting the upstream CLI's terminal experience.

Signed-off-by: Lorenzo Campanella <enzocampanella98@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

There is a typo in the doc which is [94malways[0m

3 participants