Ivy

A static website generator for people who enjoy the simpler things in life.

Version 6.5.0

FAQ

Is Ivy fast?

No. Ivy is designed to be easy to use, with lots of flexibility under the hood if you're prepared to write a little extension code. Execution speed isn't a significant design goal as it's simply irrelevant for the kind of small personal or project websites Ivy is intended to be used for.

As a rough benchmark, a clean (no-cache) build of the Ivy demo site which contains 7 output pages takes 0.15 seconds on my laptop. A clean build of the Holly demo site which contains 951 output pages takes 1.7 seconds. This means that on my particular hardware I can expect a throughput of roughly 500 pages per second.

If you need to build a website with tens or hundreds of thousands of pages, Ivy probably isn't the right tool for you. Hugo is a popular static site generator with a focus on execution speed that may be a better match for large sites.

Can I build a blog using Ivy?

Holly is a blog-engine plugin for Ivy. It adds support for WordPress-style post and tag indexes.

Where do I put my image files?

Image files, along with any other static assets, should be stored in the site's resources directory, res. The content of this directory is copied to the output directory when the site is built.

As an example, assume we have a file named photo.jpg stored in a directory named images within the res directory, i.e. 

site/
|-- res/
    |-- images/
        |-- photo.jpg

This file will be copied to the output directory and can be accessed in templates and node files via the URL: 

@root/images/photo.jpg

Ivy has no special support for WordPress-style featured images but we can implement similar functionality simply by adding the image name as an attribute to the page header, e.g. 

---
title: Page Title
image: photo.jpg
---

We can then check for the presence of a featured image in the appropriate template file: 

{% if node.image %}
    <img src="@root/images/{{node.image}}">
{% endif %}

YAML supports lists so we can implement galleries in a similar manner by adding a list of image names to the header and then iterating over the list in the template file: 

{% for image in node.gallery %}
    <img src="@root/images/{{image}}">
{% endfor %}

Why do I get an error when I add a URL to a YAML header?

YAML doesn't support unquoted values that begin with an @ symbol so you'll get an error message if you add a bare @root/ URL to a YAML header, e.g. 

---
image: @root/images/photo.jpg
---

Quoting the URL solves the problem: 

---
image: "images/photo.jpg"
---

How do I deploy a site built with Ivy?

One of the nicest things about a static website is that it's completely independent of the tool used to build it. You can host your website anywhere you like — in the simplest case you can 'deploy' it simply by double-clicking on the .html files to view them locally in your browser.

To make your website available on the public internet you have lots of options. Here's some of the most common, in order of increasing difficulty and expense.

Why is it called Ivy?

I liked the name Industrial Vellum, IV. Also, the branching tree structure of the nodes reminded me of ivy.

Can I disable a node?

You can add a disable flag to a node's metadata header: 

---
disable: true
---

This will stop Ivy from producing an output HTML page for the node.

Note that this only affects the node itself, not its children.

Can I use a different Markdown library?

Sure. Ivy defaults to using the Markdown library to render .md files but you can register a custom handler to use any library you like.

Can I use LaTeX markup?

Here's a simple demo of an Ivy site using the KaTeX JavaScript library to render LaTeX markup.