doodle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Doodle: Diagrams Over Overly Dense Long Explanations

Doodle：用图表代替冗长且密集的解释

You write one Markdown file where each drawing is a tiny

```doodle

text block. Then one command turns every block into an SVG under

img/

and swaps the block for an image link. Use the renderer instead of writing SVG by hand. Keep generated SVG markup out of context unless debugging the renderer; inspect a visual preview when needed.

<doodle>

below means

python3 <this-skill-dir>/scripts/doodle.py

你只需编写一个 Markdown 文件，其中每幅图都是一个很小的

```doodle

文本块。随后，一条命令便可将每个代码块转换为

img/

下的 SVG，并将原代码块替换为图片链接。请使用渲染器，而不是手动编写 SVG。除非在调试渲染器，否则不要将生成的 SVG 标记放入上下文；必要时查看可视化预览。

下文中的

<doodle>

表示

python3 <this-skill-dir>/scripts/doodle.py

。

Workflow

工作流程

Read the preferences. Run
```
<doodle> --settings
```
from the folder where the document will go. It prints the merged
```
doodle.json
```
settings as JSON. Use
```
audience
```
,
```
depth
```
,
```
language
```
,
```
docsDir
```
and
```
notes
```
(house rules written by the user; follow them). The current request wins over the file: "like I'm 5" means
```
kid
```
, "quick"/"rápido" means
```
quick
```
, "in depth"/"a fundo" means
```
deep
```
.
Understand first. If the topic is about this project, read the real code, logs and data. Explanations must be true; never invent evidence.
Write
<topic-slug>.md
in
```
docsDir
```
(or the current directory, or where the user asks), in the user's language unless
```
language
```
says otherwise, using the structure below.
Render:
```
<doodle> <topic-slug>.md
```
. It prints the SVG paths, then
```
warning: file:line: ...
```
lines. Fix warnings that reveal a mistake (a misspelled tone, an edge to a node that doesn't exist); the rest are judgment calls. On
```
error: file:line: ...
```
, fix that line and run again. Re-running is safe: rendered blocks are kept as
```

```
comments and re-rendered in place. Theme, colors and image folder come from
```
doodle.json
```
; don't pass
```
--theme
```
or
```
-o
```
unless the user asked for this one document.
Reply briefly: the file path plus 2–3 lines of summary. Don't paste the document into the chat.

No Python? Use

```mermaid

blocks instead (GitHub renders them) and skip step 4.

读取偏好设置。 从文档将要存放的文件夹运行
```
<doodle> --settings
```
。它会以 JSON 格式打印合并后的
```
doodle.json
```
设置。使用
```
audience
```
、
```
depth
```
、
```
language
```
、
```
docsDir
```
和
```
notes
```
（用户编写的内部规则；必须遵循）。当前请求优先于文件中的设置：“像给 5 岁小孩讲一样”表示
```
kid
```
，“quick”/“rápido”表示
```
quick
```
，“in depth”/“a fundo”表示
```
deep
```
。
先理解内容。 如果主题与当前项目有关，请阅读真实代码、日志和数据。解释必须属实；绝不可捏造证据。
编写
<topic-slug>.md
。将文件写入
```
docsDir
```
（或当前目录，或用户指定的位置），除非
```
language
```
设置另有规定，否则使用用户的语言，并采用下述结构。
渲染： 运行
```
<doodle> <topic-slug>.md
```
。它会打印 SVG 路径，然后打印
```
warning: file:line: ...
```
行。修复那些表明存在错误的警告（拼错的 tone、指向不存在节点的边）；其余警告需要自行判断。遇到
```
error: file:line: ...
```
时，修复该行并再次运行。重复运行是安全的：已渲染的代码块会保留为
```

```
注释，并在原位重新渲染。主题、颜色和图片文件夹来自
```
doodle.json
```
；除非用户要求仅对这一个文档进行相应设置，否则不要传入
```
--theme
```
或
```
-o
```
。
简短回复： 给出文件路径，再附 2–3 行摘要。不要把文档粘贴到聊天中。

没有 Python？改用

```mermaid

代码块（GitHub 可渲染），并跳过第 4 步。

Adapt to the reader

适配读者

`audience`	Write like this
`kid`	No jargon at all. Everyday metaphors in every step and title. Sentences under 12 words.
`beginner` (default)	Define each technical term the first time. A metaphor where it helps.
`developer`	Assume programming basics. Real names, file paths and short code snippets; metaphors only for the hard part.
`expert`	Dense and precise. Skip the basics, focus on the mechanism, edge cases and trade-offs.

`depth`	Shape
`quick`	Title question, "In three sentences", 1–2 drawings, one-line takeaway. Nothing else.
`standard` (default)	The full structure below with 2–4 steps.
`deep`	3–6 steps, plus the two sections marked deep below.

`audience`	写法
`kid`	完全不要使用术语。在每个步骤和标题中都使用日常生活中的比喻。每句话不超过 12 个词。
`beginner` （默认）	首次出现时定义每个技术术语。在有助于理解时使用比喻。
`developer`	假定读者掌握编程基础。使用真实名称、文件路径和简短代码片段；仅在难懂部分使用比喻。
`expert`	内容密集而精确。跳过基础知识，重点说明机制、边界情况和权衡取舍。

`depth`	组织方式
`quick`	使用问题作为标题；包含“三句话说清楚”、1–2 幅图和一句话结论。除此之外不添加其他内容。
`standard` （默认）	使用下方完整结构，共 2–4 个步骤。
`deep`	3–6 个步骤，并加入下方标有 deep 的两个章节。

Document structure (the teaching method)

文档结构（教学方式）

undefined

undefined

<Question the reader actually has, e.g. "Why does the app log me out every morning?">

In three sentences -> 3 numbered sentences: what happens, why, what fixes it

Pieces you need to know -> table | Piece | What it is | or a

hub

drawing (only if 3+ unfamiliar terms)

Pieces you need to know -> table | Piece | What it is | or a

hub

drawing (only if 3+ unfamiliar terms)

Step 1: <one claim> -> one doodle + 2–5 bullets; end with the "why"

Step 2: ... -> 2–5 steps total

When it happens / Why it matters

Common mistakes -> deep only: 2–4 bullets, each a mistake and how to avoid it

Evidence -> only real logs, numbers, file paths; a

bars

drawing for numbers (omit if none)

Evidence -> only real logs, numbers, file paths; a

bars

drawing for numbers (omit if none)

Check yourself -> deep only: 2–3 questions, each answer in <details><summary>Answer</summary>…</details>


Numbers that only illustrate (not measured) can go in a step's `bars` drawing; say so in its subtitle, e.g.
`> illustrative numbers`. The Evidence section holds only real data.

Writing rules: short sentences; plain words; **bold** the key fact in each step; one idea per drawing; the drawing's
title states the step's claim; tones tell the story (`bad` = the broken part, `ok` = the fix or healthy path,
`warn` = the risky step, `info` = the actor or input).


