From fe25a6e8eacba42c18e228c55b8a9b9c9fde1a5d Mon Sep 17 00:00:00 2001 From: konojunya Date: Sun, 6 Sep 2026 12:53:58 +0900 Subject: [PATCH] docs: surface CLI health and shell setup --- content/site/guide/getting-started.md | 29 +++++++++++++++++++++- content/site/ja/guide/getting-started.md | 29 +++++++++++++++++++++- content/site/ko/guide/getting-started.md | 29 +++++++++++++++++++++- content/site/zh/guide/getting-started.md | 29 +++++++++++++++++++++- generated/manifest.json | 8 +++--- generated/site/guide/getting-started.md | 29 +++++++++++++++++++++- generated/site/ja/guide/getting-started.md | 29 +++++++++++++++++++++- generated/site/ko/guide/getting-started.md | 29 +++++++++++++++++++++- generated/site/zh/guide/getting-started.md | 29 +++++++++++++++++++++- scripts/first-render.test.mjs | 4 +++ 10 files changed, 232 insertions(+), 12 deletions(-) diff --git a/content/site/guide/getting-started.md b/content/site/guide/getting-started.md index e759e85..b8da6ba 100644 --- a/content/site/guide/getting-started.md +++ b/content/site/guide/getting-started.md @@ -122,6 +122,33 @@ $ stack fmt diagram.stack $ stack fmt --check diagram.stack ``` +## Check your installation and add shell integration + +Before relying on Stack in a project or coding-agent workflow, inspect the installation with two read-only commands: + +```text +$ stack doctor +$ stack config path +``` + +`stack doctor` reports the CLI version, selected configuration path, configuration health, effective icon-store path, and installed known-provider packs. A missing default configuration or icon store is healthy; invalid or unreadable configured paths exit with status `2` and include a corrective action. `stack config path` prints the selected `config.yaml` path without creating or reading it. + +Homebrew installs the matching completion and manual files automatically. Direct, Aqua, and Cargo users can generate the same deterministic files for their shell: + +```text +$ stack completions bash +$ stack completions zsh +$ stack completions fish +$ stack manpage +``` + +These commands print to standard output and never edit shell startup files. Save the output in your shell's user-owned completion or manual directory by following the [shell integration guide](https://github.com/stack-sh/cli/blob/main/docs/completions.md). You can also read the offline manual without installing it: + +```text +$ stack manpage > stack.1 +$ man ./stack.1 +``` + ## Write your first document For the browser path, open the [Playground](https://stack-diagram.com/) and replace its editor content with this example. CLI users can save the same source as `diagram.stack` and repeat the check/render commands above: @@ -212,4 +239,4 @@ Stack does not update itself. Use the installer that owns your binary. Configura | Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | Run `aqua rm -m pl stack-sh,stack-sh/cli` while this configuration is present, then remove `stack-sh/cli` from `aqua.yaml`. Other projects using this package may reinstall it when needed. | | Direct download | Verify a new release and replace only your directly installed binary. | Remove only the direct binary you installed (`~/.local/bin/stack`). | -For shell completions, manual pages, and recovery, see [shell integration](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [safe upgrades](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), and [supply-chain verification](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md). +For upgrade recovery and artifact verification, see [safe upgrades](https://github.com/stack-sh/cli/blob/main/docs/self-update.md) and [supply-chain verification](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md). diff --git a/content/site/ja/guide/getting-started.md b/content/site/ja/guide/getting-started.md index b695319..f63c94a 100644 --- a/content/site/ja/guide/getting-started.md +++ b/content/site/ja/guide/getting-started.md @@ -122,6 +122,33 @@ $ stack fmt diagram.stack $ stack fmt --check diagram.stack ``` +## 導入状態を確認し、シェル連携を有効にする + +プロジェクトやcoding agentのworkflowで継続利用する前に、次のread-onlyな2コマンドで導入状態を確認します。 + +```text +$ stack doctor +$ stack config path +``` + +`stack doctor`はCLI version、選択された設定パス、設定の状態、有効なicon storeのパス、導入済みの既知provider packを報告します。デフォルトの設定やicon storeが存在しない状態は正常です。明示したパスが不正または読み取れない場合は、修正方法を示してstatus `2`で終了します。`stack config path`は、設定を作成・読み込みせず、選択される`config.yaml`のパスを表示します。 + +Homebrewはbinaryと一致する補完・manual fileを自動で導入します。直接ダウンロード、Aqua、Cargoでは、同じ決定的なfileを利用するshellに合わせて生成できます。 + +```text +$ stack completions bash +$ stack completions zsh +$ stack completions fish +$ stack manpage +``` + +これらのコマンドは標準出力へ書き出すだけで、shellのstartup fileを変更しません。[シェル連携ガイド](https://github.com/stack-sh/cli/blob/main/docs/completions.md)に従い、利用者が所有する補完・manual用ディレクトリへ保存してください。インストールせずにoffline manualを読むこともできます。 + +```text +$ stack manpage > stack.1 +$ man ./stack.1 +``` + ## 最初のdocumentを書く ブラウザで試す場合は[Playground](https://stack-diagram.com/)を開き、エディタを次の作例に置き換えます。CLIの場合は同じソースを`diagram.stack`として保存し、上の検証・描画コマンドを実行できます。 @@ -212,4 +239,4 @@ Stack自身は更新を行いません。導入に使ったツールで管理し | Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | この設定がある状態で`aqua rm -m pl stack-sh,stack-sh/cli`を実行し、`aqua.yaml`から`stack-sh/cli`を削除します。他のプロジェクトが必要とする場合は再インストールされます。 | | 直接ダウンロード | 新しいreleaseを検証し、直接導入したバイナリーだけを差し替えます。 | 自分で導入したバイナリー（`~/.local/bin/stack`）だけを削除します。 | -補完・man page・復旧手順は[シェル連携](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全な更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)、[配布物の検証](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)を参照してください。 +更新時の復旧とartifactの検証は[安全な更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)と[配布物の検証](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)を参照してください。 diff --git a/content/site/ko/guide/getting-started.md b/content/site/ko/guide/getting-started.md index 1aa5c04..f44fada 100644 --- a/content/site/ko/guide/getting-started.md +++ b/content/site/ko/guide/getting-started.md @@ -122,6 +122,33 @@ $ stack fmt diagram.stack $ stack fmt --check diagram.stack ``` +## 설치 상태 확인 및 셸 연동 설정 + +프로젝트나coding agent workflow에서 Stack을 계속 사용하기 전에 다음 두 read-only 명령으로 설치 상태를 확인하세요. + +```text +$ stack doctor +$ stack config path +``` + +`stack doctor`는 CLI 버전, 선택된 설정 경로, 설정 상태, 실제 icon store 경로, 설치된 알려진 provider pack을 보고합니다. 기본 설정이나icon store가 없는 상태는 정상입니다. 명시적으로 설정한 경로가 잘못되었거나 읽을 수 없으면 수정 방법을 표시하고 상태 코드 `2`로 종료합니다. `stack config path`는 설정을 만들거나 읽지 않고 선택될 `config.yaml` 경로만 출력합니다. + +Homebrew는binary와 일치하는 자동 완성 및manual 파일을 자동으로 설치합니다. 직접 다운로드, Aqua, Cargo 사용자는 자신의 셸에 맞춰 동일하고 결정적인 파일을 생성할 수 있습니다. + +```text +$ stack completions bash +$ stack completions zsh +$ stack completions fish +$ stack manpage +``` + +이 명령은 표준 출력에만 쓰며 셸 시작 파일을 수정하지 않습니다. [셸 연동 가이드](https://github.com/stack-sh/cli/blob/main/docs/completions.md)에 따라 사용자 소유의 자동 완성 또는manual 디렉터리에 출력을 저장하세요. 설치하지 않고offline manual을 읽을 수도 있습니다. + +```text +$ stack manpage > stack.1 +$ man ./stack.1 +``` + ## 첫 문서 작성 브라우저에서 체험하려면 [Playground](https://stack-diagram.com/)를 열고 에디터 내용을 다음 예제로 바꾸세요. CLI 사용자는 같은 소스를 `diagram.stack`으로 저장한 뒤 위의 검사·렌더링 명령을 다시 실행할 수 있습니다. @@ -212,4 +239,4 @@ Stack은 스스로 업데이트하지 않습니다. 바이너리를 설치한 | Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | 이 설정이 있는 상태에서 `aqua rm -m pl stack-sh,stack-sh/cli`를 실행하고 `aqua.yaml`에서 `stack-sh/cli`를 제거하세요. 다른 프로젝트에서 필요하면 다시 설치될 수 있습니다. | | 직접 다운로드 | 새release를 검증한 뒤 직접 설치한 바이너리만 교체하세요. | 직접 설치한 바이너리(`~/.local/bin/stack`)만 제거하세요. | -자동 완성, man 페이지, 복구 절차는 [셸 통합](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [안전한 업데이트](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), [공급망 검증](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)을 참고하세요. +업데이트 복구와artifact 검증은 [안전한 업데이트](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)와 [공급망 검증](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)을 참고하세요. diff --git a/content/site/zh/guide/getting-started.md b/content/site/zh/guide/getting-started.md index 4d09116..2ba808c 100644 --- a/content/site/zh/guide/getting-started.md +++ b/content/site/zh/guide/getting-started.md @@ -122,6 +122,33 @@ $ stack fmt diagram.stack $ stack fmt --check diagram.stack ``` +## 检查安装并配置shell集成 + +在项目或coding agent工作流中持续使用Stack之前，请先运行两个只读命令检查安装状态： + +```text +$ stack doctor +$ stack config path +``` + +`stack doctor`会报告CLI版本、选中的配置路径、配置状态、实际icon store路径和已安装的已知provider pack。默认配置或icon store不存在属于正常状态；显式配置的路径无效或不可读时，命令会提供修复建议并以状态码`2`退出。`stack config path`只显示将使用的`config.yaml`路径，不会创建或读取该文件。 + +Homebrew会自动安装与binary匹配的补全和manual文件。使用直接下载、Aqua或Cargo时，可以为自己的shell生成相同且确定的文件： + +```text +$ stack completions bash +$ stack completions zsh +$ stack completions fish +$ stack manpage +``` + +这些命令只写入标准输出，不会修改shell启动文件。请按照[shell集成指南](https://github.com/stack-sh/cli/blob/main/docs/completions.md)，将输出保存到用户拥有的补全或manual目录。也可以无需安装，直接阅读offline manual： + +```text +$ stack manpage > stack.1 +$ man ./stack.1 +``` + ## 编写第一份文档 在浏览器中试用时，打开[Playground](https://stack-diagram.com/)，将编辑器内容替换为下面的示例。CLI用户可以将相同源文件保存为`diagram.stack`，然后再次执行上面的检查与渲染命令： @@ -212,4 +239,4 @@ Stack不会自行更新。请使用安装该二进制文件的工具进行管理 | Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | 保留此配置时运行`aqua rm -m pl stack-sh,stack-sh/cli`，然后从`aqua.yaml`移除`stack-sh/cli`。其他项目需要此包时可能会重新安装。 | | 直接下载 | 验证新release后，仅替换直接安装的二进制文件。 | 仅删除自己直接安装的二进制文件（`~/.local/bin/stack`）。 | -补全、man页面与恢复方法见[shell集成](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)和[供应链验证](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)。 +更新恢复与artifact验证方法见[安全更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)和[供应链验证](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)。 diff --git a/generated/manifest.json b/generated/manifest.json index ab8003e..2158106 100644 --- a/generated/manifest.json +++ b/generated/manifest.json @@ -24,7 +24,7 @@ }, { "path": "site/guide/getting-started.md", - "sha256": "d6356f314f28389119ce31398662c95c8c7ef6ddac60f0bd054ea1f45de757a4" + "sha256": "807e0b5ea42ab7f281c9c9f6a672415a8e4425bd89188a4a28209b3ab4c708f3" }, { "path": "site/guide/playground.md", @@ -52,7 +52,7 @@ }, { "path": "site/ja/guide/getting-started.md", - "sha256": "aa4bca13cc178bbdb3fb15badfc2d207b79ee0c539acbed92c712120208fa737" + "sha256": "e5cb089c8e51a95ac5c5085cbd316de33190ae3f0ce6533d8f13ed551d54f53e" }, { "path": "site/ja/guide/playground.md", @@ -108,7 +108,7 @@ }, { "path": "site/ko/guide/getting-started.md", - "sha256": "2b3ca8edbf2b8956dae8311283984bbedbf1efee4a60ff38eea74d390b0bd6bc" + "sha256": "999c53bd1dd88e1a17ea6a0b1df548e37a9e8325711c0b1f3c67431ea65de77c" }, { "path": "site/ko/guide/playground.md", @@ -192,7 +192,7 @@ }, { "path": "site/zh/guide/getting-started.md", - "sha256": "7b6f7d7cdc8264d4633828a21fb1202c3870c9ef6c198c6e23b369214f2abc11" + "sha256": "0b5162f8c023ead20434867d354fdc4aa7df268d93cad8fbf2d89bde9d65a673" }, { "path": "site/zh/guide/playground.md", diff --git a/generated/site/guide/getting-started.md b/generated/site/guide/getting-started.md index 2729882..2124b99 100644 --- a/generated/site/guide/getting-started.md +++ b/generated/site/guide/getting-started.md @@ -122,6 +122,33 @@ $ stack fmt diagram.stack $ stack fmt --check diagram.stack ``` +## Check your installation and add shell integration + +Before relying on Stack in a project or coding-agent workflow, inspect the installation with two read-only commands: + +```text +$ stack doctor +$ stack config path +``` + +`stack doctor` reports the CLI version, selected configuration path, configuration health, effective icon-store path, and installed known-provider packs. A missing default configuration or icon store is healthy; invalid or unreadable configured paths exit with status `2` and include a corrective action. `stack config path` prints the selected `config.yaml` path without creating or reading it. + +Homebrew installs the matching completion and manual files automatically. Direct, Aqua, and Cargo users can generate the same deterministic files for their shell: + +```text +$ stack completions bash +$ stack completions zsh +$ stack completions fish +$ stack manpage +``` + +These commands print to standard output and never edit shell startup files. Save the output in your shell's user-owned completion or manual directory by following the [shell integration guide](https://github.com/stack-sh/cli/blob/main/docs/completions.md). You can also read the offline manual without installing it: + +```text +$ stack manpage > stack.1 +$ man ./stack.1 +``` + ## Write your first document For the browser path, open the [Playground](https://stack-diagram.com/) and replace its editor content with this example. CLI users can save the same source as `diagram.stack` and repeat the check/render commands above: @@ -212,4 +239,4 @@ Stack does not update itself. Use the installer that owns your binary. Configura | Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | Run `aqua rm -m pl stack-sh,stack-sh/cli` while this configuration is present, then remove `stack-sh/cli` from `aqua.yaml`. Other projects using this package may reinstall it when needed. | | Direct download | Verify a new release and replace only your directly installed binary. | Remove only the direct binary you installed (`~/.local/bin/stack`). | -For shell completions, manual pages, and recovery, see [shell integration](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [safe upgrades](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), and [supply-chain verification](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md). +For upgrade recovery and artifact verification, see [safe upgrades](https://github.com/stack-sh/cli/blob/main/docs/self-update.md) and [supply-chain verification](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md). diff --git a/generated/site/ja/guide/getting-started.md b/generated/site/ja/guide/getting-started.md index d7f6f6d..1dac03b 100644 --- a/generated/site/ja/guide/getting-started.md +++ b/generated/site/ja/guide/getting-started.md @@ -122,6 +122,33 @@ $ stack fmt diagram.stack $ stack fmt --check diagram.stack ``` +## 導入状態を確認し、シェル連携を有効にする + +プロジェクトやcoding agentのworkflowで継続利用する前に、次のread-onlyな2コマンドで導入状態を確認します。 + +```text +$ stack doctor +$ stack config path +``` + +`stack doctor`はCLI version、選択された設定パス、設定の状態、有効なicon storeのパス、導入済みの既知provider packを報告します。デフォルトの設定やicon storeが存在しない状態は正常です。明示したパスが不正または読み取れない場合は、修正方法を示してstatus `2`で終了します。`stack config path`は、設定を作成・読み込みせず、選択される`config.yaml`のパスを表示します。 + +Homebrewはbinaryと一致する補完・manual fileを自動で導入します。直接ダウンロード、Aqua、Cargoでは、同じ決定的なfileを利用するshellに合わせて生成できます。 + +```text +$ stack completions bash +$ stack completions zsh +$ stack completions fish +$ stack manpage +``` + +これらのコマンドは標準出力へ書き出すだけで、shellのstartup fileを変更しません。[シェル連携ガイド](https://github.com/stack-sh/cli/blob/main/docs/completions.md)に従い、利用者が所有する補完・manual用ディレクトリへ保存してください。インストールせずにoffline manualを読むこともできます。 + +```text +$ stack manpage > stack.1 +$ man ./stack.1 +``` + ## 最初のdocumentを書く ブラウザで試す場合は[Playground](https://stack-diagram.com/)を開き、エディタを次の作例に置き換えます。CLIの場合は同じソースを`diagram.stack`として保存し、上の検証・描画コマンドを実行できます。 @@ -212,4 +239,4 @@ Stack自身は更新を行いません。導入に使ったツールで管理し | Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | この設定がある状態で`aqua rm -m pl stack-sh,stack-sh/cli`を実行し、`aqua.yaml`から`stack-sh/cli`を削除します。他のプロジェクトが必要とする場合は再インストールされます。 | | 直接ダウンロード | 新しいreleaseを検証し、直接導入したバイナリーだけを差し替えます。 | 自分で導入したバイナリー（`~/.local/bin/stack`）だけを削除します。 | -補完・man page・復旧手順は[シェル連携](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全な更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)、[配布物の検証](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)を参照してください。 +更新時の復旧とartifactの検証は[安全な更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)と[配布物の検証](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)を参照してください。 diff --git a/generated/site/ko/guide/getting-started.md b/generated/site/ko/guide/getting-started.md index c0026e1..efc95f0 100644 --- a/generated/site/ko/guide/getting-started.md +++ b/generated/site/ko/guide/getting-started.md @@ -122,6 +122,33 @@ $ stack fmt diagram.stack $ stack fmt --check diagram.stack ``` +## 설치 상태 확인 및 셸 연동 설정 + +프로젝트나coding agent workflow에서 Stack을 계속 사용하기 전에 다음 두 read-only 명령으로 설치 상태를 확인하세요. + +```text +$ stack doctor +$ stack config path +``` + +`stack doctor`는 CLI 버전, 선택된 설정 경로, 설정 상태, 실제 icon store 경로, 설치된 알려진 provider pack을 보고합니다. 기본 설정이나icon store가 없는 상태는 정상입니다. 명시적으로 설정한 경로가 잘못되었거나 읽을 수 없으면 수정 방법을 표시하고 상태 코드 `2`로 종료합니다. `stack config path`는 설정을 만들거나 읽지 않고 선택될 `config.yaml` 경로만 출력합니다. + +Homebrew는binary와 일치하는 자동 완성 및manual 파일을 자동으로 설치합니다. 직접 다운로드, Aqua, Cargo 사용자는 자신의 셸에 맞춰 동일하고 결정적인 파일을 생성할 수 있습니다. + +```text +$ stack completions bash +$ stack completions zsh +$ stack completions fish +$ stack manpage +``` + +이 명령은 표준 출력에만 쓰며 셸 시작 파일을 수정하지 않습니다. [셸 연동 가이드](https://github.com/stack-sh/cli/blob/main/docs/completions.md)에 따라 사용자 소유의 자동 완성 또는manual 디렉터리에 출력을 저장하세요. 설치하지 않고offline manual을 읽을 수도 있습니다. + +```text +$ stack manpage > stack.1 +$ man ./stack.1 +``` + ## 첫 문서 작성 브라우저에서 체험하려면 [Playground](https://stack-diagram.com/)를 열고 에디터 내용을 다음 예제로 바꾸세요. CLI 사용자는 같은 소스를 `diagram.stack`으로 저장한 뒤 위의 검사·렌더링 명령을 다시 실행할 수 있습니다. @@ -212,4 +239,4 @@ Stack은 스스로 업데이트하지 않습니다. 바이너리를 설치한 | Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | 이 설정이 있는 상태에서 `aqua rm -m pl stack-sh,stack-sh/cli`를 실행하고 `aqua.yaml`에서 `stack-sh/cli`를 제거하세요. 다른 프로젝트에서 필요하면 다시 설치될 수 있습니다. | | 직접 다운로드 | 새release를 검증한 뒤 직접 설치한 바이너리만 교체하세요. | 직접 설치한 바이너리(`~/.local/bin/stack`)만 제거하세요. | -자동 완성, man 페이지, 복구 절차는 [셸 통합](https://github.com/stack-sh/cli/blob/main/docs/completions.md), [안전한 업데이트](https://github.com/stack-sh/cli/blob/main/docs/self-update.md), [공급망 검증](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)을 참고하세요. +업데이트 복구와artifact 검증은 [안전한 업데이트](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)와 [공급망 검증](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)을 참고하세요. diff --git a/generated/site/zh/guide/getting-started.md b/generated/site/zh/guide/getting-started.md index 700000c..4710317 100644 --- a/generated/site/zh/guide/getting-started.md +++ b/generated/site/zh/guide/getting-started.md @@ -122,6 +122,33 @@ $ stack fmt diagram.stack $ stack fmt --check diagram.stack ``` +## 检查安装并配置shell集成 + +在项目或coding agent工作流中持续使用Stack之前，请先运行两个只读命令检查安装状态： + +```text +$ stack doctor +$ stack config path +``` + +`stack doctor`会报告CLI版本、选中的配置路径、配置状态、实际icon store路径和已安装的已知provider pack。默认配置或icon store不存在属于正常状态；显式配置的路径无效或不可读时，命令会提供修复建议并以状态码`2`退出。`stack config path`只显示将使用的`config.yaml`路径，不会创建或读取该文件。 + +Homebrew会自动安装与binary匹配的补全和manual文件。使用直接下载、Aqua或Cargo时，可以为自己的shell生成相同且确定的文件： + +```text +$ stack completions bash +$ stack completions zsh +$ stack completions fish +$ stack manpage +``` + +这些命令只写入标准输出，不会修改shell启动文件。请按照[shell集成指南](https://github.com/stack-sh/cli/blob/main/docs/completions.md)，将输出保存到用户拥有的补全或manual目录。也可以无需安装，直接阅读offline manual： + +```text +$ stack manpage > stack.1 +$ man ./stack.1 +``` + ## 编写第一份文档 在浏览器中试用时，打开[Playground](https://stack-diagram.com/)，将编辑器内容替换为下面的示例。CLI用户可以将相同源文件保存为`diagram.stack`，然后再次执行上面的检查与渲染命令： @@ -212,4 +239,4 @@ Stack不会自行更新。请使用安装该二进制文件的工具进行管理 | Aqua | `aqua update`, `aqua update-checksum`, `aqua install` | 保留此配置时运行`aqua rm -m pl stack-sh,stack-sh/cli`，然后从`aqua.yaml`移除`stack-sh/cli`。其他项目需要此包时可能会重新安装。 | | 直接下载 | 验证新release后，仅替换直接安装的二进制文件。 | 仅删除自己直接安装的二进制文件（`~/.local/bin/stack`）。 | -补全、man页面与恢复方法见[shell集成](https://github.com/stack-sh/cli/blob/main/docs/completions.md)、[安全更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)和[供应链验证](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)。 +更新恢复与artifact验证方法见[安全更新](https://github.com/stack-sh/cli/blob/main/docs/self-update.md)和[供应链验证](https://github.com/stack-sh/cli/blob/main/docs/supply-chain.md)。 diff --git a/scripts/first-render.test.mjs b/scripts/first-render.test.mjs index 4d37d04..0eec8bd 100644 --- a/scripts/first-render.test.mjs +++ b/scripts/first-render.test.mjs @@ -19,6 +19,10 @@ test('all locales keep identical installer blocks and a complete first-render wa assert.match(english, /cargo install stack-diagram-cli --version \{\{cliVersion\}\} --locked/); assert.match(english, /--source-ref "refs\/tags\/v\$version" --deny-self-hosted-runners/); assert.match(english, /test ! -e "\$HOME\/\.local\/bin\/stack"/); + for (const command of ['stack doctor', 'stack config path', 'stack completions bash', 'stack completions zsh', 'stack completions fish', 'stack manpage']) { + assert.match(english, new RegExp(`^\\$ ${command}$`, 'm'), `Missing CLI setup command: ${command}`); + } + assert.match(english, /docs\/completions\.md/); for (const locale of ['ja', 'zh', 'ko']) { const translated = await readFile(new URL(`../content/site/${locale}/guide/getting-started.md`, import.meta.url), 'utf8'); assert.deepEqual(blocks(translated), blocks(english), `${locale} installer or command drift`);