From 4d75b319c5b1b335717f69438db1e78f31e2525c Mon Sep 17 00:00:00 2001 From: konojunya Date: Sun, 6 Sep 2026 07:22:58 +0900 Subject: [PATCH] docs: lead with three user benefits across all locales --- README.md | 9 +++ content/product-story-locales.json | 71 ++++++++++++++++++++++ content/site/guide/getting-started.md | 10 +-- content/site/guide/what-is-stack.md | 9 +-- content/site/index.md | 25 +------- content/site/ja/guide/getting-started.md | 10 +-- content/site/ja/guide/what-is-stack.md | 9 +-- content/site/ja/index.md | 25 +------- content/site/ko/guide/getting-started.md | 10 +-- content/site/ko/guide/what-is-stack.md | 9 +-- content/site/ko/index.md | 25 +------- content/site/zh/guide/getting-started.md | 10 +-- content/site/zh/guide/what-is-stack.md | 9 +-- content/site/zh/index.md | 25 +------- generated/manifest.json | 24 ++++---- generated/site/guide/getting-started.md | 10 +-- generated/site/guide/what-is-stack.md | 11 ++-- generated/site/index.md | 27 +------- generated/site/ja/guide/getting-started.md | 10 +-- generated/site/ja/guide/what-is-stack.md | 11 ++-- generated/site/ja/index.md | 27 +------- generated/site/ko/guide/getting-started.md | 10 +-- generated/site/ko/guide/what-is-stack.md | 11 ++-- generated/site/ko/index.md | 27 +------- generated/site/zh/guide/getting-started.md | 10 +-- generated/site/zh/guide/what-is-stack.md | 11 ++-- generated/site/zh/index.md | 27 +------- scripts/generate.mjs | 8 ++- scripts/generate.test.mjs | 19 ++++++ scripts/product-story.mjs | 45 ++++++++++++++ scripts/product-story.test.mjs | 25 ++++++++ 31 files changed, 276 insertions(+), 293 deletions(-) create mode 100644 content/product-story-locales.json create mode 100644 scripts/product-story.mjs diff --git a/README.md b/README.md index c094bd9..546f27a 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,15 @@ coding-agent guides explain this and share one copyable prompt from `content/agent-prompt.txt`. This avoids hand-maintaining the validation workflow both in a guide and a skill. `{{cliVersion}}` comes from the release lock. +The English product story lives in `content/product-story.json`; Japanese, +Chinese, and Korean UI copy lives in `content/product-story-locales.json`, keyed +by the canonical benefit IDs. `{{productHome}}` generates homepage metadata and +`{{productBenefits}}` generates the introduction's benefit list. Update those +sources rather than copying marketing text into page templates. The homepage +has only `hero.name` as its H1, a separate tagline, and a `description` field +for page metadata and the website's supporting hero paragraph. The website +owns rendering that paragraph; no example SVG is generated here. + `generated/site/` contains complete Markdown inputs for the website. Website presentation, images, VitePress configuration, and deployment are not owned here. diff --git a/content/product-story-locales.json b/content/product-story-locales.json new file mode 100644 index 0000000..a5ae645 --- /dev/null +++ b/content/product-story-locales.json @@ -0,0 +1,71 @@ +{ + "ja": { + "hero": { + "tagline": "構成を書くだけで、美しい図に。", + "description": "サービスとつながりをテキストで記述。Stackが配置とテーマを整え、ターミナルでもブラウザでも共有できるSVGを生成します。", + "primaryActionText": "最初の図を作る", + "secondaryActionText": "Playgroundで試す", + "logoAlt": "Stackロゴ" + }, + "features": { + "beautiful-by-default": { + "title": "書くだけで、見た目が整う", + "details": "箱の位置や色ではなく、システムの構成に集中。自動配置と統一されたテーマで、手作業で整えなくても見やすい図になります。" + }, + "consistent-everywhere": { + "title": "どこで作っても、一貫した図に", + "details": "Coding agent、ターミナル、ブラウザを行き来しても大丈夫。共通のエンジンが、同じソース・テーマ・アイコンパックから一貫した図を生成します。" + }, + "fast-local-rendering": { + "title": "手元で、すばやく描画", + "details": "描画サーバーを介さず、書いて、描いて、すぐ見直す。ソースは手元に置いたまま、スクリプトや外部アセットを含まないSVGを書き出せます。" + } + } + }, + "zh": { + "hero": { + "tagline": "写下技术架构，得到精美图表。", + "description": "用文本描述服务及其连接。Stack负责布局和主题，在终端或浏览器中生成可分享的SVG。", + "primaryActionText": "创建第一张图", + "secondaryActionText": "试用Playground", + "logoAlt": "Stack标志" + }, + "features": { + "beautiful-by-default": { + "title": "无需手动美化", + "details": "专注描述系统，不必逐个调整方框。自动布局和协调的主题让图表保持清晰美观，无需手动定位或设置样式。" + }, + "consistent-everywhere": { + "title": "不同工具，一致呈现", + "details": "在编程智能体、终端和浏览器之间自由切换。共享引擎让相同源文件、主题和图标包在不同工作流程中保持一致。" + }, + "fast-local-rendering": { + "title": "本地快速渲染", + "details": "无需渲染服务器，修改后即可再次生成。源文件留在你的设备上，并可导出不含脚本或外部资源的独立SVG。" + } + } + }, + "ko": { + "hero": { + "tagline": "구성을 쓰면, 아름다운 다이어그램으로.", + "description": "서비스와 연결을 텍스트로 설명하세요. Stack이 배치와 테마를 정리하고, 터미널이나 브라우저에서 공유할 수 있는 SVG를 만듭니다.", + "primaryActionText": "첫 다이어그램 만들기", + "secondaryActionText": "Playground에서 체험하기", + "logoAlt": "Stack 로고" + }, + "features": { + "beautiful-by-default": { + "title": "직접 꾸미지 않아도 아름답게", + "details": "박스 하나하나가 아닌 시스템을 설명하세요. 자동 배치와 조화로운 테마로 위치와 스타일을 수작업으로 조정하지 않아도 정돈된 다이어그램을 만듭니다." + }, + "consistent-everywhere": { + "title": "어디서나 일관된 결과", + "details": "코딩 에이전트, 터미널, 브라우저를 자유롭게 오가세요. 공유 엔진이 같은 소스, 테마, 아이콘 팩을 다양한 작업 환경에서 일관되게 렌더링합니다." + }, + "fast-local-rendering": { + "title": "내 기기에서 빠르게 렌더링", + "details": "렌더링 서버 없이 수정하고, 그리고, 다시 확인하세요. 소스를 내 기기에 둔 채 스크립트나 외부 에셋이 없는 독립형 SVG로 내보낼 수 있습니다." + } + } + } +} diff --git a/content/site/guide/getting-started.md b/content/site/guide/getting-started.md index 172546e..e759e85 100644 --- a/content/site/guide/getting-started.md +++ b/content/site/guide/getting-started.md @@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack ## Write your first document -Replace the editor content with this example: +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: ```stack stack 1.0 @@ -196,10 +196,10 @@ If Stack finds a problem, the diagnostic shows its severity, stable code, locati ## Choose what to learn next -- Read [Document and syntax](../language/syntax) for lexical rules and the complete grammar. -- Read [Nodes and groups](../language/nodes-and-groups) to model components and boundaries. -- Read [Edges and layout](../language/edges-and-layout) for relationships and placement intent. -- Read [Themes and icons](../language/themes-and-icons) before selecting a visual system or explicit icon. +- **Write with your coding agent:** install the optional [Stack skill](./coding-agents) and use the shared check/render workflow. +- **Find a starting point:** open a [live example](../examples/) in the Playground, then explore [themes and icons](../language/themes-and-icons). +- **Use your own setup:** [import provider icons](./provider-icons), then choose their local store through the [CLI configuration guide](https://github.com/stack-sh/cli/blob/main/docs/configuration.md). Configuration is a CLI contract; the browser uses explicit local pack import. +- **Look up the details:** use the [language reference](../language/syntax) and [diagnostics and limits](../reference/diagnostics-and-limits) as you model a larger system. ## Update or uninstall diff --git a/content/site/guide/what-is-stack.md b/content/site/guide/what-is-stack.md index bf3ea0a..2c3ca66 100644 --- a/content/site/guide/what-is-stack.md +++ b/content/site/guide/what-is-stack.md @@ -31,12 +31,9 @@ The document says that a client calls a service. It does not say where either bo ## What Stack optimizes for -- **Concise authoring:** useful diagrams need little more than named nodes and edges. -- **Predictable generation:** each concept has one constrained representation that people and language models can produce reliably. -- **Semantic source:** a document records topology and intent, not pixels. -- **Polished output:** the renderer owns a coherent visual system. -- **Actionable errors:** diagnostics point to source ranges and can include expected values, corrective help, and related declarations. -- **Safe embedding:** source cannot execute code, fetch arbitrary assets, or inject HTML or SVG. +{{productBenefits}} + +Consistency assumes matching engine versions and the same source, theme, and icon packs. Rendering stays local; installing tools, loading the website, and explicitly importing provider icons can require network access. See [versioning and safety](../reference/versioning-and-safety) for the exact boundaries. ## What Stack is not diff --git a/content/site/index.md b/content/site/index.md index 3bdf0f3..10ff1f9 100644 --- a/content/site/index.md +++ b/content/site/index.md @@ -1,27 +1,4 @@ --- layout: home - -hero: - name: Stack - text: Architecture, as source. - tagline: Write a small, semantic document. Get a consistent, accessible architecture diagram without drawing coordinates or styling every box. - image: - light: /favicon.svg - dark: /favicon.svg - alt: Stack logo - actions: - - theme: brand - text: Get started - link: /guide/getting-started - - theme: alt - text: Open Playground - link: https://stack-diagram.com/ - -features: - - title: Describe the system - details: Nodes, groups, relationships, and layout intent stay readable in a compact .stack file. - - title: Keep meaning portable - details: A versioned language and structured diagnostics separate architecture meaning from renderer choices. - - title: Render safely - details: The engine produces standalone SVG without scripts, arbitrary HTML, or network-loaded assets. +{{productHome}} --- diff --git a/content/site/ja/guide/getting-started.md b/content/site/ja/guide/getting-started.md index 65f77b3..b695319 100644 --- a/content/site/ja/guide/getting-started.md +++ b/content/site/ja/guide/getting-started.md @@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack ## 最初のdocumentを書く -Editorを次のexampleへ置き換えます。 +ブラウザで試す場合は[Playground](https://stack-diagram.com/)を開き、エディタを次の作例に置き換えます。CLIの場合は同じソースを`diagram.stack`として保存し、上の検証・描画コマンドを実行できます。 ```stack stack 1.0 @@ -196,10 +196,10 @@ Sourceは4つの要素で構成されています。 ## 次に読むもの -- Lexical ruleと完全なgrammarは[Documentとsyntax](../language/syntax)を参照します。 -- Componentとboundaryは[Nodeとgroup](../language/nodes-and-groups)を参照します。 -- Relationshipと配置intentは[Edgeとlayout](../language/edges-and-layout)を参照します。 -- Visual systemや明示iconを選ぶ前に[Themeとicon](../language/themes-and-icons)を参照します。 +- **Coding agentと書く:** 任意の[Stackスキル](./coding-agents)を導入し、共通の検証・描画手順を使います。 +- **作例から始める:** [実行時に描画される作例](../examples/)をPlaygroundで開き、[テーマとアイコン](../language/themes-and-icons)を試します。 +- **自分の環境に合わせる:** [プロバイダーアイコンを取り込み](./provider-icons)、[CLI設定ガイド](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)で保存先を選びます。この設定はCLI用です。ブラウザではローカルのパックを明示的に読み込みます。 +- **詳しく調べる:** [言語リファレンス](../language/syntax)と[診断・制限](../reference/diagnostics-and-limits)を参照しながら、より大きなシステムを記述します。 ## 更新・アンインストール diff --git a/content/site/ja/guide/what-is-stack.md b/content/site/ja/guide/what-is-stack.md index b6117c2..184d2b2 100644 --- a/content/site/ja/guide/what-is-stack.md +++ b/content/site/ja/guide/what-is-stack.md @@ -31,12 +31,9 @@ diagram "Service architecture" { ## Stackが重視すること -- **簡潔なauthoring:** 名前付きnodeとedgeだけで有用なdiagramを書けます。 -- **予測可能な生成:** 人とlanguage modelが同じconceptを安定して記述できます。 -- **Semantic source:** Pixelではなくtopologyとintentを記録します。 -- **整ったoutput:** 一貫したvisual systemをrendererが所有します。 -- **修正可能なerror:** Diagnosticはsource range、expected value、help、related declarationを示せます。 -- **安全な埋め込み:** Sourceはcode実行、任意asset取得、HTML/SVG注入ができません。 +{{productBenefits}} + +一貫した結果には、同じエンジンのバージョン・ソース・テーマ・アイコンパックが必要です。描画は手元で行いますが、ツールの導入、サイトの読み込み、明示的なプロバイダーアイコンの取り込みにはネットワークを使う場合があります。詳しい境界は[バージョニングと安全性](../reference/versioning-and-safety)を参照してください。 ## Stackではないもの diff --git a/content/site/ja/index.md b/content/site/ja/index.md index dafd1ac..10ff1f9 100644 --- a/content/site/ja/index.md +++ b/content/site/ja/index.md @@ -1,27 +1,4 @@ --- layout: home - -hero: - name: Stack - text: Architectureをsourceとして。 - tagline: 小さなsemantic documentを書くだけで、座標やboxごとのstyleを指定せず、一貫したaccessibleなarchitecture diagramを生成できます。 - image: - light: /favicon.svg - dark: /favicon.svg - alt: Stackロゴ - actions: - - theme: brand - text: はじめる - link: /ja/guide/getting-started - - theme: alt - text: Playgroundを開く - link: https://stack-diagram.com/ - -features: - - title: Systemを記述する - details: Node、group、relationship、layout intentを、簡潔な.stack fileとして読みやすく保ちます。 - - title: 意味をportableにする - details: Version付きlanguageとstructured diagnosticが、architectureの意味をrendererの選択から分離します。 - - title: 安全にrenderする - details: Script、任意HTML、network assetを含まないstandalone SVGをengineが生成します。 +{{productHome}} --- diff --git a/content/site/ko/guide/getting-started.md b/content/site/ko/guide/getting-started.md index 9cbfc99..1aa5c04 100644 --- a/content/site/ko/guide/getting-started.md +++ b/content/site/ko/guide/getting-started.md @@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack ## 첫 문서 작성 -에디터 내용을 다음 예제로 바꿉니다. +브라우저에서 체험하려면 [Playground](https://stack-diagram.com/)를 열고 에디터 내용을 다음 예제로 바꾸세요. CLI 사용자는 같은 소스를 `diagram.stack`으로 저장한 뒤 위의 검사·렌더링 명령을 다시 실행할 수 있습니다. ```stack stack 1.0 @@ -196,10 +196,10 @@ diagram "Checkout" { ## 다음으로 읽을 내용 -- 어휘 규칙과 전체 문법은 [문서와 문법](../language/syntax)을 참고하세요. -- 컴포넌트와 경계는 [노드와 그룹](../language/nodes-and-groups)을 참고하세요. -- 관계와 배치 의도는 [엣지와 레이아웃](../language/edges-and-layout)을 참고하세요. -- 시각 시스템이나 명시적 아이콘을 고르기 전에 [테마와 아이콘](../language/themes-and-icons)을 읽으세요. +- **코딩 에이전트와 작성하기:** 선택 사항인 [Stack 스킬](./coding-agents)을 설치하고 공통 검사·렌더링 흐름을 사용하세요. +- **예제에서 시작하기:** [실시간 렌더링 예제](../examples/)를 Playground에서 열고 [테마와 아이콘](../language/themes-and-icons)을 살펴보세요. +- **내 환경에 맞추기:** [공급자 아이콘을 가져온](./provider-icons) 다음 [CLI 설정 가이드](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)에서 로컬 저장소를 선택하세요. 이 설정은 CLI용이며, 브라우저에서는 로컬 팩을 명시적으로 가져옵니다. +- **세부 사항 찾아보기:** 더 큰 시스템을 모델링할 때 [언어 레퍼런스](../language/syntax)와 [진단과 제한](../reference/diagnostics-and-limits)을 참고하세요. ## 업데이트 또는 제거 diff --git a/content/site/ko/guide/what-is-stack.md b/content/site/ko/guide/what-is-stack.md index a5af2c5..1c77ecb 100644 --- a/content/site/ko/guide/what-is-stack.md +++ b/content/site/ko/guide/what-is-stack.md @@ -31,12 +31,9 @@ diagram "Service architecture" { ## Stack의 설계 목표 -- **간결한 작성:** 이름이 있는 노드와 엣지만으로 유용한 다이어그램을 만듭니다. -- **예측 가능한 생성:** 사람과 언어 모델이 같은 개념을 하나의 제한된 방식으로 안정적으로 표현합니다. -- **의미 기반 소스:** 픽셀이 아니라 토폴로지와 의도를 기록합니다. -- **정돈된 출력:** 렌더러가 일관된 시각 시스템을 소유합니다. -- **실행 가능한 오류:** 진단은 소스 범위, 예상 값, 수정 도움말, 관련 선언을 제공할 수 있습니다. -- **안전한 임베딩:** 소스는 코드를 실행하거나 임의 에셋을 가져오거나 HTML/SVG를 삽입할 수 없습니다. +{{productBenefits}} + +일관된 결과를 얻으려면 엔진 버전, 소스, 테마, 아이콘 팩이 같아야 합니다. 렌더링은 로컬에서 수행되지만 도구 설치, 웹사이트 로딩, 명시적인 공급자 아이콘 가져오기에는 네트워크가 필요할 수 있습니다. 정확한 범위는 [버전과 안전성](../reference/versioning-and-safety)을 참고하세요. ## Stack이 아닌 것 diff --git a/content/site/ko/index.md b/content/site/ko/index.md index 13a1514..10ff1f9 100644 --- a/content/site/ko/index.md +++ b/content/site/ko/index.md @@ -1,27 +1,4 @@ --- layout: home - -hero: - name: Stack - text: 아키텍처를 소스로. - tagline: 작은 의미 기반 문서를 작성하면 좌표나 박스별 스타일을 지정하지 않아도 일관되고 접근 가능한 아키텍처 다이어그램을 만들 수 있습니다. - image: - light: /favicon.svg - dark: /favicon.svg - alt: Stack 로고 - actions: - - theme: brand - text: 시작하기 - link: /ko/guide/getting-started - - theme: alt - text: Playground 열기 - link: https://stack-diagram.com/ - -features: - - title: 시스템 설명 - details: 노드, 그룹, 관계, 레이아웃 의도를 간결하고 읽기 쉬운 .stack 파일로 유지합니다. - - title: 의미의 이식성 - details: 버전이 있는 언어와 구조화된 진단이 아키텍처 의미를 렌더러 선택과 분리합니다. - - title: 안전한 렌더링 - details: 엔진은 스크립트, 임의 HTML, 네트워크 에셋이 없는 독립형 SVG를 생성합니다. +{{productHome}} --- diff --git a/content/site/zh/guide/getting-started.md b/content/site/zh/guide/getting-started.md index 0c5f794..4d09116 100644 --- a/content/site/zh/guide/getting-started.md +++ b/content/site/zh/guide/getting-started.md @@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack ## 编写第一份文档 -将编辑器内容替换为下面的示例： +在浏览器中试用时，打开[Playground](https://stack-diagram.com/)，将编辑器内容替换为下面的示例。CLI用户可以将相同源文件保存为`diagram.stack`，然后再次执行上面的检查与渲染命令： ```stack stack 1.0 @@ -196,10 +196,10 @@ diagram "Checkout" { ## 接下来阅读 -- [文档与语法](../language/syntax)介绍词法规则和完整语法。 -- [节点与分组](../language/nodes-and-groups)介绍组件和边界建模。 -- [连线与布局](../language/edges-and-layout)介绍关系和布局意图。 -- 选择视觉系统或显式图标前，请阅读[主题与图标](../language/themes-and-icons)。 +- **与编程智能体协作：** 安装可选的[Stack技能](./coding-agents)，使用共享的检查与渲染流程。 +- **从示例开始：** 在Playground中打开[实时渲染的示例](../examples/)，再尝试[主题与图标](../language/themes-and-icons)。 +- **适配你的环境：** [导入供应商图标](./provider-icons)，然后通过[CLI配置指南](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)选择本地存储位置。这些配置属于CLI；浏览器需要显式导入本地图标包。 +- **查阅细节：** 描述更大的系统时，参考[语言文档](../language/syntax)和[诊断与限制](../reference/diagnostics-and-limits)。 ## 更新或卸载 diff --git a/content/site/zh/guide/what-is-stack.md b/content/site/zh/guide/what-is-stack.md index c505901..bd8e390 100644 --- a/content/site/zh/guide/what-is-stack.md +++ b/content/site/zh/guide/what-is-stack.md @@ -31,12 +31,9 @@ diagram "Service architecture" { ## Stack 的设计目标 -- **简洁编写：** 只需命名节点和连线即可得到有用的图。 -- **可预测生成：** 人和语言模型都能用一种受约束的方式稳定表达概念。 -- **语义源文件：** 记录拓扑和意图，而不是像素。 -- **一致输出：** 渲染器拥有统一的视觉系统。 -- **可操作错误：** 诊断可指向源码范围，并给出候选值、修复帮助和相关声明。 -- **安全嵌入：** 源文件不能执行代码、获取任意资源或注入 HTML/SVG。 +{{productBenefits}} + +一致的结果要求引擎版本、源文件、主题和图标包相同。渲染在本地完成，但安装工具、加载网站以及主动导入供应商图标可能需要网络。具体边界请参阅[版本与安全](../reference/versioning-and-safety)。 ## Stack 不是什么 diff --git a/content/site/zh/index.md b/content/site/zh/index.md index 7df8d09..10ff1f9 100644 --- a/content/site/zh/index.md +++ b/content/site/zh/index.md @@ -1,27 +1,4 @@ --- layout: home - -hero: - name: Stack - text: 将架构写成源代码。 - tagline: 编写一份简洁的语义文档，无需指定坐标或逐个设置方框样式，即可生成一致且无障碍的架构图。 - image: - light: /favicon.svg - dark: /favicon.svg - alt: Stack 标志 - actions: - - theme: brand - text: 快速开始 - link: /zh/guide/getting-started - - theme: alt - text: 打开 Playground - link: https://stack-diagram.com/ - -features: - - title: 描述系统 - details: 用简洁、可读的 .stack 文件记录节点、分组、关系和布局意图。 - - title: 保持语义可移植 - details: 带版本的语言和结构化诊断将架构语义与渲染器选择分离。 - - title: 安全渲染 - details: 引擎生成不含脚本、任意 HTML 或网络资源的独立 SVG。 +{{productHome}} --- diff --git a/generated/manifest.json b/generated/manifest.json index dc758c2..efa0e3c 100644 --- a/generated/manifest.json +++ b/generated/manifest.json @@ -24,7 +24,7 @@ }, { "path": "site/guide/getting-started.md", - "sha256": "b9e21a3fcf5c8de6360dcf060cbf2b05099f0e55dda1186f1ea3700740e0a860" + "sha256": "e673678a7fe76d608f290babaf073c57b98fd03fce166c732d86feb50e4c5d8f" }, { "path": "site/guide/playground.md", @@ -36,11 +36,11 @@ }, { "path": "site/guide/what-is-stack.md", - "sha256": "ab46e1a9652452dbdb9502726451ae42c926036bb3faa3639605e562d994d1e2" + "sha256": "b02d56c6f26c656f27ee4e90ba36edbe74268eaa1d878137c3ade8ee7a76222f" }, { "path": "site/index.md", - "sha256": "2c7a4c60b27975c811efd7a6323d16791b16e8b713bfd2eac03d4f14dfdf4e70" + "sha256": "354a80ed32a22a7afd0817ad323a601b0cde58c5f6d9c488bac6cd3b1ef5685c" }, { "path": "site/ja/examples/index.md", @@ -52,7 +52,7 @@ }, { "path": "site/ja/guide/getting-started.md", - "sha256": "bae22b095cc22279e48494213748d1b0413eddec9893b261c73159267c27875d" + "sha256": "729e59c32a554f6efa6559e6e57811fb494813e8bd68b3e919b90dac7e16bbd6" }, { "path": "site/ja/guide/playground.md", @@ -64,11 +64,11 @@ }, { "path": "site/ja/guide/what-is-stack.md", - "sha256": "1206d992d898f626d7505ae64d494513175bb53766845006a5921e7d32e44b25" + "sha256": "0832ffffadd5db80ab613f96cd2e88bb76cec54722ef5b430119e97642f083d5" }, { "path": "site/ja/index.md", - "sha256": "0e24d302a65bcaa7cfcc7793c6d059449514ddedfff2e14dbc07ff993dfe147c" + "sha256": "cc3f5cffe10077e4fa94b7a34a43bb4627d9d4e7340d9741563ffb868206923e" }, { "path": "site/ja/language/edges-and-layout.md", @@ -108,7 +108,7 @@ }, { "path": "site/ko/guide/getting-started.md", - "sha256": "0e55e18cc77bfa6ffb2598ecfc69b1884a8e0380e54953860cbfa1e01ebcd58b" + "sha256": "667080b1012bc67514abe3827d9ff166e7c50dfd0fc7ac3be36d2ef73b801540" }, { "path": "site/ko/guide/playground.md", @@ -120,11 +120,11 @@ }, { "path": "site/ko/guide/what-is-stack.md", - "sha256": "cc1e807ac44f57af084a6b87bdccb3ecb5484462ebd5852be3b97692d66d3f86" + "sha256": "4557a1ee3fc7f1a73e26d8da38299c50cb563f1f492ae421f68c63ff0198a029" }, { "path": "site/ko/index.md", - "sha256": "1d625195c05e182786ecec258e4ca994429bf6f39ea3068b4429befe3cf2211d" + "sha256": "973f42eaa34720743f80eef15af3ed684e2c9c8bf7ecd84bbaad084bca166564" }, { "path": "site/ko/language/edges-and-layout.md", @@ -192,7 +192,7 @@ }, { "path": "site/zh/guide/getting-started.md", - "sha256": "88100e9090603b3eb07fad7e7b32f066cede0cfcc306e28ecb4ed852b9a850e1" + "sha256": "2347ab5ddc5196f30287726eac5294b07b81d2c9cf543335751dd62dcc8e1613" }, { "path": "site/zh/guide/playground.md", @@ -204,11 +204,11 @@ }, { "path": "site/zh/guide/what-is-stack.md", - "sha256": "d616fb3b5b2324c9892a3f593f0e3b2f92d0fb338300ba2ebf3488022aa9634b" + "sha256": "763078612cb5b7e6c9871081a7baec2b6b1c26845af6c72ea3fd153f9c38801f" }, { "path": "site/zh/index.md", - "sha256": "432a5667dd51c297e2a415f3fca9438d8cfd7ed4b02d8946fc863548363f228d" + "sha256": "0a7bd5635557f0924ff3098513deb4bcec8bd0006c87a9a80e49ebf6acc15fba" }, { "path": "site/zh/language/edges-and-layout.md", diff --git a/generated/site/guide/getting-started.md b/generated/site/guide/getting-started.md index c5c57c6..8464378 100644 --- a/generated/site/guide/getting-started.md +++ b/generated/site/guide/getting-started.md @@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack ## Write your first document -Replace the editor content with this example: +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: ```stack stack 1.0 @@ -196,10 +196,10 @@ If Stack finds a problem, the diagnostic shows its severity, stable code, locati ## Choose what to learn next -- Read [Document and syntax](../language/syntax) for lexical rules and the complete grammar. -- Read [Nodes and groups](../language/nodes-and-groups) to model components and boundaries. -- Read [Edges and layout](../language/edges-and-layout) for relationships and placement intent. -- Read [Themes and icons](../language/themes-and-icons) before selecting a visual system or explicit icon. +- **Write with your coding agent:** install the optional [Stack skill](./coding-agents) and use the shared check/render workflow. +- **Find a starting point:** open a [live example](../examples/) in the Playground, then explore [themes and icons](../language/themes-and-icons). +- **Use your own setup:** [import provider icons](./provider-icons), then choose their local store through the [CLI configuration guide](https://github.com/stack-sh/cli/blob/main/docs/configuration.md). Configuration is a CLI contract; the browser uses explicit local pack import. +- **Look up the details:** use the [language reference](../language/syntax) and [diagnostics and limits](../reference/diagnostics-and-limits) as you model a larger system. ## Update or uninstall diff --git a/generated/site/guide/what-is-stack.md b/generated/site/guide/what-is-stack.md index bf3ea0a..69f9929 100644 --- a/generated/site/guide/what-is-stack.md +++ b/generated/site/guide/what-is-stack.md @@ -31,12 +31,11 @@ The document says that a client calls a service. It does not say where either bo ## What Stack optimizes for -- **Concise authoring:** useful diagrams need little more than named nodes and edges. -- **Predictable generation:** each concept has one constrained representation that people and language models can produce reliably. -- **Semantic source:** a document records topology and intent, not pixels. -- **Polished output:** the renderer owns a coherent visual system. -- **Actionable errors:** diagnostics point to source ranges and can include expected values, corrective help, and related declarations. -- **Safe embedding:** source cannot execute code, fetch arbitrary assets, or inject HTML or SVG. +- **Beautiful by default:** Describe the system, not every box. Automatic layout and coordinated themes keep your diagrams polished without manual positioning or styling. +- **Consistent everywhere:** Move between your coding agent, terminal, and browser. The shared engine keeps the same source, theme, and icon packs consistent across workflows. +- **Fast, local rendering:** Edit, render, and repeat without a rendering server. Keep your source on your device and export standalone SVG without scripts or external assets. + +Consistency assumes matching engine versions and the same source, theme, and icon packs. Rendering stays local; installing tools, loading the website, and explicitly importing provider icons can require network access. See [versioning and safety](../reference/versioning-and-safety) for the exact boundaries. ## What Stack is not diff --git a/generated/site/index.md b/generated/site/index.md index 3bdf0f3..aa01eb4 100644 --- a/generated/site/index.md +++ b/generated/site/index.md @@ -1,27 +1,6 @@ --- layout: home - -hero: - name: Stack - text: Architecture, as source. - tagline: Write a small, semantic document. Get a consistent, accessible architecture diagram without drawing coordinates or styling every box. - image: - light: /favicon.svg - dark: /favicon.svg - alt: Stack logo - actions: - - theme: brand - text: Get started - link: /guide/getting-started - - theme: alt - text: Open Playground - link: https://stack-diagram.com/ - -features: - - title: Describe the system - details: Nodes, groups, relationships, and layout intent stay readable in a compact .stack file. - - title: Keep meaning portable - details: A versioned language and structured diagnostics separate architecture meaning from renderer choices. - - title: Render safely - details: The engine produces standalone SVG without scripts, arbitrary HTML, or network-loaded assets. +description: "Describe your services and connections in text. Stack handles layout and theming, then renders a shareable SVG in your terminal or browser." +hero: {"name":"Stack","tagline":"Write your stack. Get a beautiful diagram.","image":{"light":"/favicon.svg","dark":"/favicon.svg","alt":"Stack logo"},"actions":[{"theme":"brand","text":"Create your first diagram","link":"/guide/getting-started"},{"theme":"alt","text":"Try the Playground","link":"https://stack-diagram.com/"}]} +features: [{"title":"Beautiful by default","details":"Describe the system, not every box. Automatic layout and coordinated themes keep your diagrams polished without manual positioning or styling."},{"title":"Consistent everywhere","details":"Move between your coding agent, terminal, and browser. The shared engine keeps the same source, theme, and icon packs consistent across workflows."},{"title":"Fast, local rendering","details":"Edit, render, and repeat without a rendering server. Keep your source on your device and export standalone SVG without scripts or external assets."}] --- diff --git a/generated/site/ja/guide/getting-started.md b/generated/site/ja/guide/getting-started.md index 739368d..ccd197b 100644 --- a/generated/site/ja/guide/getting-started.md +++ b/generated/site/ja/guide/getting-started.md @@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack ## 最初のdocumentを書く -Editorを次のexampleへ置き換えます。 +ブラウザで試す場合は[Playground](https://stack-diagram.com/)を開き、エディタを次の作例に置き換えます。CLIの場合は同じソースを`diagram.stack`として保存し、上の検証・描画コマンドを実行できます。 ```stack stack 1.0 @@ -196,10 +196,10 @@ Sourceは4つの要素で構成されています。 ## 次に読むもの -- Lexical ruleと完全なgrammarは[Documentとsyntax](../language/syntax)を参照します。 -- Componentとboundaryは[Nodeとgroup](../language/nodes-and-groups)を参照します。 -- Relationshipと配置intentは[Edgeとlayout](../language/edges-and-layout)を参照します。 -- Visual systemや明示iconを選ぶ前に[Themeとicon](../language/themes-and-icons)を参照します。 +- **Coding agentと書く:** 任意の[Stackスキル](./coding-agents)を導入し、共通の検証・描画手順を使います。 +- **作例から始める:** [実行時に描画される作例](../examples/)をPlaygroundで開き、[テーマとアイコン](../language/themes-and-icons)を試します。 +- **自分の環境に合わせる:** [プロバイダーアイコンを取り込み](./provider-icons)、[CLI設定ガイド](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)で保存先を選びます。この設定はCLI用です。ブラウザではローカルのパックを明示的に読み込みます。 +- **詳しく調べる:** [言語リファレンス](../language/syntax)と[診断・制限](../reference/diagnostics-and-limits)を参照しながら、より大きなシステムを記述します。 ## 更新・アンインストール diff --git a/generated/site/ja/guide/what-is-stack.md b/generated/site/ja/guide/what-is-stack.md index b6117c2..3f2a125 100644 --- a/generated/site/ja/guide/what-is-stack.md +++ b/generated/site/ja/guide/what-is-stack.md @@ -31,12 +31,11 @@ diagram "Service architecture" { ## Stackが重視すること -- **簡潔なauthoring:** 名前付きnodeとedgeだけで有用なdiagramを書けます。 -- **予測可能な生成:** 人とlanguage modelが同じconceptを安定して記述できます。 -- **Semantic source:** Pixelではなくtopologyとintentを記録します。 -- **整ったoutput:** 一貫したvisual systemをrendererが所有します。 -- **修正可能なerror:** Diagnosticはsource range、expected value、help、related declarationを示せます。 -- **安全な埋め込み:** Sourceはcode実行、任意asset取得、HTML/SVG注入ができません。 +- **書くだけで、見た目が整う:** 箱の位置や色ではなく、システムの構成に集中。自動配置と統一されたテーマで、手作業で整えなくても見やすい図になります。 +- **どこで作っても、一貫した図に:** Coding agent、ターミナル、ブラウザを行き来しても大丈夫。共通のエンジンが、同じソース・テーマ・アイコンパックから一貫した図を生成します。 +- **手元で、すばやく描画:** 描画サーバーを介さず、書いて、描いて、すぐ見直す。ソースは手元に置いたまま、スクリプトや外部アセットを含まないSVGを書き出せます。 + +一貫した結果には、同じエンジンのバージョン・ソース・テーマ・アイコンパックが必要です。描画は手元で行いますが、ツールの導入、サイトの読み込み、明示的なプロバイダーアイコンの取り込みにはネットワークを使う場合があります。詳しい境界は[バージョニングと安全性](../reference/versioning-and-safety)を参照してください。 ## Stackではないもの diff --git a/generated/site/ja/index.md b/generated/site/ja/index.md index dafd1ac..f982f85 100644 --- a/generated/site/ja/index.md +++ b/generated/site/ja/index.md @@ -1,27 +1,6 @@ --- layout: home - -hero: - name: Stack - text: Architectureをsourceとして。 - tagline: 小さなsemantic documentを書くだけで、座標やboxごとのstyleを指定せず、一貫したaccessibleなarchitecture diagramを生成できます。 - image: - light: /favicon.svg - dark: /favicon.svg - alt: Stackロゴ - actions: - - theme: brand - text: はじめる - link: /ja/guide/getting-started - - theme: alt - text: Playgroundを開く - link: https://stack-diagram.com/ - -features: - - title: Systemを記述する - details: Node、group、relationship、layout intentを、簡潔な.stack fileとして読みやすく保ちます。 - - title: 意味をportableにする - details: Version付きlanguageとstructured diagnosticが、architectureの意味をrendererの選択から分離します。 - - title: 安全にrenderする - details: Script、任意HTML、network assetを含まないstandalone SVGをengineが生成します。 +description: "サービスとつながりをテキストで記述。Stackが配置とテーマを整え、ターミナルでもブラウザでも共有できるSVGを生成します。" +hero: {"name":"Stack","tagline":"構成を書くだけで、美しい図に。","image":{"light":"/favicon.svg","dark":"/favicon.svg","alt":"Stackロゴ"},"actions":[{"theme":"brand","text":"最初の図を作る","link":"/ja/guide/getting-started"},{"theme":"alt","text":"Playgroundで試す","link":"https://stack-diagram.com/"}]} +features: [{"title":"書くだけで、見た目が整う","details":"箱の位置や色ではなく、システムの構成に集中。自動配置と統一されたテーマで、手作業で整えなくても見やすい図になります。"},{"title":"どこで作っても、一貫した図に","details":"Coding agent、ターミナル、ブラウザを行き来しても大丈夫。共通のエンジンが、同じソース・テーマ・アイコンパックから一貫した図を生成します。"},{"title":"手元で、すばやく描画","details":"描画サーバーを介さず、書いて、描いて、すぐ見直す。ソースは手元に置いたまま、スクリプトや外部アセットを含まないSVGを書き出せます。"}] --- diff --git a/generated/site/ko/guide/getting-started.md b/generated/site/ko/guide/getting-started.md index 0676f47..081504e 100644 --- a/generated/site/ko/guide/getting-started.md +++ b/generated/site/ko/guide/getting-started.md @@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack ## 첫 문서 작성 -에디터 내용을 다음 예제로 바꿉니다. +브라우저에서 체험하려면 [Playground](https://stack-diagram.com/)를 열고 에디터 내용을 다음 예제로 바꾸세요. CLI 사용자는 같은 소스를 `diagram.stack`으로 저장한 뒤 위의 검사·렌더링 명령을 다시 실행할 수 있습니다. ```stack stack 1.0 @@ -196,10 +196,10 @@ diagram "Checkout" { ## 다음으로 읽을 내용 -- 어휘 규칙과 전체 문법은 [문서와 문법](../language/syntax)을 참고하세요. -- 컴포넌트와 경계는 [노드와 그룹](../language/nodes-and-groups)을 참고하세요. -- 관계와 배치 의도는 [엣지와 레이아웃](../language/edges-and-layout)을 참고하세요. -- 시각 시스템이나 명시적 아이콘을 고르기 전에 [테마와 아이콘](../language/themes-and-icons)을 읽으세요. +- **코딩 에이전트와 작성하기:** 선택 사항인 [Stack 스킬](./coding-agents)을 설치하고 공통 검사·렌더링 흐름을 사용하세요. +- **예제에서 시작하기:** [실시간 렌더링 예제](../examples/)를 Playground에서 열고 [테마와 아이콘](../language/themes-and-icons)을 살펴보세요. +- **내 환경에 맞추기:** [공급자 아이콘을 가져온](./provider-icons) 다음 [CLI 설정 가이드](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)에서 로컬 저장소를 선택하세요. 이 설정은 CLI용이며, 브라우저에서는 로컬 팩을 명시적으로 가져옵니다. +- **세부 사항 찾아보기:** 더 큰 시스템을 모델링할 때 [언어 레퍼런스](../language/syntax)와 [진단과 제한](../reference/diagnostics-and-limits)을 참고하세요. ## 업데이트 또는 제거 diff --git a/generated/site/ko/guide/what-is-stack.md b/generated/site/ko/guide/what-is-stack.md index a5af2c5..0d45f4e 100644 --- a/generated/site/ko/guide/what-is-stack.md +++ b/generated/site/ko/guide/what-is-stack.md @@ -31,12 +31,11 @@ diagram "Service architecture" { ## Stack의 설계 목표 -- **간결한 작성:** 이름이 있는 노드와 엣지만으로 유용한 다이어그램을 만듭니다. -- **예측 가능한 생성:** 사람과 언어 모델이 같은 개념을 하나의 제한된 방식으로 안정적으로 표현합니다. -- **의미 기반 소스:** 픽셀이 아니라 토폴로지와 의도를 기록합니다. -- **정돈된 출력:** 렌더러가 일관된 시각 시스템을 소유합니다. -- **실행 가능한 오류:** 진단은 소스 범위, 예상 값, 수정 도움말, 관련 선언을 제공할 수 있습니다. -- **안전한 임베딩:** 소스는 코드를 실행하거나 임의 에셋을 가져오거나 HTML/SVG를 삽입할 수 없습니다. +- **직접 꾸미지 않아도 아름답게:** 박스 하나하나가 아닌 시스템을 설명하세요. 자동 배치와 조화로운 테마로 위치와 스타일을 수작업으로 조정하지 않아도 정돈된 다이어그램을 만듭니다. +- **어디서나 일관된 결과:** 코딩 에이전트, 터미널, 브라우저를 자유롭게 오가세요. 공유 엔진이 같은 소스, 테마, 아이콘 팩을 다양한 작업 환경에서 일관되게 렌더링합니다. +- **내 기기에서 빠르게 렌더링:** 렌더링 서버 없이 수정하고, 그리고, 다시 확인하세요. 소스를 내 기기에 둔 채 스크립트나 외부 에셋이 없는 독립형 SVG로 내보낼 수 있습니다. + +일관된 결과를 얻으려면 엔진 버전, 소스, 테마, 아이콘 팩이 같아야 합니다. 렌더링은 로컬에서 수행되지만 도구 설치, 웹사이트 로딩, 명시적인 공급자 아이콘 가져오기에는 네트워크가 필요할 수 있습니다. 정확한 범위는 [버전과 안전성](../reference/versioning-and-safety)을 참고하세요. ## Stack이 아닌 것 diff --git a/generated/site/ko/index.md b/generated/site/ko/index.md index 13a1514..292af3c 100644 --- a/generated/site/ko/index.md +++ b/generated/site/ko/index.md @@ -1,27 +1,6 @@ --- layout: home - -hero: - name: Stack - text: 아키텍처를 소스로. - tagline: 작은 의미 기반 문서를 작성하면 좌표나 박스별 스타일을 지정하지 않아도 일관되고 접근 가능한 아키텍처 다이어그램을 만들 수 있습니다. - image: - light: /favicon.svg - dark: /favicon.svg - alt: Stack 로고 - actions: - - theme: brand - text: 시작하기 - link: /ko/guide/getting-started - - theme: alt - text: Playground 열기 - link: https://stack-diagram.com/ - -features: - - title: 시스템 설명 - details: 노드, 그룹, 관계, 레이아웃 의도를 간결하고 읽기 쉬운 .stack 파일로 유지합니다. - - title: 의미의 이식성 - details: 버전이 있는 언어와 구조화된 진단이 아키텍처 의미를 렌더러 선택과 분리합니다. - - title: 안전한 렌더링 - details: 엔진은 스크립트, 임의 HTML, 네트워크 에셋이 없는 독립형 SVG를 생성합니다. +description: "서비스와 연결을 텍스트로 설명하세요. Stack이 배치와 테마를 정리하고, 터미널이나 브라우저에서 공유할 수 있는 SVG를 만듭니다." +hero: {"name":"Stack","tagline":"구성을 쓰면, 아름다운 다이어그램으로.","image":{"light":"/favicon.svg","dark":"/favicon.svg","alt":"Stack 로고"},"actions":[{"theme":"brand","text":"첫 다이어그램 만들기","link":"/ko/guide/getting-started"},{"theme":"alt","text":"Playground에서 체험하기","link":"https://stack-diagram.com/"}]} +features: [{"title":"직접 꾸미지 않아도 아름답게","details":"박스 하나하나가 아닌 시스템을 설명하세요. 자동 배치와 조화로운 테마로 위치와 스타일을 수작업으로 조정하지 않아도 정돈된 다이어그램을 만듭니다."},{"title":"어디서나 일관된 결과","details":"코딩 에이전트, 터미널, 브라우저를 자유롭게 오가세요. 공유 엔진이 같은 소스, 테마, 아이콘 팩을 다양한 작업 환경에서 일관되게 렌더링합니다."},{"title":"내 기기에서 빠르게 렌더링","details":"렌더링 서버 없이 수정하고, 그리고, 다시 확인하세요. 소스를 내 기기에 둔 채 스크립트나 외부 에셋이 없는 독립형 SVG로 내보낼 수 있습니다."}] --- diff --git a/generated/site/zh/guide/getting-started.md b/generated/site/zh/guide/getting-started.md index e5a5220..4f943f1 100644 --- a/generated/site/zh/guide/getting-started.md +++ b/generated/site/zh/guide/getting-started.md @@ -124,7 +124,7 @@ $ stack fmt --check diagram.stack ## 编写第一份文档 -将编辑器内容替换为下面的示例： +在浏览器中试用时，打开[Playground](https://stack-diagram.com/)，将编辑器内容替换为下面的示例。CLI用户可以将相同源文件保存为`diagram.stack`，然后再次执行上面的检查与渲染命令： ```stack stack 1.0 @@ -196,10 +196,10 @@ diagram "Checkout" { ## 接下来阅读 -- [文档与语法](../language/syntax)介绍词法规则和完整语法。 -- [节点与分组](../language/nodes-and-groups)介绍组件和边界建模。 -- [连线与布局](../language/edges-and-layout)介绍关系和布局意图。 -- 选择视觉系统或显式图标前，请阅读[主题与图标](../language/themes-and-icons)。 +- **与编程智能体协作：** 安装可选的[Stack技能](./coding-agents)，使用共享的检查与渲染流程。 +- **从示例开始：** 在Playground中打开[实时渲染的示例](../examples/)，再尝试[主题与图标](../language/themes-and-icons)。 +- **适配你的环境：** [导入供应商图标](./provider-icons)，然后通过[CLI配置指南](https://github.com/stack-sh/cli/blob/main/docs/configuration.md)选择本地存储位置。这些配置属于CLI；浏览器需要显式导入本地图标包。 +- **查阅细节：** 描述更大的系统时，参考[语言文档](../language/syntax)和[诊断与限制](../reference/diagnostics-and-limits)。 ## 更新或卸载 diff --git a/generated/site/zh/guide/what-is-stack.md b/generated/site/zh/guide/what-is-stack.md index c505901..20b105e 100644 --- a/generated/site/zh/guide/what-is-stack.md +++ b/generated/site/zh/guide/what-is-stack.md @@ -31,12 +31,11 @@ diagram "Service architecture" { ## Stack 的设计目标 -- **简洁编写：** 只需命名节点和连线即可得到有用的图。 -- **可预测生成：** 人和语言模型都能用一种受约束的方式稳定表达概念。 -- **语义源文件：** 记录拓扑和意图，而不是像素。 -- **一致输出：** 渲染器拥有统一的视觉系统。 -- **可操作错误：** 诊断可指向源码范围，并给出候选值、修复帮助和相关声明。 -- **安全嵌入：** 源文件不能执行代码、获取任意资源或注入 HTML/SVG。 +- **无需手动美化:** 专注描述系统，不必逐个调整方框。自动布局和协调的主题让图表保持清晰美观，无需手动定位或设置样式。 +- **不同工具，一致呈现:** 在编程智能体、终端和浏览器之间自由切换。共享引擎让相同源文件、主题和图标包在不同工作流程中保持一致。 +- **本地快速渲染:** 无需渲染服务器，修改后即可再次生成。源文件留在你的设备上，并可导出不含脚本或外部资源的独立SVG。 + +一致的结果要求引擎版本、源文件、主题和图标包相同。渲染在本地完成，但安装工具、加载网站以及主动导入供应商图标可能需要网络。具体边界请参阅[版本与安全](../reference/versioning-and-safety)。 ## Stack 不是什么 diff --git a/generated/site/zh/index.md b/generated/site/zh/index.md index 7df8d09..436f9e3 100644 --- a/generated/site/zh/index.md +++ b/generated/site/zh/index.md @@ -1,27 +1,6 @@ --- layout: home - -hero: - name: Stack - text: 将架构写成源代码。 - tagline: 编写一份简洁的语义文档，无需指定坐标或逐个设置方框样式，即可生成一致且无障碍的架构图。 - image: - light: /favicon.svg - dark: /favicon.svg - alt: Stack 标志 - actions: - - theme: brand - text: 快速开始 - link: /zh/guide/getting-started - - theme: alt - text: 打开 Playground - link: https://stack-diagram.com/ - -features: - - title: 描述系统 - details: 用简洁、可读的 .stack 文件记录节点、分组、关系和布局意图。 - - title: 保持语义可移植 - details: 带版本的语言和结构化诊断将架构语义与渲染器选择分离。 - - title: 安全渲染 - details: 引擎生成不含脚本、任意 HTML 或网络资源的独立 SVG。 +description: "用文本描述服务及其连接。Stack负责布局和主题，在终端或浏览器中生成可分享的SVG。" +hero: {"name":"Stack","tagline":"写下技术架构，得到精美图表。","image":{"light":"/favicon.svg","dark":"/favicon.svg","alt":"Stack标志"},"actions":[{"theme":"brand","text":"创建第一张图","link":"/zh/guide/getting-started"},{"theme":"alt","text":"试用Playground","link":"https://stack-diagram.com/"}]} +features: [{"title":"无需手动美化","details":"专注描述系统，不必逐个调整方框。自动布局和协调的主题让图表保持清晰美观，无需手动定位或设置样式。"},{"title":"不同工具，一致呈现","details":"在编程智能体、终端和浏览器之间自由切换。共享引擎让相同源文件、主题和图标包在不同工作流程中保持一致。"},{"title":"本地快速渲染","details":"无需渲染服务器，修改后即可再次生成。源文件留在你的设备上，并可导出不含脚本或外部资源的独立SVG。"}] --- diff --git a/scripts/generate.mjs b/scripts/generate.mjs index 0b3cf87..51c42dd 100644 --- a/scripts/generate.mjs +++ b/scripts/generate.mjs @@ -4,6 +4,7 @@ import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { generateMachineResources } from './machine-resources.mjs'; +import { productCopy, productTokens } from './product-story.mjs'; const root = fileURLToPath(new URL('../', import.meta.url)); @@ -50,10 +51,15 @@ export async function generate(directory = root, check = false) { const siteFiles = await filePaths(siteRoot); if (siteFiles.length > 0) { const prompt = (await readFile(path.join(directory, 'content/agent-prompt.txt'), 'utf8')).trimEnd(); + const story = JSON.parse(await readFile(path.join(directory, 'content/product-story.json'), 'utf8')); + const translations = JSON.parse(await readFile(path.join(directory, 'content/product-story-locales.json'), 'utf8')); for (const file of siteFiles) { assert.ok(file.endsWith('.md'), `Only Markdown source is supported: ${file}`); const source = await readFile(path.join(siteRoot, file), 'utf8'); - const rendered = source.replaceAll('{{cliVersion}}', release.version).replaceAll('{{agentPrompt}}', prompt); + const locale = file.match(/^(ja|zh|ko)\//)?.[1] ?? 'en'; + const tokens = { cliVersion: release.version, agentPrompt: prompt, ...productTokens(productCopy(story, translations, locale)) }; + let rendered = source; + for (const [key, value] of Object.entries(tokens)) rendered = rendered.replaceAll(`{{${key}}}`, value); assert.ok(!/\{\{[^}]+\}\}/.test(rendered), `Unknown site template token: ${file}`); outputs[`site/${file}`] = rendered; } diff --git a/scripts/generate.test.mjs b/scripts/generate.test.mjs index ee4bf6d..652b798 100644 --- a/scripts/generate.test.mjs +++ b/scripts/generate.test.mjs @@ -42,6 +42,21 @@ test('release lock updates all rendered version references', async t => { } }); +test('canonical story changes reach the home and introduction without duplicating copy', async t => { + const directory = await fixture(t); + const storyPath = path.join(directory, 'content/product-story.json'); + const story = JSON.parse(await readFile(storyPath, 'utf8')); + story.features[0].title = 'Updated canonical benefit'; + story.hero.tagline = 'A revised tagline.'; + await writeFile(storyPath, JSON.stringify(story)); + const outputs = await generate(directory); + assert.ok(outputs['site/index.md'].includes('A revised tagline.')); + assert.ok(outputs['site/index.md'].includes('Updated canonical benefit')); + assert.ok(outputs['site/guide/what-is-stack.md'].includes('Updated canonical benefit')); + for (const locale of ['ja', 'zh', 'ko']) assert.ok(!outputs[`site/${locale}/index.md`].includes('Updated canonical benefit')); + await generate(directory, true); +}); + test('check rejects modified, missing, and unexpected generated files', async t => { const directory = await fixture(t); await generate(directory); @@ -74,6 +89,10 @@ test('all four locales expose the same page set and shared copyable instruction' for (const page of englishPages) assert.ok(outputs[`site/${locale}${page}`], `Missing ${locale}${page}`); assert.ok(outputs[`site/${locale}guide/coding-agents.md`].includes(prompt)); assert.equal(outputs[`site/${locale}guide/agent-workflow.md`].replace(/^\$ /gm, ''), outputs['guide/agent-workflow.md']); + const gettingStarted = outputs[`site/${locale}guide/getting-started.md`]; + for (const destination of ['./coding-agents', '../examples/', './provider-icons', '../language/syntax', '../reference/diagnostics-and-limits', 'https://github.com/stack-sh/cli/blob/main/docs/configuration.md']) { + assert.ok(gettingStarted.includes(`](${destination})`), `Missing next step: ${locale}${destination}`); + } } assert.equal(Object.keys(outputs).filter(file => file.startsWith('site/')).length, 60); }); diff --git a/scripts/product-story.mjs b/scripts/product-story.mjs new file mode 100644 index 0000000..2cf8c87 --- /dev/null +++ b/scripts/product-story.mjs @@ -0,0 +1,45 @@ +import assert from 'node:assert/strict'; + +export function productCopy(story, translations, locale) { + assert.equal(story.hero.name, 'Stack'); + assert.equal(story.features.length, 3); + assert.deepEqual(Object.keys(translations).sort(), ['ja', 'ko', 'zh']); + assert.ok(['en', 'ja', 'zh', 'ko'].includes(locale), `Unknown product locale: ${locale}`); + const ids = story.features.map(feature => feature.id); + assert.equal(new Set(ids).size, 3); + for (const translation of Object.values(translations)) { + assert.deepEqual(Object.keys(translation.features).sort(), [...ids].sort(), 'Translated benefit inventory drift'); + for (const key of ['tagline', 'description', 'primaryActionText', 'secondaryActionText', 'logoAlt']) { + assert.ok(typeof translation.hero[key] === 'string' && translation.hero[key].trim().length > 0, `Missing translated hero ${key}`); + } + for (const feature of Object.values(translation.features)) { + for (const key of ['title', 'details']) assert.ok(typeof feature[key] === 'string' && feature[key].trim().length > 0, `Missing translated benefit ${key}`); + } + } + const translated = locale === 'en' ? null : translations[locale]; + const prefix = locale === 'en' ? '' : `/${locale}`; + return { + description: translated?.hero.description ?? story.hero.description, + hero: { + name: story.hero.name, + tagline: translated?.hero.tagline ?? story.hero.tagline, + image: { light: '/favicon.svg', dark: '/favicon.svg', alt: translated?.hero.logoAlt ?? 'Stack logo' }, + actions: [ + { theme: 'brand', text: translated?.hero.primaryActionText ?? story.hero.primaryAction.text, link: prefix + story.hero.primaryAction.link }, + { theme: 'alt', text: translated?.hero.secondaryActionText ?? story.hero.secondaryAction.text, link: story.hero.secondaryAction.link }, + ], + }, + features: story.features.map(feature => ({ + title: translated?.features[feature.id].title ?? feature.title, + details: translated?.features[feature.id].details ?? feature.details, + })), + }; +} + +export function productTokens(copy) { + return { + // JSON is valid YAML, so punctuation and translated strings remain escaped safely. + productHome: Object.entries(copy).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join('\n'), + productBenefits: copy.features.map(feature => `- **${feature.title}:** ${feature.details}`).join('\n'), + }; +} diff --git a/scripts/product-story.test.mjs b/scripts/product-story.test.mjs index a1a1552..8e09d24 100644 --- a/scripts/product-story.test.mjs +++ b/scripts/product-story.test.mjs @@ -1,6 +1,7 @@ import assert from 'node:assert/strict'; import { readFile } from 'node:fs/promises'; import test from 'node:test'; +import { productCopy, productTokens } from './product-story.mjs'; test('canonical story has one product heading, three evidenced benefits, and both first-success paths', async () => { const story = JSON.parse(await readFile(new URL('../content/product-story.json', import.meta.url), 'utf8')); @@ -21,3 +22,27 @@ test('canonical story has one product heading, three evidenced benefits, and bot assert.match(story.claimBoundaries.join('\n'), /matching engine versions/); assert.match(story.claimBoundaries.join('\n'), /runtime/); }); + +test('localized homepage metadata keeps H1 product-only and exactly three matching benefits', async () => { + const story = JSON.parse(await readFile(new URL('../content/product-story.json', import.meta.url), 'utf8')); + const translations = JSON.parse(await readFile(new URL('../content/product-story-locales.json', import.meta.url), 'utf8')); + for (const locale of ['en', 'ja', 'zh', 'ko']) { + const copy = productCopy(story, translations, locale); + assert.equal(copy.hero.name, 'Stack'); + assert.equal(copy.hero.text, undefined); + assert.equal(copy.features.length, 3); + assert.equal(copy.hero.actions[0].link, `${locale === 'en' ? '' : `/${locale}`}/guide/getting-started`); + assert.equal(copy.hero.actions[1].link, 'https://stack-diagram.com/'); + assert.ok(copy.description.length > 0 && copy.description.length <= 160); + const tokens = productTokens(copy); + assert.ok(tokens.productBenefits.includes(copy.features[0].title)); + assert.equal(JSON.parse(tokens.productHome.split('\n')[1].slice(6)).name, 'Stack'); + } + assert.throws(() => productCopy(story, translations, 'fr'), /Unknown/); + const incomplete = structuredClone(translations); + delete incomplete.ja.features['fast-local-rendering']; + assert.throws(() => productCopy(story, incomplete, 'ja'), /inventory drift/); + const empty = structuredClone(translations); + empty.ko.hero.tagline = ''; + assert.throws(() => productCopy(story, empty, 'ko'), /Missing translated/); +});