仅用于举例说明（而非实测）的数字可以放在某一步的 `bars` 图中；应在副标题中说明，例如 `> illustrative numbers`。“Evidence”章节只包含真实数据。

写作规则：句子要短；用词要平实；每一步都要**加粗**关键事实；每幅图只表达一个想法；图的标题应陈述该步骤的结论；Tone 用来讲述整个过程（`bad` = 故障部分，`ok` = 修复方案或健康路径，`warn` = 风险步骤，`info` = 执行者或输入）。

Doodle blocks (cheat sheet)

Doodle 代码块（速查表）

doodle

timeline: A pizza order
> optional subtitle
Order placed | the app sends it to the shop | info
Oven is full | waits 20 minutes | warn
Delivered | still hot | ok

Line 1 is
```
kind: Title
```
. Each row is
```
label | note | tone
```
; note and tone are optional.
Tones:
```
neutral
```
(default),
```
info
```
,
```
ok
```
,
```
bad
```
,
```
warn
```
. Options:
```
@sketch
```
(hand-drawn),
```
@vertical
```
,
```
@horizontal
```
,
```
@arrow
```
(for
```
compare
```
,
```
stack
```
,
```
hub
```
),
```
@theme NAME
```
.
```
\n
```
breaks a line;
```
//
```
starts a comment.
Keep labels ≤ 4 words and notes ≤ 12 words. Use 3–6 rows; split bigger ideas into two drawings.

kind	use it for	extra syntax
`timeline`	what happens in what order	rows only (numbered automatically)
`flow`	steps, decisions, branches	`[id] Label \| note \| tone` rows, then `a -> b: label` ; `~>` = dashed. No edges = a chain of the rows
`cycle`	loops, things that keep repeating	rows only, in loop order
`compare`	before/after, A vs B, wrong vs right	`## Column \| tone` then rows (items inherit the column tone); `@arrow` puts → between columns
`tree`	folders, hierarchies, parts of a whole	indent children by 2 spaces
`stack`	layers (architecture, network, call stack)	rows top to bottom; `@arrow` links them
`sequence`	who talks to whom (requests, protocols)	`A -> B: message \| tone` ; `~>` = reply (dashed); `A -> A` = self
`bars`	how much: time, size, count, cost	`Label \| 120 ms \| tone` ; the note holds the number
`hub`	what something is made of; key vocabulary	first row is the center, the others go around it

Full syntax and examples: references/dsl.md. Read it only if the cheat sheet isn't enough.

doodle

timeline: A pizza order
> optional subtitle
Order placed | the app sends it to the shop | info
Oven is full | waits 20 minutes | warn
Delivered | still hot | ok

