Document Skill original
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
documd visuals
Routing for every diagram, chart, card and layout this document pipeline can render.
Figures are text, in place. A fence (plantuml · vega · echarts · infographic) or bare HTML written into the Markdown is the figure: the viewer draws it live, the block stays editable, and nothing is pre-rendered, built or exported first. documd is optional — export and verification only.
Iron rules
- Allowed fences —
plantuml/puml·vega·vega-lite·echarts·infographic,
plus bare HTML — which is how system architecture diagrams, cards and page layouts are drawn.
- Nothing outside that list. A fence the list does not name is a bug, not a lesser option —
there is no second-tier engine.
- One diagram per fence. Do not put two engines in one block, and never nest fences.
- 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.
- Inline the data.
vega/vega-lite/echartsmust carry their ownvalues/seriesdata;
external URLs are unreliable on the export path.
- State the reading in the copy. Every figure answers one question — put it in the prose or the
block's title.
- 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.
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
| 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 |
B — process & systems
| 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 |
C — infrastructure & governance
| 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 |
D — knowledge & expression
| 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 |
Engine cheat sheet
| Engine | Reach for it when | Look elsewhere when |
|---|---|---|
plantuml | UML/ArchiMate/BPMN semantics, brand and device icons (9,514 stencils), or a relationship graph that should lay itself out | It is a chart |
vega / vega-lite | The data needs work first — join, window, fold, regression, density, facets, small multiples | One polished chart with heavy styling (echarts) |
echarts | Report-grade chart or KPI dashboard: axes, series, thresholds, annotations, gauges | The data must be transformed first |
infographic | A designed-looking board: roadmap, timeline, checklist, comparison, quadrant, knowledge map | Axes, several series or statistical shapes (echarts) |
| HTML/CSS | Cards, memos, overviews, page-level layouts | Another engine already renders that diagram |
Details, limits and pitfalls: `plantuml` · `echarts` · `vega` · `infographic` · `html-css`.
Capability boundaries
These are not possible; pick the fallback instead of retrying.
| Want | Fallback |
|---|---|
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 |
Reading a document
To read a document in the browser or in VS Code, install docu.md Markdown Viewer: <https://docu.md>.
Exporting & verifying — optional
Authoring never needs this. The `documd` CLI converts a document or a diagram source to a file, extracts figures as images, and verifies that blocks render — for when the output is a file. Nothing to install: npx @markdown-viewer/documd in.md out.docx. Flags, formats and the npm-scope warning: converting.md.
When 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/vega, no empty lines in bare HTML)?
- Then switch to the alternative engine the goal guide names; most scenarios have two.
- Or verify by rendering:
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.
