idyll-lang.org

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”的输入项）。这就是“可探索式解释”的最小结构：文本负责叙述，变量负责状态，组件负责呈现。

适合谁、什么时候选它

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

上手路径与验证方法

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

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

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

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 式写法能明显降低上手成本。需要进一步了解组件清单和示例，可查看官网的示例画廊与文档。

Idyll 可以配合大多数发布在 npm 上的 JavaScript 库使用，官方文档明确点名兼容 D3 和 P5 这类图形库。前提是你的库能作为 React 组件生态的一部分被引入——因为 Idyll 中每个标签都对应一个 React 组件，组件接收你传入的属性，属性值可以是响应式变量或表达式，Idyll 负责监听变量变化并重新渲染。

机制：标签即组件，属性即数据

Idyll 的交互能力来自一条简单的映射规则：你在文本里写的标签，会被当作 React 组件渲染；标签上的属性，会作为 props 传给该组件。

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

这段语法说明三件事：

• 属性可以绑定变量：property:variableValue 把变量值传给组件。
• 属性可以是表达式：用反引号包裹的 `variableValue = 5` 会在事件触发时执行。
• 更新自动生效：变量变化后，Idyll 自动重新渲染相关组件，不需要手写刷新逻辑。

因此，判断一个库能否在 Idyll 里用，关键不是"Idyll 有没有内置它"，而是"它能否被包装成接收 props 的 React 组件"。

图形库：D3 与 P5

官方文档将 D3 和 P5 列为兼容的图形库。这类库的典型用法是：把绘图逻辑封装进一个组件，通过属性把数据、定义域、采样点等参数传进去。

文档给出的内置 Chart 组件示例可以直接说明这种模式：

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

变量再通过按钮或输入控件更新，图表就会随之重绘：

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

同样的变量也可以绑定到标准输入控件上（例如更新定义域的起点和终点），实现滑块调参式的探索体验。这套"变量 → 属性 → 组件重渲染"的链路，对 D3、P5 封装的组件同样适用。

普通 JavaScript 库

文档的表述是"可以支持 npm 上大多数 JavaScript 库"。这是一个范围较宽但带保留的说法，实际可用性取决于库本身的形态：

选择时的判断条件很简单：如果你的库需要一个容器元素并自行管理渲染，就把它包进一个 React 组件，把 Idyll 变量作为 props 传入，在组件内部完成初始化与更新。这样既保留了库的原生用法，又能接入 Idyll 的响应式机制。

能做出什么

按文档描述，Idyll 适合创建可探索的解释性文档、数据驱动的叙事，以及为博客引擎和内容管理系统增加交互性；产物可以是独立网页，也可以嵌入现有页面。样式上可选内置主题或自定义 CSS，官方还提供免费的公共托管服务用于发布作品。

如果你的目标是"用熟悉的 JS 图形库做可交互的图表或可视化叙事"，Idyll 的组件模型能承接；如果某个库无法以组件形式接入，就需要先评估封装成本，再决定是否采用。

Idyll 提供免费公共托管服务，作品可以发布到网上，页面说明称只需几秒即可完成。发布前需要先明确产物的形态：Idyll 既能生成独立网页，也能嵌入已有页面；样式上可选内置主题或提供自定义 CSS。若想先看成品效果，官网的示例画廊（example gallery）是现成的入口；进一步的项目说明和支持信息则在页面的 Support 部分。

发布前先确定产物形态

Idyll 的定位是“用于交互式文档的标记语言”，官方概述列出三类典型用途：可探索式解释（explorable explanations）、数据驱动故事，以及给博客引擎和内容管理系统增加交互性。这决定了发布方式有两种：

• 独立网页：适合单独分享一个交互式解释或数据故事。
• 嵌入已有页面：适合在现有博客或 CMS 中插入交互模块，而不另起一个站点。

样式方面，内置主题可以直接套用；需要匹配品牌或版式时，再提供自定义 CSS。这一步建议在发布前完成，因为托管发布的是最终产物。

发布到免费公共托管

页面明确提供免费公共托管服务，用于把创作发布到 Web，描述为“几秒内”完成。资料没有给出具体命令、账号要求或操作菜单，因此这里不编造步骤。可核对的行动路径是：

1. 在本地完成文档，确认它能正常渲染、交互组件（如按钮、输入控件）按预期响应变量变化。
2. 选择产物形态：独立网页，或准备嵌入的片段。
3. 确定样式：内置主题或自定义 CSS。
4. 使用官方免费公共托管服务发布，然后访问生成的地址验证效果。

