Troubleshooting and tips

Here are some common issues we’ve encountered, especially when we’re new to the Electric Book workflow.

Checking markdown syntax

Use a good text editor that colour-codes markdown as you work. We like Sublime Text (with MarkdownEditing installed and set to MultiMarkdown) or Notepad++ (with this markdown highlighter).

Jekyll and GitHub

Using includes inside blockquotes

If you use {% include figure %} inside a markdown blockquote, for instance if you’re creating a box, the figure breaks the box. This is because the Liquid tag itself, when processed, adds a blank line in the markdown. To kramdown, it looks like your > blockquote is finished. And at the next > after the include, a new blockquote starts – where you wanted one continuous blockquote.

Issues with newlines at Liquid tags is a widespread PITA. It’s possible that this will be simpler to solve when Jekyll uses Liquid 4, which seems to provide special syntax for removing whitespace. Till then, this workaround works well: capture the include and output the captured result with the strip_newlines filter. Here is an example.

This will not work:

> This figure shows the different paths taken by these economies. 
> 
> {% include figure image="fig.jpg" %}
> 
> Notice that West Germany started from a more favourable position in 1950 than East Germany. Yet in 1936, before the war began, the two parts of Germany had virtually identical living standards. 
{:.box}

And this does work:

> This figure shows the different paths taken by these economies. 
> 
> {% capture myfigure %}
{% include figure image="fig.jpg" %}
{% endcapture %}{{ myfigure | strip_newlines }}
> 
> Notice that West Germany started from a more favourable position in 1950 than East Germany. Yet in 1936, before the war began, the two parts of Germany had virtually identical living standards. 
{:.box}

Thanks to Clemens Tolboom and Nathan Arthur for the tip.

Another approach – which is actually easier if you know a little HTML – is to use an HTML blockquote rather than a markdown one. In that case, you’d do this:

<blockquote class="box" markdown=1">

This figure shows the different paths taken by these economies. 

{% include figure image="fig.jpg" %}

Notice that West Germany started from a more favourable position in 1950 than East Germany. Yet in 1936, before the war began, the two parts of Germany had virtually identical living standards. 

</blockquote>

Note that you need markdown="1" to tell kramdown to process the content of your HTML blockquote as markdown.