Configuration and Styles

Command Line Options

The idyll command line tool accepts the following options

  • --css the path to your CSS file. You can use this to override Idyll's default styles, e.g. $ idyll index.idl --css my-custom-styles.css.
  • --components the path to your custom components. By default this points to components/.
  • --datasets the path to the folder containing your datasets. By default this points to data/.
  • --layout the name of the layout to use. By default this is blog. More on layouts below.
  • --theme the name of the theme to use. By default this is idyll. More on themes below.
  • --output the location to place built files in
  • --build the build flag tells Idyll to output the compiled JavaScript instead of running a server and opening your page in a web browser.

If you are using Idyll via the project generator, open package.json to change these options.

Themes and Page Layout

Idyll exposes two options to help you style your project, layout and theme. layout deals with CSS styles related to how your content is layed out on the page: width, columns, etc. The theme option allows you to choose diffent stylesheets to change the style of the content itself (text color, font, and so on).


Idyll currently ships with several page layouts that can be used to modify the structure of how to content is displayed on the page, allowing you to quickly test out different narrative styles for you project.


The centered layout puts your content in the center of the page and is mobile responsive.


This is the default layout. The blog layout is fairly traditional article layout with room in the margin to put notes and other callouts. See for an example of this layout.


If you set --layout none Idyll won't provide any structural CSS, allowing you to customize things to your heart's content.



This is the default theme, it uses CSS that resembles the styles in GitHub READMEs.


This theme uses custom styles that go along with Idyll's look and feel. See for an example of this style.


The Tufte theme uses styles from


Using Idyll as an API

You can use Idyll directly from JavaScript as well. This is useful if you want to build on top of Idyll, for example, you could make a static blog engine that uses Idyll to compile the blog posts.


var Idyll = require('idyll');

var idyll = Idyll({
  inputFile: 'my-file.idl'
  output: 'build/',
  htmlTemplate: '_index.html',
  componentFolder: './components/'
  dataFolder: './data',
  layout: 'centered',
  theme: 'github'
     .on('update', () => {}) // the compilation finished.
     .on('error', () => {}) // there was an error

If you pass live: true to Idyll, it will continue to watch the input files for changes, and will emit the update event each time that the output is rebuilt.

Continue to the next section to learn about Idyll components.