如果发布后交互没有生效，优先检查变量绑定和组件属性是否写对——Idyll 的交互依赖变量更新后触发组件重新渲染，属性值写错时页面可能“看起来正常但不响应”。

用示例画廊和支持部分继续深入

官网概述页设有 Example Usage 与 Support 两个小节。Example Usage 展示了默认组件的用法，例如用 Chart 组件绘制正弦曲线：

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

这段代码目前是静态图；把 equation、domain 换成变量后，图表就能随用户操作动态更新。页面给出的做法包括用 [var name:"func" value:Math.sin /] 声明变量，再通过按钮的 onClick 修改它：

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

也可以把变量绑定到标准输入控件上，例如用输入框调整 domain 的起点和终点。这类“变量 + 组件 + 事件”的组合，正是发布前最值得在本地验证的部分。

想了解项目全貌和获取帮助，从页面 Support 部分进入；想找可参考的成品，从 example gallery 进入。两者都是官网提供的入口，不需要额外注册即可浏览。

适用条件与限制

这套流程适合想快速把交互式文档放到网上、又不想自建托管的人。需要注意：资料只说明托管服务免费、发布快，未提及存储空间、自定义域名、访问统计或长期可用性等细节，这些应在正式依赖前自行确认。若作品需要嵌入已有站点，还要确认目标 CMS 是否允许插入 Idyll 生成的页面或片段。

Idyll 适合制作可探索式解释（explorable explanations）、数据驱动故事，以及给博客或内容管理系统增加交互性的页面。它既能生成独立网页，也能嵌入已有页面。它的写法从 Markdown 的基本思路出发，文本直接写，需要交互时再用特殊语法嵌入 JavaScript 和组件；每个标签对应一个 React 组件，组件接收属性，属性可以是响应式变量或表达式，变量更新后 Idyll 负责重新渲染。因此，判断一个内容点子是否适合 Idyll，关键看它是否需要“文字叙述 + 可调参数 + 即时图形反馈”的组合。

三类典型内容

可探索式解释

读者一边读文字，一边通过按钮、滑块改变图形或数据，自己“试出”结论。Idyll 文档给出的正弦波图表就是最小例子：先用 [Chart ... /] 画一条静态曲线，再用变量把函数和定义域参数化，最后把变量绑到按钮点击或标准输入控件上。

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

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

这段代码的输入是变量声明和组件标签，动作是点击按钮改写 func，预期结果是图表按新函数重绘。同样的变量也可以绑定到输入控件，让读者直接调整定义域起止值。

数据驱动故事

把叙述文字和图表、交互控件穿插在同一文档里，读者滚动阅读时能操作数据视图。Idyll 兼容 D3、P5 等图形库，也支持 npm 上大多数 JavaScript 库，所以常规的图表绘制和数据可视化库可以沿用。适合的场景例如：一篇解释抽样误差的文章，让读者拖动样本量看分布变化；或一篇讲增长曲线的文章，让读者调整增长率观察曲线形态。

博客与 CMS 中的交互增强

Idyll 可以生成独立网页，也可以嵌入现有页面，因此不必整站迁移。已有博客里想加一个可交互图表或小演示，可以只把这一块做成 Idyll 内容嵌入。内置主题可直接选用，也可以提供自定义 CSS。

能力边界与选择条件

如果你的内容主要是静态长文、不需要读者调参数看反馈，用普通 Markdown 更省事；如果核心体验是“读者动手改、页面立刻变”，Idyll 的变量驱动重渲染正好对应这个需求。

上手前要准备什么

1. 确认内容形态：先写清楚读者要调整哪个变量、看到什么变化。变量设计不清，组件再多也做不出可探索感。
2. 准备 JavaScript 基础：至少要能写 (t) => Math.sin(t) 这类表达式，并理解变量赋值会触发重渲染。
3. 选发布路径：先用免费公共托管服务发布验证，再决定是否嵌入现有站点。
4. 验证方法：改一次变量值，确认图表或组件随之更新；再分别测试按钮点击和输入控件两条绑定路径。

常见卡点集中在变量作用域和组件属性写法：属性值需要用反引号包裹表达式，变量名要与 [var] 声明一致，否则组件拿不到更新后的值。文档中的示例画廊可以作为对照参考，先跑通正弦波例子再改造成自己的内容。