第 1 行是
```
kind: Title
```
。每一行是
```
label | note | tone
```
；
```
note
```
和
```
tone
```
可省略。
Tone：
```
neutral
```
（默认）、
```
info
```
、
```
ok
```
、
```
bad
```
、
```
warn
```
。可用选项：
```
@sketch
```
（手绘）、
```
@vertical
```
、
```
@horizontal
```
、
```
@arrow
```
（用于
```
compare
```
、
```
stack
```
、
```
hub
```
）、
```
@theme NAME
```
。
```
\n
```
用于换行；
```
//
```
用于开始注释。
标签不超过 4 个词，备注不超过 12 个词。每幅图使用 3–6 行；较大的想法应拆成两幅图。

kind	用途	额外语法
`timeline`	按顺序发生的事情	仅使用行（自动编号）
`flow`	步骤、决策、分支	`[id] Label
`cycle`	循环、不断重复的事情	仅使用行，按循环顺序排列
`compare`	之前与之后、A 与 B、错误与正确	`## Column
`tree`	文件夹、层级、整体组成部分	子项缩进 2 个空格
`stack`	层（架构、网络、调用栈）	从上到下排列各行； `@arrow` 连接各层
`sequence`	谁与谁通信（请求、协议）	`A -> B: message
`bars`	数量度量：时间、大小、计数、成本	`Label
`hub`	某事物由什么组成；关键词汇	第一行是中心，其他行围绕中心排列

完整语法和示例：references/dsl.md。仅在速查表不够用时阅读。

Personalize

个性化

When the user states a lasting preference ("always use the chalk theme", "my team are senior devs", "save these in docs/explain", "use our brand purple"), save it instead of just applying it once:

For this project: edit the
```
doodle.json
```
that
```
--settings
```
lists last in
```
sources
```
(the nearest one), or create one at the repository root with
```
<doodle> --init
```
. Files cascade: one in a subfolder overrides only the keys it names, for documents in that subfolder.
For every project: edit
```
~/.config/doodle/config.json
```
.
For one document only: add
```
@theme NAME
```
to its blocks, so re-renders keep the look.

Then re-render any document they are looking at. Settings:

theme

(

paper

clean

candy

blueprint

chalk

sketch

scheme

(

auto

light

dark

colors

(per tone,

#hex

imageDir

audience

depth

language

docsDir

notes

. Details and examples: references/customize.md.

当用户说明一项长期偏好（“始终使用粉笔主题”“我的团队都是资深开发者”“把这些保存到 docs/explain”“使用我们的品牌紫色”）时，应保存该偏好，而不是只应用一次：

针对当前项目：编辑
```
--settings
```
输出的
```
sources
```
中最后列出的
```
doodle.json
```
（即距离最近的那个），或在仓库根目录运行
```
<doodle> --init
```
创建。配置会逐层合并：子文件夹中的文件仅覆盖其明确指定的键，并适用于该子文件夹中的文档。
适用于所有项目：编辑
```
~/.config/doodle/config.json
```
。
仅适用于一个文档：在其代码块中添加
```
@theme NAME
```
，这样重新渲染时仍会保留该外观。

然后重新渲染用户正在查看的文档。设置项包括：

theme

（

paper

、

clean

、

candy

、

blueprint

、

chalk

）、

sketch

、

scheme

（

auto

light

dark

）、

colors

（按 Tone 配置，使用

#hex

）、

imageDir

、

audience

、

depth

、

language

、

docsDir

、

notes

。详情和示例：references/customize.md。

doodle

Original

Translation

Doodle: Diagrams Over Overly Dense Long Explanations

Doodle：用图表代替冗长且密集的解释

Workflow

工作流程

Adapt to the reader

适配读者

Document structure (the teaching method)

文档结构（教学方式）

<Question the reader actually has, e.g. "Why does the app log me out every morning?">

<Question the reader actually has, e.g. "Why does the app log me out every morning?">

In three sentences -> 3 numbered sentences: what happens, why, what fixes it

In three sentences -> 3 numbered sentences: what happens, why, what fixes it

Pieces you need to know -> table | Piece | What it is | or a
`hub`
drawing (only if 3+ unfamiliar terms)

Pieces you need to know -> table | Piece | What it is | or a
`hub`
drawing (only if 3+ unfamiliar terms)

Step 1: <one claim> -> one doodle + 2–5 bullets; end with the "why"

Step 1: <one claim> -> one doodle + 2–5 bullets; end with the "why"

Step 2: ... -> 2–5 steps total

Step 2: ... -> 2–5 steps total

When it happens / Why it matters

When it happens / Why it matters

Common mistakes -> deep only: 2–4 bullets, each a mistake and how to avoid it

Common mistakes -> deep only: 2–4 bullets, each a mistake and how to avoid it

Evidence -> only real logs, numbers, file paths; a
`bars`
drawing for numbers (omit if none)

Evidence -> only real logs, numbers, file paths; a
`bars`
drawing for numbers (omit if none)

Check yourself -> deep only: 2–3 questions, each answer in <details><summary>Answer</summary>…</details>

Check yourself -> deep only: 2–3 questions, each answer in <details><summary>Answer</summary>…</details>

Doodle blocks (cheat sheet)

Doodle 代码块（速查表）

Personalize

个性化