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.c4likec4.tmLanguage.json让 MDX 中 likec4 代码块获得语法高亮。自动生成机制generate-theme-c4.mjs 如何产出 colors.c4colors.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 kindkind 的style块里写shape ${shape}即“每个形状自身作为一个元素种类”model在themecolor colors容器下为每个颜色创建一个themecolor实例每个颜色容器内再嵌套每个形状一个实例shape shape { ... style { color ${key} } }元素带 markdown 描述文本 ... 以同时展示富文本能力viewsview index of colorsinclude *展示全部主题颜色的总览每个形状一个视图如view rectangleinclude 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 viewIdallshapes/组件第 89 行不需要改动它渲染的allshapes视图定义在 allshapes.c4 中内容仅为views { view allshapes { title All Shapes include colors.primary.* } }由于include colors.primary.*是通配引用它会自动纳入colors.c4中主色下的所有形状实例。因此只要 Step 1 重新生成了colors.c4All 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中其他样式属性颜色、尺寸、透明度、边框等的变更遵循完全相同的模式。各属性在页面中的位置与对应的实时示例组件如下PropertyDocs section示例组件 viewIdShape### Shape~line 75allshapesColor### Color~line 91indexSize### Size~line 130sizesOpacity### Opacity~line 148opacityBorder### Border~line 167bordersMultiple### Multiple~line 184multipleIcon### Icon~line 200icons对照当前仓库中 styling.mdx 的实际内容每个属性小节都遵循同一“三段式”结构代码示例一段带 likec4 标识的 DSL 语法例如opacity 10%、border dotted、size largeProse 列表枚举该属性可用的取值例如 Size 接受xsmall/small/medium/large/xlarge或简写xs–xl默认mediumBorder 支持dashed默认、dotted、solid、none实时示例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:onlyreact style{style} /likec4:react/likec4-theme是一个虚拟模块文档站通过它把src/components/likec4-theme/下的.c4文件集合打包为一个 LikeC4 项目模型viewId即该模型中的视图 idclient:onlyreact表示客户端按需加载 React 渲染器保证服务端产物体积不受影响默认开启交互但通过browser配置禁用了焦点模式、元素详情、关系详情与搜索enableFocusMode: false等使文档中的示例图保持轻量keepAspectRatio开启时套用.likec4-theme-view样式max-width: 700px居中控制示例图在文档排版中的尺寸。组件支持的可配置 Props 为viewId必填、interactive默认true、fitViewPadding默认8px、keepAspectRatio默认true与style。关键文件速查表完整继承自指引文档并标注各文件的维护方式FilePurposeAuto-generated?apps/docs/src/content/docs/dsl/styling.mdx样式属性主参考页否 - 手工编辑apps/docs/src/content/docs/dsl/specification.mdx元素种类定义文档否 - 手工编辑apps/docs/src/content/docs/dsl/notations.mdx记号/图例文档否 - 手工编辑apps/docs/scripts/generate-theme-c4.mjs生成colors.c4的脚本否 - 手工编辑apps/docs/src/components/likec4-theme/colors.c4全 shape × 全 color 示例是- 运行脚本生成apps/docs/src/components/likec4-theme/allshapes.c4视图主色下所有 shape否 - 极少需要改动apps/docs/src/components/likec4-theme/LikeC4ThemeView.astro内联渲染.c4视图否 - 极少需要改动apps/docs/likec4.tmLanguage.json代码块语法高亮否 - 手工编辑要点回顾文档站是“文字手改 图示自动生成”的双轨结构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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考