Idyll 是什么网站?

更新时间

Idyll 是一个用于创建交互式文档的标记语言，idyll-lang.org 是它的官方文档站。它适合三类任务：制作“可探索式解释”（读者能操作变量、观察结果变化的说明页）、撰写数据驱动的故事，以及给博客或内容管理系统增加交互性。产出物既可以是独立网页，也可以嵌入现有页面。文档站说明它提供内置主题与自定义 CSS，并提供免费公共托管服务，可将作品发布到网上。

它和 Markdown 的关系

Idyll 从 Markdown 的基本原则出发，沿用大量相同语法：想让文字出现在输出里，直接写就行。区别在于它允许把 JavaScript 嵌入文本，用特殊语法把变量、表达式和组件接进正文。文档给出的组件写法形如：

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

每个标签对应一个 React 组件，组件接收传入的属性。属性可以是响应式变量或表达式，Idyll 负责监听变量更新并重新渲染组件。它兼容 D3、P5 等图形库，也能支持 npm 上可用的大部分 JavaScript 库。

一个具体例子：从静态图到可交互图

文档用图表组件演示了交互是怎么来的。先是一个静态正弦波：

[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 /]

变量再绑定到用户操作上，图表就会随点击或输入变化。文档示例中，按钮通过 onClick 把 func 设为 Math.sin 或 Math.cos；输入控件则绑定到定义域的起止值（示例里出现“Update Domain Start / End”的输入项）。这就是“可探索式解释”的最小结构：文本负责叙述，变量负责状态，组件负责呈现。

适合谁、什么时候选它

你的需求 Idyll 是否合适 说明
写带交互的说明文档、教学页 合适 正文接近 Markdown，交互用标签和变量表达
做数据驱动的叙事 合适 可接 D3、P5 等库，图表可随变量更新
给现有博客/CMS 加交互 可考虑 支持嵌入现有页面，也支持生成独立网页
只想写纯静态文章 未必需要 不涉及交互时，普通 Markdown 工具更轻
需要现成主题快速出样式 可考虑 有内置主题，也支持自定义 CSS

选择前值得确认两点：你的内容是否真的需要“读者操作—结果变化”这一层，如果不需要，引入组件和变量的成本就不划算；以及你是否接受用标签语法写交互，而不是在图形界面里拖拽配置。

上手路径与验证方法

文档站给出的路径是：先按 Markdown 习惯写正文，再在需要交互的位置插入组件标签，用 var 定义状态，把状态绑到组件属性或按钮、输入控件的事件上。发布环节，文档提到免费公共托管服务，可把作品发布到网上；具体入口和操作步骤以站内文档为准。

验证是否跑通，可以按文档示例做一次最小闭环：写一个静态 Chart，确认能渲染；改成用 var 提供函数和定义域，确认图表随变量值变化；再加一个按钮修改该变量，确认点击后图表更新。三步都成立，说明变量监听与重渲染这条链路是通的。常见卡点是属性值里的表达式写法（反引号包裹）和事件绑定（onClick 内为赋值表达式），照示例格式核对通常能定位问题。

更多组件用法和完整示例，可继续阅读 idyll-lang.org 的文档正文与示例画廊。