mdbook-pikchr 操作手册

mdbook-pikchr 会把 pikchr fenced code block 渲染成 SVG 图，适合论文式框图、结构图和需要精确相对布局的技术示意图。

原仓库：https://github.com/podsvirov/mdbook-pikchr

最基础的框和箭头

对应源码：

```pikchr
box "Client"
arrow
box "Server"
```

横向流程

对应源码：

```pikchr
right
box "Query"
arrow
box "Index"
arrow
box "Top-k"
```

纵向流程

对应源码：

```pikchr
down
box "Controller"
arrow
box "Worker"
arrow
box "SSD"
```

常用图形元素

Pikchr 常见对象包括：

box
circle
ellipse
line
arrow
move
text

常用方向：

right
left
up
down

样例：不同形状

对应源码：

```pikchr
right
box "Box"
arrow
circle "C"
arrow
ellipse "Ellipse"
```

用变量重复布局

Pikchr 的优势之一是可以给对象命名，之后基于对象位置继续画图。

A: box “Controller” B: box “Worker” right of A arrow from A.e to B.w

/*    1 */  A: box "Controller"
/*    2 */  B: box "Worker" right of A
                            ^^^^^
ERROR: use with line-oriented objects only

对应源码：

```pikchr
A: box "Controller"
B: box "Worker" right of A
arrow from A.e to B.w
```

对象的常用锚点包括：

.n  north
.s  south
.e  east
.w  west
.ne .nw .se .sw

这比只依赖自动排版更适合需要精确连接位置的论文框图。

样例：一对多结构

C: box “Controller” W1: box “Worker 1” below left of C W2: box “Worker 2” below right of C arrow from C.s to W1.n arrow from C.s to W2.n

/*    1 */  C: box "Controller"
/*    2 */  W1: box "Worker 1" below left of C
                                     ^^^^
ERROR: use with line-oriented objects only

对应源码：

```pikchr
C: box "Controller"
W1: box "Worker 1" below left of C
W2: box "Worker 2" below right of C
arrow from C.s to W1.n
arrow from C.s to W2.n
```

图的对齐方式

mdbook-pikchr 支持配置整个渲染图在页面中的水平对齐：

[preprocessor.pikchr]
align = "center"

可选：

left
center
right

默认是 center。

当前书库配置

[preprocessor.pikchr]

因此当前使用默认居中对齐。

Mermaid 和 Pikchr 怎么选

用 Mermaid：

• 流程图；
• 时序图；
• 状态机；
• ER 图；
• 关系复杂但不关心像素级布局的系统图。

用 Pikchr：

• 论文中的简洁框图；
• 需要控制对象相对位置；
• 箭头必须从某个框的特定边进入/离开；
• 希望最终图像更像传统技术论文中的手工制图。