企业官网建设流程全解析

LikeC4 文档站维护指南：DSL 新增 Shape 后如何四步同步文档、示例与语法高亮

【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4

本文以仓库中的 Agent 指引文档 .claude/update-docs-for-dsl-changes.md 为主线，结合apps/docs文档站的真实脚本、组件与 MDX 源码，讲解当 LikeC4 DSL 发生变更（新增元素形状、调整样式属性取值等）时，文档侧需要同步哪些文件、按什么顺序操作、每一步如何验证。读完本文，你可以独立完成一次完整的“DSL 变更 → 文档站同步”流程，并理解文档站内自动生成的colors.c4、内嵌实时图示组件LikeC4ThemeView.astro以及 TextMate 语法高亮三者之间的联动关系。

文档站结构：Astro + Starlight 下的四层职责划分

LikeC4 文档站是一个Astro + Starlight应用，位于 apps/docs/ 目录。官方指引要求在开始任何文档更新前，先阅读根目录的 AGENTS.md 了解项目约定。文档站中与 DSL 变更相关的结构如下：

apps/docs/ ├── src/ │ ├── content/docs/ # MDX 文档页面（Starlight content） │ │ └── dsl/ # DSL 参考文档 │ │ ├── styling.mdx # Shape、color、size、border、opacity 等样式文档 │ │ ├── specification.mdx │ │ ├── notations.mdx │ │ ├── model.mdx │ │ └── Views/ # 视图相关文档 │ └── components/ │ └── likec4-theme/ # .c4 示例文件 + Astro 组件 │ ├── colors.c4 # 自动生成 - 全部 shape × 全部 color │ ├── allshapes.c4 # 展示主色下所有 shape 的视图 │ ├── LikeC4ThemeView.astro # 在文档中内联渲染 .c4 视图 │ └── *.c4 # 其他示例文件 ├── scripts/ │ └── generate-theme-c4.mjs # 生成 colors.c4 的脚本 ├── likec4.tmLanguage.json # 代码块的 TextMate 语法 └── package.json

这里需要说明一处与指引文档的差异：指引文档中写作scripts/generate-theme-c4.mts，而当前仓库中的实际文件是 apps/docs/scripts/generate-theme-c4.mjs，执行命令时应以实际文件名为准。

各目录职责可以概括为：

• src/content/docs/dsl/：人读的部分。styling.mdx是样式属性参考的主页面，新增形状时其中的文字列表需要手工更新；
• src/components/likec4-theme/：机器渲染的部分。.c4文件存放示例模型与视图，LikeC4ThemeView.astro负责把它们渲染成文档页面上的实时交互图；
• scripts/：生成器。只有一份generate-theme-c4.mjs，产出colors.c4；
• likec4.tmLanguage.json：让 MDX 中 ```likec4 代码块获得语法高亮。

自动生成机制：generate-theme-c4.mjs 如何产出 colors.c4

colors.c4是整个样式文档联动展示的数据源，它由脚本自动产出，头部带有// DO NOT EDIT MANUALLY标记，严禁手工编辑。脚本 generate-theme-c4.mjs 的核心逻辑分三部分：

1. 形状清单（shapes 数组）

这是新增形状时第一个要改的地方。当前脚本中的实际内容为：

const shapes = [ 'rectangle', 'component', 'browser', 'storage', 'bucket', 'person', 'mobile', 'queue', 'document', ]

2. 颜色清单（来自 core 包的主题定义）

颜色不是写死的，而是从@likec4/core包的样式导出中动态读取：

import { LikeC4Styles } from '@likec4/core/styles' const colors = Object.keys(LikeC4Styles.DEFAULT.theme.colors)

从源码结构看，这意味着当@likec4/core的主题新增或调整默认颜色时，文档侧无需修改脚本中的颜色列表，重新运行生成器即可同步——但新增形状仍必须手动加入shapes数组。

3. 生成 specification / model / views 三段结构

脚本拼接出的colors.c4内容包含：

• specification：为themecolor（带opacity 20%）以及每个形状各定义一个 element kind，kind 的style块里写shape ${shape}，即“每个形状自身作为一个元素种类”；
• model：在themecolor colors容器下为每个颜色创建一个themecolor实例，每个颜色容器内再嵌套每个形状一个实例（shape = shape { ... style { color ${key} } }），元素带 markdown 描述文本（''' ... '''）以同时展示富文本能力；
• views：
  • view index of colors（include *）：展示全部主题颜色的总览；
  • 每个形状一个视图（如view rectangle），include colors with {...}并逐色列出该形状实例，配navigateTo跳转；
  • 每个颜色一个themecolor_${key}视图，展示该颜色下所有形状。

生成后的文件写入固定路径apps/docs/src/components/likec4-theme/colors.c4，即 colors.c4。重新生成命令为：

cd apps/docs && npx tsx scripts/generate-theme-c4.mjs

新增 Element Shape 的标准四步流程

以下流程完整继承自指引文档，并结合当前仓库的实际文件做了校准。

Step 1：更新生成器脚本并重新生成 colors.c4

文件：apps/docs/scripts/generate-theme-c4.mjs

将新形状加入shapes数组（位于文件第 13–23 行附近），然后运行重新生成命令。该步骤会让colors.c4自动多出：新形状的 specification kind、每种颜色下的新形状实例、以及对应的新形状视图。

Step 2：更新 styling 参考页的文字列表

文件：apps/docs/src/content/docs/dsl/styling.mdx

找到 Shape 小节（约第 75–89 行）。当前页面第 87 行的实际文字为：

Available shapes:rectangle(default),component,storage,cylinder,browser,mobile,person,queue,bucket, anddocument.

将新形状追加进这个 prose 列表即可。紧随其后的<LikeC4ThemeView viewId="allshapes"/>组件（第 89 行）不需要改动：它渲染的allshapes视图定义在 allshapes.c4 中，内容仅为：

views { view allshapes { title "All Shapes" include colors.primary.* } }

由于include colors.primary.*是通配引用，它会自动纳入colors.c4中主色下的所有形状实例。因此只要 Step 1 重新生成了colors.c4，"All Shapes" 实时图就会自动出现新形状——这正是“文字列表要手改、图示自动生成”这一分工的由来。

Step 3：更新 TextMate 语法以支持代码块高亮

文件：apps/docs/likec4.tmLanguage.json

搜索已有的形状交替模式（形如rectangle|person|browser的正则分组），把新形状名加入该分组。指引文档特别提醒：文档站的 TextMate 语法可能与 VS Code 扩展中的版本不完全一致（仓库中还有 packages/vscode/likec4.tmLanguage.json 与 apps/playground/likec4.tmLanguage.json 等独立副本），必须仔细搜索确认改到的是apps/docs/下这一份。

Step 4：本地验证

cd apps/docs && pnpm dev

逐项检查：

• styling 页面（/dsl/styling/）的 "All Shapes" 实时图中出现了新形状；
• 含有shape YOUR_SHAPE的代码块获得了语法高亮；
• Shape 小节的 prose 列表中列出了新形状。

其他样式属性：同一模式的复用

指引文档指出，对styling.mdx中其他样式属性（颜色、尺寸、透明度、边框等）的变更遵循完全相同的模式。各属性在页面中的位置与对应的实时示例组件如下：

对照当前仓库中 styling.mdx 的实际内容，每个属性小节都遵循同一“三段式”结构：

1. 代码示例：一段带 ```likec4 标识的 DSL 语法（例如opacity 10%、border dotted、size large）；
2. Prose 列表：枚举该属性可用的取值（例如 Size 接受xsmall/small/medium/large/xlarge或简写xs–xl，默认medium；Border 支持dashed（默认）、dotted、solid、none）；
3. 实时示例：<LikeC4ThemeView viewId="..."/>组件渲染likec4-theme/目录下对应.c4文件的实际效果图。

