documd-visuals

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

documd visuals

documd 可视化

Routing for every diagram, chart, card and layout this document pipeline can render.
该文档管道所能渲染的每个图表、图形、卡片和布局的路由。

Iron rules

铁律

  1. Allowed fences —
    plantuml
    /
    puml
    ·
    vega
    ·
    vega-lite
    ·
    echarts
    ·
    infographic
    , plus bare HTML — which is how system architecture diagrams, cards and page layouts are drawn.
  2. 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.
  3. One diagram per fence. Do not put two engines in one block, and never nest fences.
  4. HTML is bare, never
    ```html
    — a fenced block becomes an image. Start from a real file rather than inventing one:
    layered-with-wings.md
    for a system,
    executive-brief-summary.md
    for a card.
  5. Inline the data.
    vega
    /
    vega-lite
    /
    echarts
    must carry their own
    values
    /
    series
    data; external URLs are unreliable on the export path.
  6. State the reading in the copy. Every figure answers one question — put that question in the surrounding prose or the block's
    title
    .
  7. Pick a theme, then colour from it. Colours come from one of the themes indexed in
    styles/palette.md
    ; 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.
  1. 允许的围栏 —
    plantuml
    /
    puml
    ·
    vega
    ·
    vega-lite
    ·
    echarts
    ·
    infographic
    ,加上裸 HTML — 系统架构图、卡片和页面布局即以此方式绘制。
  2. 列表之外的均不可用。 列表未命名的围栏是 bug,而不是次优选项——没有可回退的二线引擎。
  3. 每个围栏一个图表。 不要在一个块中放置两个引擎,也绝不嵌套围栏。
  4. HTML 是裸的,绝不要用
    html
    — 围栏块会变成图像。从真实文件开始,而不是凭空捏造:
    layered-with-wings.md
    用于系统,
    executive-brief-summary.md
    用于卡片。
  5. 内联数据。
    vega
    /
    vega-lite
    /
    echarts
    必须携带自己的
    values
    /
    series
    数据;外部 URL 在导出路径上不可靠。
  6. 在正文中说明解读。 每个图回答一个问题——将该问题放在周围的散文中或块的
    title
    中。
  7. 选择一个主题,然后从中取色。 颜色来自
    styles/palette.md
    中索引的主题之一;为你的引擎复制该主题的块,并从中取每个值——手工挑选的十六进制颜色,或一个图中的两个主题,都是 bug。图表按顺序使用分类色带;卡片使用一个强调色加中性色。

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 — 数据与指标

GoalTrigger keywordsEnginesRead
service-reliabilitylatency · p95/p99 · SLO · SLA · error budget · burn rate · availability · uptime · reliabilityecharts vega infographicgoals/service-reliability.md
ops-monitoringincident load · alert volume · outliers · anomalies · service scorecard · support volumeecharts vega infographicgoals/ops-monitoring.md
delivery-throughputthroughput · cycle time · lead time · velocity · capacity · staffing · backlog · WIP · rank movementecharts vega infographicgoals/delivery-throughput.md
goal-and-status-reportingOKR · KPI · target vs actual · goal attainment · status board · dashboard · scorecardecharts vega infographic html-cssgoals/goal-and-status-reporting.md
product-metricsconversion · funnel · adoption · retention · churn · activation · signup · cohorts · experimentecharts infographicgoals/product-metrics.md
business-reportingquarterly results · revenue · ARR · revenue mix · margin · periodic results · forecastinfographic vega echartsgoals/business-reporting.md
go-to-marketpipeline · channel · partner · partner tiers · market entry · sales funnel · SWOT · campaignsecharts infographicgoals/go-to-market.md
cost-and-budgetcost · spend · budget · cloud bill · savings · cost reduction · capex · unit economicsecharts infographic vegagoals/cost-and-budget.md
data-explorationcorrelation · distribution · regression · outlier detection · missing data · small multiples · densityvega echartsgoals/data-exploration.md
目标触发关键词引擎阅读
服务可靠性延迟 · p95/p99 · SLO · SLA · 错误预算 · 燃烧率 · 可用性 · 正常运行时间 · 可靠性echarts vega infographicgoals/service-reliability.md
运维监控事故负载 · 警报量 · 离群点 · 异常 · 服务记分卡 · 支持量echarts vega infographicgoals/ops-monitoring.md
交付吞吐量吞吐量 · 周期时间 · 前置时间 · 速度 · 容量 · 人员配备 · 积压 · 在制品 · 排名变化echarts vega infographicgoals/delivery-throughput.md
目标与状态汇报OKR · KPI · 目标与实际 · 目标达成 · 状态板 · 仪表盘 · 记分卡echarts vega infographic html-cssgoals/goal-and-status-reporting.md
产品指标转化率 · 漏斗 · 采用 · 留存 · 流失 · 激活 · 注册 · 队列 · 实验echarts infographicgoals/product-metrics.md
业务报告季度业绩 · 收入 · ARR · 收入结构 · 利润率 · 定期业绩 · 预测infographic vega echartsgoals/business-reporting.md
上市策略管道 · 渠道 · 合作伙伴 · 合作伙伴层级 · 市场进入 · 销售漏斗 · SWOT · 活动echarts infographicgoals/go-to-market.md
成本与预算成本 · 支出 · 预算 · 云账单 · 节省 · 降本 · 资本支出 · 单位经济echarts infographic vegagoals/cost-and-budget.md
数据探索相关性 · 分布 · 回归 · 离群点检测 · 缺失数据 · 小倍数 · 密度vega echartsgoals/data-exploration.md

B — process & systems

B — 流程与系统

GoalTrigger keywordsEnginesRead
engineering-operationsstandup · sprint ritual · team rhythm · on-call · coverage · shift handover · deploy cadence · checklistinfographic vega echartsgoals/engineering-operations.md
incident-managementincident · postmortem · escalation · triage · runbook · change request · launch readiness · reviewinfographic echarts html-cssgoals/incident-management.md
process-and-workflowapproval · workflow · swimlane · SOP · process map · BPMN · gate · procurementplantuml infographicgoals/process-and-workflow.md
software-designclass · domain model · component · package · layering · use case · object · C4 container · SysMLplantumlgoals/software-design.md
software-behaviourstate machine · lifecycle · sequence · interaction · messaging · event flow · EIP · deploymentplantumlgoals/software-behaviour.md
dependencies-and-relationsdependency · call graph · impact analysis · coupling · ownership · causality · fishboneplantuml vega echarts infographicgoals/dependencies-and-relations.md
system-architecturesystem architecture · layer stack · zones · pipeline stages · service catalog · request path · connectorshtml-cssgoals/system-architecture.md
目标触发关键词引擎阅读
工程运营站会 · 冲刺仪式 · 团队节奏 · 值班 · 覆盖 · 交接 · 部署节奏 · 检查单infographic vega echartsgoals/engineering-operations.md
事故管理事故 · 事后分析 · 升级 · 分诊 · 运行手册 · 变更请求 · 发布就绪 · 审查infographic echarts html-cssgoals/incident-management.md
流程与工作流审批 · 工作流 · 泳道 · SOP · 流程图 · BPMN · 关卡 · 采购plantuml infographicgoals/process-and-workflow.md
软件设计类 · 领域模型 · 组件 · 包 · 分层 · 用例 · 对象 · C4 容器 · SysMLplantumlgoals/software-design.md
软件行为状态机 · 生命周期 · 序列 · 交互 · 消息传递 · 事件流 · EIP · 部署plantumlgoals/software-behaviour.md
依赖与关系依赖 · 调用图 · 影响分析 · 耦合 · 所有权 · 因果关系 · 鱼骨图plantuml vega echarts infographicgoals/dependencies-and-relations.md
系统架构系统架构 · 层次栈 · 区域 · 管道阶段 · 服务目录 · 请求路径 · 连接器html-cssgoals/system-architecture.md

C — infrastructure & governance

C — 基础设施与治理

GoalTrigger keywordsEnginesRead
cloud-architectureAWS · Azure · Kubernetes · container · serverless · IoT · edge · VPC · observabilityplantuml infographicgoals/cloud-architecture.md
data-platformETL · lakehouse · warehouse · CDC · streaming · ingestion · catalog · ML pipeline · ER modelplantumlgoals/data-platform.md
network-topologynetwork · topology · DMZ · wireless · firewall · switch · packet · route · trafficplantuml echartsgoals/network-topology.md
security-and-compliancezero trust · IAM · encryption · threat model · trust boundary · controls · evidence · audit · compliance · riskplantuml infographic html-cssgoals/security-and-compliance.md
enterprise-architectureArchiMate · capability map · value stream · stakeholder map · business architectureplantuml infographicgoals/enterprise-architecture.md
organization-and-rolesorg chart · reporting line · workforce · capability coverage · capability maturity · handoffs · responsibilitiesinfographic vega echarts html-cssgoals/organization-and-roles.md
people-and-hiringhiring · headcount plan · interview loop · onboarding · career ladder · certifications · progressioninfographicgoals/people-and-hiring.md
目标触发关键词引擎阅读
云架构AWS · Azure · Kubernetes · 容器 · serverless · IoT · 边缘 · VPC · 可观测性plantuml infographicgoals/cloud-architecture.md
数据平台ETL · lakehouse · 数仓 · CDC · 流式处理 · 摄取 · 目录 · ML管道 · ER模型plantumlgoals/data-platform.md
网络拓扑网络 · 拓扑 · DMZ · 无线 · 防火墙 · 交换机 · 数据包 · 路由 · 流量plantuml echartsgoals/network-topology.md
安全与合规零信任 · IAM · 加密 · 威胁模型 · 信任边界 · 控制 · 证据 · 审计 · 合规 · 风险plantuml infographic html-cssgoals/security-and-compliance.md
企业架构ArchiMate · 能力地图 · 价值流 · 利益相关者地图 · 业务架构plantuml infographicgoals/enterprise-architecture.md
组织与角色组织架构图 · 汇报线 · 劳动力 · 能力覆盖 · 能力成熟度 · 交接 · 职责infographic vega echarts html-cssgoals/organization-and-roles.md
人员与招聘招聘 · 编制计划 · 面试流程 · 入职 · 职业阶梯 · 认证 · 晋升infographicgoals/people-and-hiring.md

D — knowledge & expression

D — 知识与表达

GoalTrigger keywordsEnginesRead
knowledge-and-outlinemind map · outline · knowledge map · concept map · topics · word cloudplantuml infographic vega echartsgoals/knowledge-and-outline.md
planning-and-roadmaproadmap · milestone · timeline · Gantt · quarterly plan · release schedule · strategy focusinfographic vega plantuml html-cssgoals/planning-and-roadmap.md
migration-and-rolloutmigration · cutover · rollout waves · phased delivery · programme · work breakdownplantuml infographicgoals/migration-and-rollout.md
comparison-and-selectioncompare · versus · build or buy · decision record · quadrant · vendor selection · trade-off · priorityinfographic html-cssgoals/comparison-and-selection.md
internal-documentsmemo · brief · charter · abstract · policy · quote · principleshtml-css infographicgoals/internal-documents.md
catalogues-and-inventoriescatalogue · inventory · entitlements · offerings · standard tools · support tiersinfographicgoals/catalogues-and-inventories.md
customer-and-partner-commscustomer story · case study · sales brief · bulletin · announcement · partner brief · education modulehtml-cssgoals/customer-and-partner-comms.md
theme-and-toneprint · photocopy · handout · low vision · large print · colour-blind · slide · projected · long-forminfographic echarts plantumlgoals/theme-and-tone.md
目标触发关键词引擎阅读
知识与大纲思维导图 · 大纲 · 知识地图 · 概念图 · 主题 · 词云plantuml infographic vega echartsgoals/knowledge-and-outline.md
规划与路线图路线图 · 里程碑 · 时间线 · 甘特图 · 季度计划 · 发布计划 · 战略重点infographic vega plantuml html-cssgoals/planning-and-roadmap.md
迁移与推广迁移 · 切换 · 分批推广 · 分阶段交付 · 项目群 · 工作分解plantuml infographicgoals/migration-and-rollout.md
比较与选择比较 · 对比 · 自建或购买 · 决策记录 · 四象限 · 供应商选择 · 权衡 · 优先级infographic html-cssgoals/comparison-and-selection.md
内部文档备忘录 · 简报 · 章程 · 摘要 · 政策 · 引文 · 原则html-css infographicgoals/internal-documents.md
目录与清单目录 · 清单 · 权限 · 产品 · 标准工具 · 支持层级infographicgoals/catalogues-and-inventories.md
客户与合作伙伴沟通客户故事 · 案例研究 · 销售简报 · 公告 · 通知 · 合作伙伴简报 · 教育模块html-cssgoals/customer-and-partner-comms.md
主题与色调打印 · 复印 · 讲义 · 低视力 · 大字版 · 色盲 · 幻灯片 · 投影 · 长文infographic echarts plantumlgoals/theme-and-tone.md

Engine cheat sheet

引擎速查表

EngineReach for it whenLook elsewhere when
plantuml
UML/ArchiMate/BPMN semantics, brand and device icons (9,514 stencils), or a relationship graph that should lay itself outIt is a chart
vega
/
vega-lite
The data needs work first — join, window, fold, regression, density, facets, small multiplesOne polished chart with heavy styling (
echarts
)
echarts
Report-grade chart or KPI dashboard: axes, series, thresholds, annotations, gaugesThe data must be transformed first
infographic
A designed-looking board: roadmap, timeline, checklist, comparison, quadrant, knowledge mapAxes, several series or statistical shapes (
echarts
)
HTML/CSSCards, memos, overviews, page-level layoutsAnother engine already renders that diagram
Details, limits and pitfalls:
plantuml
·
echarts
·
vega
·
infographic
·
html-css
.
引擎何时使用何时改用其他
plantuml
UML/ArchiMate/BPMN 语义,品牌和设备图标(9,514 个模具),或需要自动布局的关系图它是图表
vega
/
vega-lite
数据需要先处理——连接、窗口、折叠、回归、密度、分面、小倍数需要高度样式化的一键式图表(
echarts
)
echarts
报告级图表或 KPI 仪表盘:坐标轴、系列、阈值、标注、仪表盘数据必须先进行转换
infographic
设计感展板:路线图、时间线、检查单、比较、四象限、知识地图坐标轴、多个系列或统计图形(
echarts
)
HTML/CSS卡片、备忘录、概览、页面级布局其他引擎已可渲染该图
详细信息、限制与陷阱:
plantuml
·
echarts
·
vega
·
infographic
·
html-css
。

Capability boundaries

能力边界

These are not possible; pick the fallback instead of retrying.
WantFallback
3D / globe / WebGL charts (no
echarts-gl
)
2D
echarts
;
scatter
/
graph
for shape
Geographic maps (no bundled map data, no GeoJSON offline)schematic rectangle layout, or an HTML/CSS region diagram
dataset.transform
in ECharts (throws
RangeError
in 6.1.0)
sort and derive upstream, then
dataset.source
Functions in an
echarts
option (parsed as JSON)
template strings (
"{c}%"
), per-item label objects
External data or images (
data.url
, remote URLs)
inline
values
, data URLs
PlantUML WBS / Salt / Timing / ditaa / JSON / YAML / EBNF / nwdiag / SDL / math (parse, draw nothing useful)
@startmindmap
, a boxed rectangle tree, HTML/CSS mockups, or a code fence
Interactive charts (tooltip, zoom, brush)annotate directly: labels, thresholds, callouts
Icons in
vega
/
echarts
plantuml
stencils
Free-form positioning in
infographic
HTML/CSS for pixel control
以下不可能实现;选择替代方案而不是重试。
需求替代方案
3D / 地球 / WebGL 图表(无
echarts-gl
)
2D
echarts
;用
scatter
/
graph
表示形状
地理地图(无内置地图数据,无离线 GeoJSON)示意矩形布局,或 HTML/CSS 区域图
ECharts 中的
dataset.transform
(在 6.1.0 中抛出
RangeError
)
在上游排序和派生,然后使用
dataset.source
echarts
选项中的函数(按 JSON 解析)
模板字符串(
"{c}%"
),逐项标签对象
外部数据或图像(
data.url
,远程 URL)
内联
values
,数据 URL
PlantUML WBS / Salt / Timing / ditaa / JSON / YAML / EBNF / nwdiag / SDL / 数学(解析但画不出有用内容)
@startmindmap
,盒状矩形树,HTML/CSS 模型,或代码围栏
交互式图表(工具提示、缩放、刷选)直接标注:标签、阈值、标注
vega
/
echarts
中的图标
plantuml
模具
infographic
中的自由定位
使用 HTML/CSS 进行像素级控制

Converting a document

转换文档

The
documd
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 (
--assets ./figures
), 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:
npx @markdown-viewer/documd in.md out.docx
(
.pdf
·
.epub
·
.html
,
diagram.puml out.png
). ⚠️ Use the scope: bare
documd
on npm is a different package. Flags, formats and export behaviour: converting.md.
documd
CLI
做了宿主应用无法做的三件事:将文档或图表源文件转换为文件,将其图形提取为图像文件以供查看(
--assets ./figures
),并验证——渲染是证明块能绘制的唯一方法;每次失败都会返回其引擎和 markdown 行,并以退出码 1 结束。无需安装:
npx @markdown-viewer/documd in.md out.docx
(
.pdf
·
.epub
·
.html
,
diagram.puml out.png
)。 ⚠️ 注意范围:npm 上的裸
documd
是不同的包。标志、格式和导出行为:converting.md。

When a block does not render

当块不渲染时

  1. Fence in the allowed list? Exactly one block per figure?
  2. Is it a listed anti-pattern in that engine's reference (see Engine cheat sheet) — or strict syntax (JSON for
    echarts
    /
    vega
    , no empty lines in bare HTML)?
  3. Then switch to the alternative engine named in the goal guide; most scenarios have two implementations.
  4. Or verify by rendering:
    npx @markdown-viewer/documd file.md --assets /tmp/figs
    .
  1. 围栏是否在允许列表中?每个图形是否只有一个块?
  2. 是否是该引擎参考中的列出的反面模式(见引擎速查表)——或严格语法(
    echarts
    /
    vega
    需要 JSON,裸 HTML 不能有空行)?
  3. 然后切换到目标指南中提到的替代引擎;大多数场景有两种实现。
  4. 或通过渲染验证:
    npx @markdown-viewer/documd file.md --assets /tmp/figs
    。

Where everything lives

所有内容存放位置

catalog/scenarios.md
indexes every scenario with its domain, engines, tier and example path — start there; then
goals/<domain>.md
,
engines/<engine>.md
,
examples/<domain>/<file>.md
.
catalog/scenarios.md
索引了每个场景及其领域、引擎、层级和示例路径——从那里开始;然后
goals/<domain>.md
,
engines/<engine>.md
,
examples/<domain>/<file>.md
。