Back to Details

renderizr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Renderizr — a Structurizr workspace as one shareable file

Renderizr — 将Structurizr工作区转换为单个可共享文件

This skill renders a Structurizr workspace — its views, documentation and decision log — into a browsable static site, or into a single self-contained HTML file that can be uploaded as a Claude artifact and opened by anyone, with no server and no network.
Diagrams are drawn by Structurizr's own renderer rather than re-implemented, so they pan, zoom and play back dynamic views exactly as they do in Structurizr.
本技能可将Structurizr工作区（包括其视图、文档和决策日志）渲染为可浏览的静态站点，或单个自包含HTML文件，该文件可作为Claude工件上传，任何人无需服务器和网络即可打开。
图表由Structurizr官方渲染器绘制，而非重新实现，因此它们的平移、缩放和动态视图回放效果与在Structurizr中完全一致。

When to use this skill

何时使用本技能

  • The user wants to see an architecture model rather than read its source.
  • The user wants to share a model with people who have no Structurizr account, no server and no copy of the DSL.
  • The user asks for an artifact, a preview, or "publish the diagrams".
  • The user is working in a repository that has an 
    ./architecture
    folder — often one created by Scaffoldizr — and wants output from it.
Do not use this skill to author or edit a model. Renderizr renders; it does not parse DSL and never writes to the workspace. Editing the model is Scaffoldizr's job.
  • 用户希望查看架构模型，而非阅读其源代码。
  • 用户希望与没有Structurizr账户、服务器或DSL副本的人分享模型。
  • 用户要求生成工件、预览或“发布图表”。
  • 用户正在包含
    ./architecture
    文件夹的仓库中工作（通常由Scaffoldizr创建），并希望从中获取输出。
请勿使用本技能创作或编辑模型。Renderizr仅负责渲染；它不解析DSL，也绝不会写入工作区。编辑模型是Scaffoldizr的职责。

The one command

单条命令

bash
npx github:FormulaMonks/renderizr <workspace.json|url> --single-file --out <dir>
That writes two files into 
<dir>
:
FileWhat it isUse it for
artifact.html
The page without its own 
<html>
/
<head>
/
<body>
scaffolding		Uploading as a Claude artifact — the host supplies the document
index.html
The same page as a complete standalone documentOpening from disk, emailing, dropping in a bucket
Both inline every stylesheet, script, font, icon and the workspace itself. Neither makes a single network request.
For a Claude artifact, use 
artifact.html
. Handing over 
index.html
instead produces a document nested inside a document.
Drop 
--single-file
to get a directory — 
index.html
plus 
assets/
— for hosting on a static server or GitHub Pages.
bash
npx github:FormulaMonks/renderizr <workspace.json|url> --single-file --out <dir>
该命令会在
<dir>
目录中生成两个文件：
文件说明使用场景
artifact.html
不含自身
<html>
/
<head>
/
<body>
框架的页面		上传为Claude工件 — 由宿主提供文档结构
index.html
完整的独立文档页面本地打开、邮件发送、存入存储桶
两个文件均内联了所有样式表、脚本、字体、图标以及工作区本身。均不会发起任何网络请求。
若要生成Claude工件，请使用
artifact.html
。 若提供
index.html
，会导致文档嵌套在宿主文档内部。
移除
--single-file
参数可生成包含
index.html
和
assets/
目录的文件夹，用于部署到静态服务器或GitHub Pages。

Getting a workspace to render

获取待渲染的工作区

Renderizr takes JSON, either a local path or a URL. It does not parse DSL.
  • A 
    workspace.json
    already on disk     — usually 
    ./architecture/workspace.json
    . Use it directly.
  • Only a 
    workspace.dsl
     — export it first with structurizr-cli, which exports a DSL workspace to JSON. In a Scaffoldizr repository, 
    ./architecture/scripts/export.sh
    (or 
    export.ps1
    ) does this for you.
  • A URL — passed straight through, e.g. the Big Bank plc example:
    bash
    npx github:FormulaMonks/renderizr \
  https://raw.githubusercontent.com/structurizr/ui/main/examples/big-bank-plc.json \
  --single-file --out /tmp/big-bank
workspace.json
is a compiled output in a Scaffoldizr repository. Render it, but never edit it — it is overwritten on the next export.
Renderizr接收JSON格式的输入，可以是本地路径或URL。它不解析DSL。
  • 本地已存在
    workspace.json
     — 通常位于
    ./architecture/workspace.json
    ，可直接使用。
  • 仅存在
    workspace.dsl
     — 需先通过structurizr-cli将其导出为JSON。在Scaffoldizr仓库中，
    ./architecture/scripts/export.sh
    （或
    export.ps1
    ）可自动完成此操作。
  • URL — 直接传入即可，例如Big Bank plc示例：
    bash
    npx github:FormulaMonks/renderizr \
  https://raw.githubusercontent.com/structurizr/ui/main/examples/big-bank-plc.json \
  --single-file --out /tmp/big-bank
在Scaffoldizr仓库中，
workspace.json
是编译输出文件。可对其进行渲染，但切勿编辑 — 下次导出时它会被覆盖。

Recommended flow

