Before starting:

If you’ve never heard about Idyll I suggest taking a look to this post to install it.

Some good pratices for Cerfacs new users

Best practices

1. Stick to Markdown text to keep the post human readable from the source.
2. There are , to our knowledge, no comment character, making the source harder to debug. In the worst case, copy/paste the whole contant somewhere, remove all, and paste back your source bit by bit.
3. Gather all your Idyll var and derived statements at the beginning of your document. This is easier to read and edit afterward
4. the [Fixed] component must be stated at the very beginning of your document.
5. the LaTeX [Equation] component is apparently bugged, at least on my install, and reapeat the content as plain text : $E=mc^2$
6. There are Idyll syntax highlithing plugins for Visual studio code, Atom and Sublime.
7. Use javascript’s methods .toPrecision(3) and .toExponential(3) to format numbers outputs.

Handling errors

If parser errors are not accurate/explicit, your document is probably ill-formed. Pay attention to closing tags. For example [/br] can easily be mityped as [\br], [br] or [br/]). In equations a missing parenthesis is often yields errors at line 1:

SyntaxError: Unexpected token (1:39)
    (...)
  pos: 39,
  loc: Position { line: 1, column: 39 },
  raisedAt: 40
}
Error occurred in Idyll expression

When the output is apprently wrong and you do not get why, open your best browser console, you can get hints from the Javascript errors.

Now let’s talk about serious matters

Add dynamic graphics with React components

As you may know, with Idyll you can easily include any open-source React components in your project, but not only. You can also include chart.js or D3.js components.

Do you like the graph you can see on your right ? You can easily add it in your project without much of coding !

To do so, install the react component with npm by running the following command in your terminal:

npm install react-simple-pie-chart --save

Then, include it in your markup by adding the code below in your project:

[ReactSimplePieChart
  slices:`[{
    color: 'green',
    value: x,
  }, {
    color: '#EAE7D6',
    value: y, },
  ]` /]

The component will be instantiated and displayed on your page.

Other example

Here is another example to make sure you understand the process.
Imagine, you want to add in your page a histogram. To do so, you just have to search on the internet a react component:

On your right, you can see that in our example, to install the Histogram you must write de command:

npm install react-chart-histogram

Note: yarn add is equivalent to npm install

And then, write on you post the code below:

 [ReactChartHistogram
      xLabels:`["2016", "2017", "2018"]`
      yValues:`[324, 45, 672]`
      width:'400'
      height:'200'
      options:`{ fillColor: '#FFFFFF', strokeColor: 'green' }` /]

After that, the graph you can see on the side will be displayed in your Idyll article.

As you may have noticed, the code written above isn’t exactly the same as the one in the video. Indeed, there are some little differences. First of all, with idyll the syntax of the component is not <Histogram .../> but [ReactChartHistogram .../]. Indeed, you have to use the same name you used as when you installed the component with npm, otherwise Idyll will not recognize it during the compilation.
Then, on Idyll, all the = must be replaced by :.
And finally, when you see some braces on the code, replace them by backquotes.
Those are the main differences.

Add a chart with axis names

To generate a chart with axis names we will use Vega-Lite.

Tu use this visualization tool, follow those instructions.

Here is the code to generate the graph visible on the right.

[data name:"exampleData" source:"exampleData.csv" /]

[IdyllVegaLite data:exampleData spec:`{
  mark: "line",
  encoding: {
    x: {
      field: "time",
      type: "temporal",
      axis: {title: "Year"} //name for the x-axis
    },
    y: {
      field: "value",
      type: "quantitative",
      axis: {title: "Water level"}, //name for the y-axis
      scale: { domain: [575, 582] }
    }
  },
  config: {
    mark: {
      color: "green"
    }
  }
}` /]

You can modify the type of the chart by changing the second line with the mark type. You can add either a: area, bar, circle, line, point, rect, rule, square, text, tick, or geoshape type.

You can go to the site of Vega-Lite and view the different charts possibilities.
For example, let’s choose this type of line chart (the one you can see on the side). You just have to copy the code that is presented in the Vega-Lite site and paste it in your Idyll project just like this:

Change the layout of your post

If you have visited the explorable explanations blog, you may have noticed that the layout of the different posts is not always the same.

Indeed, with Idyll you can choose what will be the layout of your text. This part of the Idyll documentation talks about it.

For example, if you want a style post such as the article “What is a code review?”, go in the package.json file of your project and change the line "layout": "centered" into "layout": "blog". Then, you will have to recompile your project and the post will update.

Include a top-bar navigation element

If you want to add the element you can see below in your post, follow these guidelines.

Create a component

Display the component in the idyll post

[BarMenu /]

You will now be able to view your navigation bar at the top of your Idyll post.

Small mistakes to avoid

You may frequently have compilation errors with Idyll without knowing where the problem comes from exactly.

It could often happen that, while using components, you get syntax errors. It can, indeed, be quite tricky.
For example, if you want to use any Idyll components, be careful not to confuse / with \. If you want to use the component aside, write: [aside]..[/aside] and not: [aside]..[\aside].
Also, if you want to go back to the line or skip lines with br, the right syntax is: [br/].