documd-visuals
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesedocumd visuals
documd 可视化
Routing for every diagram, chart, card and layout this document pipeline can render.
该文档管道所能渲染的每个图表、图形、卡片和布局的路由。
Iron rules
铁律
- Allowed fences — /
plantuml·puml·vega·vega-lite·echarts, plus bare HTML — which is how system architecture diagrams, cards and page layouts are drawn.infographic - Nothing outside that list. A fence the list does not name is a bug, not a lesser option — there is no second-tier engine to fall back to.
- One diagram per fence. Do not put two engines in one block, and never nest fences.
- HTML is bare, never — a fenced block becomes an image. Start from a real file rather than inventing one:
```htmlfor a system,layered-with-wings.mdfor a card.executive-brief-summary.md - Inline the data. /
vega/vega-litemust carry their ownecharts/valuesdata; external URLs are unreliable on the export path.series - State the reading in the copy. Every figure answers one question — put that question in the
surrounding prose or the block's .
title - Pick a theme, then colour from it. Colours come from one of the themes indexed in
; copy that theme's block for your engine and take every value from it — a hex picked by hand, or two themes in one figure, is a bug. Charts pass the categorical ramp in order; cards use one accent plus neutrals.
styles/palette.md
- 允许的围栏 — /
plantuml·puml·vega·vega-lite·echarts,加上裸 HTML — 系统架构图、卡片和页面布局即以此方式绘制。infographic - 列表之外的均不可用。 列表未命名的围栏是 bug,而不是次优选项——没有可回退的二线引擎。
- 每个围栏一个图表。 不要在一个块中放置两个引擎,也绝不嵌套围栏。
- HTML 是裸的,绝不要用 — 围栏块会变成图像。从真实文件开始,而不是凭空捏造:
html用于系统,layered-with-wings.md用于卡片。executive-brief-summary.md - 内联数据。 /
vega/vega-lite必须携带自己的echarts/values数据;外部 URL 在导出路径上不可靠。series - 在正文中说明解读。 每个图回答一个问题——将该问题放在周围的散文中或块的 中。
title - 选择一个主题,然后从中取色。 颜色来自 中索引的主题之一;为你的引擎复制该主题的块,并从中取每个值——手工挑选的十六进制颜色,或一个图中的两个主题,都是 bug。图表按顺序使用分类色带;卡片使用一个强调色加中性色。
styles/palette.md
Route by goal
按目标路由
Find the reader's goal, open the goal guide, pick an example. Engines are suggestions; the guide and
examples are authoritative.
找到读者的目标,打开目标指南,选择示例。引擎是建议;指南和示例是权威的。
A — data & metrics
A — 数据与指标
| Goal | Trigger keywords | Engines | Read |
|---|---|---|---|
| service-reliability | latency · p95/p99 · SLO · SLA · error budget · burn rate · availability · uptime · reliability | echarts vega infographic | goals/service-reliability.md |
| ops-monitoring | incident load · alert volume · outliers · anomalies · service scorecard · support volume | echarts vega infographic | goals/ops-monitoring.md |
| delivery-throughput | throughput · cycle time · lead time · velocity · capacity · staffing · backlog · WIP · rank movement | echarts vega infographic | goals/delivery-throughput.md |
| goal-and-status-reporting | OKR · KPI · target vs actual · goal attainment · status board · dashboard · scorecard | echarts vega infographic html-css | goals/goal-and-status-reporting.md |
| product-metrics | conversion · funnel · adoption · retention · churn · activation · signup · cohorts · experiment | echarts infographic | goals/product-metrics.md |
| business-reporting | quarterly results · revenue · ARR · revenue mix · margin · periodic results · forecast | infographic vega echarts | goals/business-reporting.md |
| go-to-market | pipeline · channel · partner · partner tiers · market entry · sales funnel · SWOT · campaigns | echarts infographic | goals/go-to-market.md |
| cost-and-budget | cost · spend · budget · cloud bill · savings · cost reduction · capex · unit economics | echarts infographic vega | goals/cost-and-budget.md |
| data-exploration | correlation · distribution · regression · outlier detection · missing data · small multiples · density | vega echarts | goals/data-exploration.md |
| 目标 | 触发关键词 | 引擎 | 阅读 |
|---|---|---|---|
| 服务可靠性 | 延迟 · p95/p99 · SLO · SLA · 错误预算 · 燃烧率 · 可用性 · 正常运行时间 · 可靠性 | echarts vega infographic | goals/service-reliability.md |
| 运维监控 | 事故负载 · 警报量 · 离群点 · 异常 · 服务记分卡 · 支持量 | echarts vega infographic | goals/ops-monitoring.md |
| 交付吞吐量 | 吞吐量 · 周期时间 · 前置时间 · 速度 · 容量 · 人员配备 · 积压 · 在制品 · 排名变化 | echarts vega infographic | goals/delivery-throughput.md |
| 目标与状态汇报 | OKR · KPI · 目标与实际 · 目标达成 · 状态板 · 仪表盘 · 记分卡 | echarts vega infographic html-css | goals/goal-and-status-reporting.md |
| 产品指标 | 转化率 · 漏斗 · 采用 · 留存 · 流失 · 激活 · 注册 · 队列 · 实验 | echarts infographic | goals/product-metrics.md |
| 业务报告 | 季度业绩 · 收入 · ARR · 收入结构 · 利润率 · 定期业绩 · 预测 | infographic vega echarts | goals/business-reporting.md |
| 上市策略 | 管道 · 渠道 · 合作伙伴 · 合作伙伴层级 · 市场进入 · 销售漏斗 · SWOT · 活动 | echarts infographic | goals/go-to-market.md |
| 成本与预算 | 成本 · 支出 · 预算 · 云账单 · 节省 · 降本 · 资本支出 · 单位经济 | echarts infographic vega | goals/cost-and-budget.md |
| 数据探索 | 相关性 · 分布 · 回归 · 离群点检测 · 缺失数据 · 小倍数 · 密度 | vega echarts | goals/data-exploration.md |
B — process & systems
B — 流程与系统
| Goal | Trigger keywords | Engines | Read |
|---|---|---|---|
| engineering-operations | standup · sprint ritual · team rhythm · on-call · coverage · shift handover · deploy cadence · checklist | infographic vega echarts | goals/engineering-operations.md |
| incident-management | incident · postmortem · escalation · triage · runbook · change request · launch readiness · review | infographic echarts html-css | goals/incident-management.md |
| process-and-workflow | approval · workflow · swimlane · SOP · process map · BPMN · gate · procurement | plantuml infographic | goals/process-and-workflow.md |
| software-design | class · domain model · component · package · layering · use case · object · C4 container · SysML | plantuml | goals/software-design.md |
| software-behaviour | state machine · lifecycle · sequence · interaction · messaging · event flow · EIP · deployment | plantuml | goals/software-behaviour.md |
| dependencies-and-relations | dependency · call graph · impact analysis · coupling · ownership · causality · fishbone | plantuml vega echarts infographic | goals/dependencies-and-relations.md |
| system-architecture | system architecture · layer stack · zones · pipeline stages · service catalog · request path · connectors | html-css | goals/system-architecture.md |
| 目标 | 触发关键词 | 引擎 | 阅读 |
|---|---|---|---|
| 工程运营 | 站会 · 冲刺仪式 · 团队节奏 · 值班 · 覆盖 · 交接 · 部署节奏 · 检查单 | infographic vega echarts | goals/engineering-operations.md |
| 事故管理 | 事故 · 事后分析 · 升级 · 分诊 · 运行手册 · 变更请求 · 发布就绪 · 审查 | infographic echarts html-css | goals/incident-management.md |
| 流程与工作流 | 审批 · 工作流 · 泳道 · SOP · 流程图 · BPMN · 关卡 · 采购 | plantuml infographic | goals/process-and-workflow.md |
| 软件设计 | 类 · 领域模型 · 组件 · 包 · 分层 · 用例 · 对象 · C4 容器 · SysML | plantuml | goals/software-design.md |
| 软件行为 | 状态机 · 生命周期 · 序列 · 交互 · 消息传递 · 事件流 · EIP · 部署 | plantuml | goals/software-behaviour.md |
| 依赖与关系 | 依赖 · 调用图 · 影响分析 · 耦合 · 所有权 · 因果关系 · 鱼骨图 | plantuml vega echarts infographic | goals/dependencies-and-relations.md |
| 系统架构 | 系统架构 · 层次栈 · 区域 · 管道阶段 · 服务目录 · 请求路径 · 连接器 | html-css | goals/system-architecture.md |
C — infrastructure & governance
C — 基础设施与治理
| Goal | Trigger keywords | Engines | Read |
|---|---|---|---|
| cloud-architecture | AWS · Azure · Kubernetes · container · serverless · IoT · edge · VPC · observability | plantuml infographic | goals/cloud-architecture.md |
| data-platform | ETL · lakehouse · warehouse · CDC · streaming · ingestion · catalog · ML pipeline · ER model | plantuml | goals/data-platform.md |
| network-topology | network · topology · DMZ · wireless · firewall · switch · packet · route · traffic | plantuml echarts | goals/network-topology.md |
| security-and-compliance | zero trust · IAM · encryption · threat model · trust boundary · controls · evidence · audit · compliance · risk | plantuml infographic html-css | goals/security-and-compliance.md |
| enterprise-architecture | ArchiMate · capability map · value stream · stakeholder map · business architecture | plantuml infographic | goals/enterprise-architecture.md |
| organization-and-roles | org chart · reporting line · workforce · capability coverage · capability maturity · handoffs · responsibilities | infographic vega echarts html-css | goals/organization-and-roles.md |
| people-and-hiring | hiring · headcount plan · interview loop · onboarding · career ladder · certifications · progression | infographic | goals/people-and-hiring.md |
| 目标 | 触发关键词 | 引擎 | 阅读 |
|---|---|---|---|
| 云架构 | AWS · Azure · Kubernetes · 容器 · serverless · IoT · 边缘 · VPC · 可观测性 | plantuml infographic | goals/cloud-architecture.md |
| 数据平台 | ETL · lakehouse · 数仓 · CDC · 流式处理 · 摄取 · 目录 · ML管道 · ER模型 | plantuml | goals/data-platform.md |
| 网络拓扑 | 网络 · 拓扑 · DMZ · 无线 · 防火墙 · 交换机 · 数据包 · 路由 · 流量 | plantuml echarts | goals/network-topology.md |
| 安全与合规 | 零信任 · IAM · 加密 · 威胁模型 · 信任边界 · 控制 · 证据 · 审计 · 合规 · 风险 | plantuml infographic html-css | goals/security-and-compliance.md |
| 企业架构 | ArchiMate · 能力地图 · 价值流 · 利益相关者地图 · 业务架构 | plantuml infographic | goals/enterprise-architecture.md |
| 组织与角色 | 组织架构图 · 汇报线 · 劳动力 · 能力覆盖 · 能力成熟度 · 交接 · 职责 | infographic vega echarts html-css | goals/organization-and-roles.md |
| 人员与招聘 | 招聘 · 编制计划 · 面试流程 · 入职 · 职业阶梯 · 认证 · 晋升 | infographic | goals/people-and-hiring.md |
D — knowledge & expression
D — 知识与表达
| Goal | Trigger keywords | Engines | Read |
|---|---|---|---|
| knowledge-and-outline | mind map · outline · knowledge map · concept map · topics · word cloud | plantuml infographic vega echarts | goals/knowledge-and-outline.md |
| planning-and-roadmap | roadmap · milestone · timeline · Gantt · quarterly plan · release schedule · strategy focus | infographic vega plantuml html-css | goals/planning-and-roadmap.md |
| migration-and-rollout | migration · cutover · rollout waves · phased delivery · programme · work breakdown | plantuml infographic | goals/migration-and-rollout.md |
| comparison-and-selection | compare · versus · build or buy · decision record · quadrant · vendor selection · trade-off · priority | infographic html-css | goals/comparison-and-selection.md |
| internal-documents | memo · brief · charter · abstract · policy · quote · principles | html-css infographic | goals/internal-documents.md |
| catalogues-and-inventories | catalogue · inventory · entitlements · offerings · standard tools · support tiers | infographic | goals/catalogues-and-inventories.md |
| customer-and-partner-comms | customer story · case study · sales brief · bulletin · announcement · partner brief · education module | html-css | goals/customer-and-partner-comms.md |
| theme-and-tone | print · photocopy · handout · low vision · large print · colour-blind · slide · projected · long-form | infographic echarts plantuml | goals/theme-and-tone.md |
| 目标 | 触发关键词 | 引擎 | 阅读 |
|---|---|---|---|
| 知识与大纲 | 思维导图 · 大纲 · 知识地图 · 概念图 · 主题 · 词云 | plantuml infographic vega echarts | goals/knowledge-and-outline.md |
| 规划与路线图 | 路线图 · 里程碑 · 时间线 · 甘特图 · 季度计划 · 发布计划 · 战略重点 | infographic vega plantuml html-css | goals/planning-and-roadmap.md |
| 迁移与推广 | 迁移 · 切换 · 分批推广 · 分阶段交付 · 项目群 · 工作分解 | plantuml infographic | goals/migration-and-rollout.md |
| 比较与选择 | 比较 · 对比 · 自建或购买 · 决策记录 · 四象限 · 供应商选择 · 权衡 · 优先级 | infographic html-css | goals/comparison-and-selection.md |
| 内部文档 | 备忘录 · 简报 · 章程 · 摘要 · 政策 · 引文 · 原则 | html-css infographic | goals/internal-documents.md |
| 目录与清单 | 目录 · 清单 · 权限 · 产品 · 标准工具 · 支持层级 | infographic | goals/catalogues-and-inventories.md |
| 客户与合作伙伴沟通 | 客户故事 · 案例研究 · 销售简报 · 公告 · 通知 · 合作伙伴简报 · 教育模块 | html-css | goals/customer-and-partner-comms.md |
| 主题与色调 | 打印 · 复印 · 讲义 · 低视力 · 大字版 · 色盲 · 幻灯片 · 投影 · 长文 | infographic echarts plantuml | goals/theme-and-tone.md |
Engine cheat sheet
引擎速查表
| Engine | Reach for it when | Look elsewhere when |
|---|---|---|
| UML/ArchiMate/BPMN semantics, brand and device icons (9,514 stencils), or a relationship graph that should lay itself out | It is a chart |
| The data needs work first — join, window, fold, regression, density, facets, small multiples | One polished chart with heavy styling ( |
| Report-grade chart or KPI dashboard: axes, series, thresholds, annotations, gauges | The data must be transformed first |
| A designed-looking board: roadmap, timeline, checklist, comparison, quadrant, knowledge map | Axes, several series or statistical shapes ( |
| HTML/CSS | Cards, memos, overviews, page-level layouts | Another engine already renders that diagram |
Details, limits and pitfalls: ·
· · ·
.
plantumlechartsvegainfographichtml-css| 引擎 | 何时使用 | 何时改用其他 |
|---|---|---|
| UML/ArchiMate/BPMN 语义,品牌和设备图标(9,514 个模具),或需要自动布局的关系图 | 它是图表 |
| 数据需要先处理——连接、窗口、折叠、回归、密度、分面、小倍数 | 需要高度样式化的一键式图表( |
| 报告级图表或 KPI 仪表盘:坐标轴、系列、阈值、标注、仪表盘 | 数据必须先进行转换 |
| 设计感展板:路线图、时间线、检查单、比较、四象限、知识地图 | 坐标轴、多个系列或统计图形( |
| HTML/CSS | 卡片、备忘录、概览、页面级布局 | 其他引擎已可渲染该图 |
详细信息、限制与陷阱: · · · · 。
plantumlechartsvegainfographichtml-cssCapability boundaries
能力边界
These are not possible; pick the fallback instead of retrying.
| Want | Fallback |
|---|---|
3D / globe / WebGL charts (no | 2D |
| Geographic maps (no bundled map data, no GeoJSON offline) | schematic rectangle layout, or an HTML/CSS region diagram |
| sort and derive upstream, then |
Functions in an | template strings ( |
External data or images ( | inline |
| PlantUML WBS / Salt / Timing / ditaa / JSON / YAML / EBNF / nwdiag / SDL / math (parse, draw nothing useful) | |
| Interactive charts (tooltip, zoom, brush) | annotate directly: labels, thresholds, callouts |
Icons in | |
Free-form positioning in | HTML/CSS for pixel control |
以下不可能实现;选择替代方案而不是重试。
| 需求 | 替代方案 |
|---|---|
3D / 地球 / WebGL 图表(无 | 2D |
| 地理地图(无内置地图数据,无离线 GeoJSON) | 示意矩形布局,或 HTML/CSS 区域图 |
ECharts 中的 | 在上游排序和派生,然后使用 |
| 模板字符串( |
外部数据或图像( | 内联 |
| PlantUML WBS / Salt / Timing / ditaa / JSON / YAML / EBNF / nwdiag / SDL / 数学(解析但画不出有用内容) | |
| 交互式图表(工具提示、缩放、刷选) | 直接标注:标签、阈值、标注 |
| |
| 使用 HTML/CSS 进行像素级控制 |
Converting a document
转换文档
The CLI does three things the host application cannot: convert a document or a diagram
source to a file, extract its figures as image files to look at (), and
verify — rendering is the only way to prove a block draws; every failure comes back with its engine
and markdown line, and the run exits 1. Nothing to install:
( · · , ).
⚠️ Use the scope: bare on npm is a different package. Flags, formats and export
behaviour: converting.md.
documd--assets ./figuresnpx @markdown-viewer/documd in.md out.docx.pdf.epub.htmldiagram.puml out.pngdocumddocumd--assets ./figuresnpx @markdown-viewer/documd in.md out.docx.pdf.epub.htmldiagram.puml out.pngdocumdWhen a block does not render
当块不渲染时
- Fence in the allowed list? Exactly one block per figure?
- Is it a listed anti-pattern in that engine's reference (see Engine cheat sheet) — or strict
syntax (JSON for /
echarts, no empty lines in bare HTML)?vega - Then switch to the alternative engine named in the goal guide; most scenarios have two implementations.
- Or verify by rendering: .
npx @markdown-viewer/documd file.md --assets /tmp/figs
- 围栏是否在允许列表中?每个图形是否只有一个块?
- 是否是该引擎参考中的列出的反面模式(见引擎速查表)——或严格语法(/
echarts需要 JSON,裸 HTML 不能有空行)?vega - 然后切换到目标指南中提到的替代引擎;大多数场景有两种实现。
- 或通过渲染验证:。
npx @markdown-viewer/documd file.md --assets /tmp/figs
Where everything lives
所有内容存放位置
catalog/scenarios.mdgoals/<domain>.mdengines/<engine>.mdexamples/<domain>/<file>.mdcatalog/scenarios.mdgoals/<domain>.mdengines/<engine>.mdexamples/<domain>/<file>.md