推荐流程

  1. Find the workspace. Look for 
    ./architecture/workspace.json
    . If only 
    workspace.dsl
    exists, export it first and say so; do not silently render a stale JSON.
  2. Render it, into a temporary directory rather than the repository, unless the user asked for the output to be kept:
    bash
    npx github:FormulaMonks/renderizr ./architecture/workspace.json --single-file --out /tmp/renderizr-out
  3. Check it is genuinely self-contained before handing it over — see verifying. One command, and it is the difference between an artifact that opens and one that renders blank for the recipient.
  4. Hand over 
    artifact.html
    .     Say which file it is and roughly how big; a real model lands around 1 MB.
  1. 查找工作区。寻找
    ./architecture/workspace.json
    。若仅存在
    workspace.dsl
    ，请先导出并告知用户；切勿静默渲染过时的JSON文件。
  2. 执行渲染，将输出保存到临时目录而非仓库中，除非用户要求保留输出：
    bash
    npx github:FormulaMonks/renderizr ./architecture/workspace.json --single-file --out /tmp/renderizr-out
  3. 移交前验证文件是否真正自包含 — 参考验证。只需一条命令，就能确保接收方打开的是正常显示的工件，而非空白页面。
  4. 移交
    artifact.html
    。告知用户文件名及大致大小；真实模型的文件大小约为1 MB。

Flags

命令参数

Full reference in flags. The ones that matter most:
FlagEffect
--single-file
One self-contained document, plus 
artifact.html
. Use for artifacts.
-o, --out <dir>
Output directory (default 
structurizr-output
)
--base <path>
Base public path for the multi-file build, e.g. 
/repo-name/
for project Pages
--logo <path|url>
Image top-left in the header, embedded as a data URI
--font <family>
A Google Web Font, fetched at build time and embedded as woff2
--font
and a remote 
--logo
are the only things that need network access during a build. Without them a render is fully offline.
完整参数说明请参考参数。最常用的参数如下：
参数作用
--single-file
生成单个自包含文档及
artifact.html
。用于生成工件。
-o, --out <dir>
输出目录（默认值为
structurizr-output
）
--base <path>
多文件构建的基础公共路径，例如项目Pages的
/repo-name/
--logo <path|url>
页眉左上角的图片，以data URI形式嵌入
--font <family>
Google Web字体，构建时获取并以woff2格式嵌入
--font
和远程
--logo
是构建过程中唯一需要网络访问的操作。若无这两个参数，渲染过程可完全离线进行。

Things that will bite you

注意事项

Each of these has been verified against the tool, not inferred:
  • Node 20 is a hard floor. 
    npx
    runs against whatever Node is first on 
    PATH
    , which is often not the one the shell reports. Renderizr checks and exits with a clear message rather than failing deep inside the build.
  • artifact.html
    and 
    index.html
    are not interchangeable.     See the table above.
  • The output directory is emptied before writing. Never point 
    --out
    at a directory holding anything you want to keep.
  • https://
    in the output is not a leak.     A rendered page contains ordinary hyperlinks to 
    structurizr.com
    , 
    c4model.com
    and the like. Self-containment is about asset references — 
    <script src>
    , 
    <link href>
    , 
    <img src>
    — of which there are none. Check the right thing; see verifying.
  • Working inside a clone of the Renderizr repository is different. 
    pnpm build <workspace> [flags]
    — and specifically not 
    pnpm build -- <workspace> --flag
    , which makes the flag arrive as a second workspace. 
    pnpm dev
    is the opposite and does want the 
    --
    . This only applies inside the repository; 
    npx
    users are unaffected.
以下均为经过工具验证的实际问题，而非推断：
  • Node 20是最低要求。
    npx
    会使用
    PATH
    中优先级最高的Node版本，这可能与Shell显示的版本不同。Renderizr会进行版本检查，若版本不满足则会输出清晰提示，而非在构建过程中深层报错。
  • artifact.html
    和
    index.html
    不可互换    。请参考上方表格说明。
  • 输出目录会被清空后再写入文件。切勿将
    --out
    指向包含重要文件的目录。
  • 输出中的
    https://
    并非信息泄露    。渲染后的页面包含指向
    structurizr.com
    、
    c4model.com
    等网站的普通超链接。自包含性针对的是资源引用（如
    <script src>
    、
    <link href>
    、
    <img src>
    ），此类引用在输出中不存在。请参考验证确认正确内容。
  • 在Renderizr仓库克隆内工作时有所不同。需使用
    pnpm build <workspace> [flags]
    — 特别注意不能使用
    pnpm build -- <workspace> --flag
    ，否则参数会被当作第二个工作区。
    pnpm dev
    则相反，需要添加
    --
    。此规则仅适用于仓库内部；
    npx
    用户不受影响。

References

参考文档

  • flags — every CLI flag, what it does, and what it costs
  • artifacts — the Claude artifact path in detail, including size and what to hand over
  • verifying — proving an artifact is self-contained before you hand it over
  • 参数 — 所有CLI参数的作用及说明
  • 工件 — Claude工件的详细说明，包括大小及移交建议
  • 验证 — 移交前验证工件是否自包含的方法