Idyll 的语法和 Markdown 有什么关系?

更新时间

Idyll 的语法以 Markdown 的基本原则为基础，并复用了大量相同的写法：想输出文字，直接写就行。区别在于，Idyll 在文本中加入了特殊语法，让你可以内联嵌入 JavaScript，从而把普通文档变成可交互的页面。它适合用来做“可探索的解释”、数据驱动的故事，或给博客和内容管理系统增加交互性；输出既可以是独立网页，也可以嵌入已有页面。

相同之处：文本照常写

Idyll 从 Markdown 的同一套原则出发，普通段落、行文方式不需要额外标记。你写下的文字会直接出现在输出中，这一点和 Markdown 的体验一致。因此，已有 Markdown 写作习惯的人上手时，不需要先学一套全新的文本标记。

不同之处：用标签嵌入组件

Idyll 的核心能力来自“标签 + JavaScript”。在文本中插入如下形式的标签，就能引入一个组件：

Lorem ipsum...
[ComponentName property:variableValue onEvent:`variableValue = 5` /]
Lorem ipsum...

每个标签对应一个 React 组件，标签里写的属性会作为 props 传给该组件。属性值可以是响应式变量，也可以是表达式。Idyll 会负责监听变量变化，并在需要时重新渲染组件——也就是说，你不需要手动操作 DOM 来更新界面。

响应式：变量驱动图表

文档给出的图表例子很能说明这套机制。先写一个静态正弦波：

[Chart equation:`(t) => Math.sin(t)` domain:`[0, 2 * Math.PI]` samplePoints:1000 /]

再用变量把输出参数化：

[var name:"func" value:`Math.sin` /]
[var name:"domainStart" value:0 /]
[var name:"domainEnd" value:`2 * Math.PI` /]
[Chart equation:`(t) => func(t)` domain:`[domainStart, domainEnd]` samplePoints:1000 /]

此时图表会随 func、domainStart、domainEnd 的取值变化而更新。变量可以由用户操作触发，例如按钮点击：

[Button onClick:`func = Math.sin`]sin[/Button]
[Button onClick:`func = Math.cos`]cos[/Button]

也可以绑定到标准输入控件（如调整定义域起止值的输入框）。这体现了 Idyll 与 Markdown 的关键差异：Markdown 描述的是静态排版，Idyll 描述的是“文本 + 状态 + 组件”的文档，状态一变，组件就重绘。

生态与发布

  • 内置多种开箱即用的组件，可直接用于构建丰富文档。
  • 兼容 D3、P5 等图形库，并支持 npm 上大多数 JavaScript 库。
  • 提供内置主题，也可自定义 CSS。
  • 官方提供免费的公共托管服务，可将作品发布到网上。

怎么选

如果你只需要排版静态文章，Markdown 足够；如果你希望读者能操作参数、看到图表或内容随交互变化，并且愿意在文本里写少量 JavaScript 表达式和组件标签，Idyll 的 Markdown 式写法能明显降低上手成本。需要进一步了解组件清单和示例，可查看官网的示例画廊与文档。