Syntax

Idyll markup is an extension of markdown, which is meant to be easy to read and write. The main extensions are reactive variables, and components. Together these two elements can be used to create dynamic, interactive articles.

We provide syntax highlighting plugins for several editors:

If you'd like a syntax highlighter for a different editor, please open an issue on github.

Idyll tries to maintain parity with popular markdown implementations, but sometimes doesn't get things exactly right. If something seems off, feel free to open an issue.

Text
Components
- Properties
Variables
- Derived Variables
Datasets

Text

By default everything in Idyll is text. To make common formatting tasks easier, Idyll borrows some syntax from markdown.

Bold, italic

Text surrounded by asterisks (*) will be bolded, e.g. *italic* becomes italic, and **bold** becomes bold.

Headers

Use a pound sign (#) to denote a header:

# Title h1
## Title h2
### Title h3
#### Title h4
##### Title h5
###### Title h6

Code

Text placed between backticks (`) will be displayed inline as code: `y = x * x` becomes y = x * x.

Text placed between groups of three backticks will be displayed as a code block.

This is a code block

The above code block is created with this code:

```
This is a code block
```

Lists

Ordered and unordered lists are supported. Lists can be created by using an asterisk (*) or numbers. For example:

* Unordered item one
* Unordered item two
* Unordered item three

1. ordered item one
2. ordered item two
3. ordered item three

Components

Besides text, components are the other basic building block of an Idyll document. Components are denoted with brackets, and can be invoked in one of two ways: they can be self closing,

[Range min:0 max:10 value:value /]

or have a closing and opening tag with content in between.

[Button]
Click Me
[/Button]

Component properties

Properties can be passed into components in the following ways:

Literals: number, string, boolean

Number, string, or boolean literals may be used.

[Component propName:10 /]
[Component propName:'propValue' /]
[Component propName:false /]

Variable and datasets

A variable or dataset can be passed in directly, this will automatically create a binding between that variable and property, more on this in the section on variables and datasets.

[Component propName:myVar /]

If the variable changes that update will immediately be reflected in the state of the component.

Expressions

Use backticks to pass an evaluated expression:

[Component propName:`2 * 2 * 2` /]
[Component propName:`{ an: 'object' }` /]

Note that because Idyll is reactive, if a variable changes, any expressions that reference that variable will immediately be recomputed. See this utilized to create reactive vega-lite specifications: https://idyll-lang.org/examples/csv/.

If the property expects a function, the expression will automatically be converted to a callback. This is convenient for updating variables on events, for example.

[Component onClick:`myVar++` /]

Idyll uses naming conventions to determine if the expression should be converted to a callback. Properties that are named onXxxxx (e.g. onClick) or handleYyyyy (e.g. handleMouseMove) are assumed to expect callbacks.

Refs

There is a special property called ref that allows you to create a reference to specific component on the page. This is primarily used to keep track of elements on the page as a reader scrolls. See the section on refs for more details.

Variables

Variables can be declared at any point in an Idyll file. Variables use the same syntax as a component, but must defined a name and a valueproperty.

[var name:'x' value:10 /]

The above code defines a variable x, with the initial value of 10.

Derived Variables

A derived variable is similar to a var, but its value is derived from other variables, and is recomputed whenever values change:

[derived name:'xSquared' value:`x * x` /]

The above code defines a derived variable xSquared that depends on the value of x. The value of xSquared is automatically updated based on the value of x.

Datasets

A dataset is similar to a variable, except instead of expecting avalue, datasets must be provided with a source (the name of the data file).

Example:

[data name:'myData' source:'myData.csv' /]
[Table data:myData /]

The above code declares a dataset, and uses it as input to a Table component. Datasets can be either .csv or .json files. CSV files will automatically be converted to a JSON object. You can also fetch data from a url.