以 Size 小节为例，当前页面实际引用的是sizes1_example与sizes2_example两个视图；Border 小节引用border_example。这与指引文档表格中简写的sizes、borders略有出入——表格给出的是定位用的近似值，实际操作时以 MDX 文件中的viewId实参为准。likec4-theme/目录下目前已有的示例数据文件包括 icons.c4、multiple.c4、notations.c4、opacity.c4、sizes.c4 等，均为手工维护（非自动生成）。

实时渲染层：LikeC4ThemeView.astro 如何工作

理解 LikeC4ThemeView.astro 有助于解释“为什么只改.c4文件就能让文档页面的图自动更新”。该组件的关键实现：

import { LikeC4View } from 'likec4:react/likec4-theme' ... <LikeC4View className={keepAspectRatio ? 'likec4-theme-view' : ''} viewId={viewId} fitViewPadding={fitViewPadding} keepAspectRatio={keepAspectRatio} browser={interactive ? { ... } : false} client:only="react" style={style} />

• likec4:react/likec4-theme是一个虚拟模块，文档站通过它把src/components/likec4-theme/下的.c4文件集合打包为一个 LikeC4 项目模型，viewId即该模型中的视图 id；
• client:only="react"表示客户端按需加载 React 渲染器，保证服务端产物体积不受影响；
• 默认开启交互，但通过browser配置禁用了焦点模式、元素详情、关系详情与搜索（enableFocusMode: false等），使文档中的示例图保持轻量；
• keepAspectRatio开启时套用.likec4-theme-view样式（max-width: 700px居中），控制示例图在文档排版中的尺寸。

组件支持的可配置 Props 为viewId（必填）、interactive（默认true）、fitViewPadding（默认'8px'）、keepAspectRatio（默认true）与style。

关键文件速查表

完整继承自指引文档，并标注各文件的维护方式：

要点回顾

• 文档站是“文字手改 + 图示自动生成”的双轨结构：DSL 新形状的文字描述改styling.mdx，实时图靠重新生成colors.c4与allshapes视图的通配include colors.primary.*自动带出；
• colors.c4永远重新生成、绝不手编：它由 generate-theme-c4.mjs 依据@likec4/core的LikeC4Styles.DEFAULT.theme.colors与脚本内的shapes数组产出，颜色变化可自动同步，形状变化必须手动登记；
• 语法高亮是独立的一环：MDX 代码块使用likec4语言标识，高亮由 apps/docs/likec4.tmLanguage.json 驱动，且该文件与 VS Code 扩展中的同名语法是各自独立维护的副本，新增形状时需要分别检查；
• 验证闭环：cd apps/docs && pnpm dev后核对 All Shapes 图、代码块高亮与 prose 列表三处，即可确认一次 DSL 变更的文档同步完整无遗漏。

【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4