FAQ
- Why won't Ivy install?
- Where do I put my image files?
- Does Ivy support featured images or image galleries?
- Why do I get an error when I add a url to a Yaml header?
- Can I build a blog using Ivy?
- How do I deploy a site built with Ivy?
- Why is it called Ivy?
Why won't Ivy install?
Ivy requires Python 3. Every installation problem I've heard about has turned out to be a Python 2 issue, even when people are convinced they're installing using Python 3. If you're having problems installing Ivy, try this sequence of steps:
First, make sure you have Python 3 installed:
$ python3 --version
Next, install Ivy using the copy of pip
associated with your Python 3 installation:
$ python3 -m pip install ivy
Check that Ivy has installed properly:
$ python3 -m ivy --version
You should now be able to run the application simply by typing ivy
, but if you're still having problems try python3 -m ivy
as a fallback.
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
Does Ivy support featured images or image galleries?
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?
Annoyingly, Yaml doesn't support unquoted values that begin with an @
symbol so you'll get a scary looking 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: "@root/images/photo.jpg" ---
And yes, I think it's ugly too.
Can I build a blog using Ivy?
Sure, but you'll have to write some code to do it.
Ivy is actually a stripped-down version of an older static website generator that I tinkered with for years called Malt, which was fully blog-capable. One of the lessons I learned along the way is that it's pretty much impossible to build a simple, elegant, general-purpose static-website-plus-blog engine — it just ends up being a WordPress-style rat's nest of options and switches.
It's actually quite easy to build a blog on top of Ivy by adding a simple plugin to assemble indexes, etc. — at least, it's easy to do it for one specific site. I've certainly thought about building a general-purpose blog plugin, but it inevitably turns into its own mini rat's nest of options and switches all over again.
I don't have any personal use for a blog so I probably never will get around to working on the problem again, but if anyone else wants to try they're welcome to take a look at Malt for inspiration.
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.
-
The simplest option to get started is to use a service like Github Pages which will host static websites for free.
-
The next step up is 'shared web hosting' — it's cheap, flexible, and lots of online companies offer it. I've used NearlyFreeSpeech myself and been happy with their service.
-
If you need more control over your hosting environment you can run your own webserver like Apache or Nginx on a virtual server machine (a VPS or Virtual Private Server) you rent from a company like Digital Ocean.
Why is it called Ivy?
Industrial Vellum, IV. Also, the branching tree structure of the nodes reminded me of ivy.