Ivy

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

Version 6.5.0

Building Websites

Command Line Interface

To initialize a new site, create a site directory, cd into it, and run the init command: 

$ ivy init

To build an existing site, run the build command from the site directory or any of its subdirectories: 

$ ivy build

Use the ivy --help flag to view the full command-line help text.

Site Structure

Ivy assumes that a site uses the following default directory structure: 

site/
|-- ext/         # extensions directory for plugins
|-- inc/         # includes directory for menus, etc.
|-- lib/         # library directory for themes
|-- out/         # output directory for html files
|-- res/         # resources directory for static assets
|-- src/         # source directory for text files
|-- site.py      # site configuration file

Ivy uses the presence of a site.py file (alternatively, a config.py file) to identify a site's home directory.

Static assets such as image files should be placed in the site's resources directory, res. The content of this directory is copied to the output directory when the site is built.

Nodes

A node is a text file or directory stored in a site's src directory. Ivy parses the src directory into a tree of nodes which it then renders into a website, generating a single HTML page in the out directory for each node in the tree.

A node file can begin with a YAML header specifying metadata for the node: 

---
title: My Important Document
author: John Doe
date: 1999-12-31
---

Content begins here.

Node content can be written in Markdown, Syntext, or plain HTML. Files with a .md extension have their content passed through a Markdown renderer; files with a .stx extension have their content passed through a Syntext renderer; files with an unregistered extension (like .txt or .html) have their content preserved as-is.

Note that the file 

src/foo/bar.md

and the directory 

src/foo/bar/

correspond to a single node in the parse tree. Node files provide content and metadata for a node; node directories store child nodes.

(Files named index.* are special — they correspond to the same node as their parent directory.)

Metadata

Ivy has builtin support for node metadata in YAML format. Note that metadata keys are converted to lowercase and spaces and hyphens are replaced by underscores so the YAML attribute: 

---
Meta Title: Important Document
---

would be accessible in template files as node.meta_title.

All nodes have the following default attributes:

node.text

The node's text content as read from the source file.

node.html

The node's text content after it has been rendered into HTML. (This will only differ from node.text if a renderer has been registered for the node file's extension. By default a Markdown renderer is registered for .md files and a Syntext renderer for .stx files.)

node.url

The node's @root/ URL.

Ivy generates page-relative URLs and files with a .html extension by default.

To link to files within your site from nodes or templates use site-relative URLs prefixed by @root/, e.g. 

@root/images/photo.jpg

Ivy will automatically rewrite these URLs in the appropriate format.

Use two trailing slashes when linking to pages generated by Ivy itself — this tells Ivy to rewrite the ending to suit your extension settings. 

@root/posts/my-post//

Linking to the homepage is a special case — a simple @root/ will always suffice.

Slugs

A node's URL is determined by its slug and by the slugs of its ancestor nodes. By default a node's slug is generated by slugifying its filename — the extension is stripped, text is converted to lowercase ASCII, spaces are converted to hyphens etc., so a node file named Foo Bar.md would have the slug foo-bar.

This default slug can be overridden by setting a custom slug in the header: 

---
slug: my-custom-slug
---

Slugs can be customized sitewide by registering a filter callback on the Filter.SLUGIFY filter hook. (You can find this hook in the ivy/utils.py file.)

Classes

Ivy automatically generates a list of useful CSS classes for each page's <body> element based on the page's URL slugs. For example the page with the URL: 

@root/foo/bar/baz//

will have the classes: 

node-foo-bar-baz
node-foo-bar
node-foo
node

You can add your own custom classes for a particular node by adding a comma-separated classes list to the node's header, e.g. 

---
classes: foo, bar, baz
---

Note that the homepage node automatically gets the class homepage.

Includes

The includes directory, inc, is for includeable files, typically snippets of content that can be reused on multiple pages throughout the site like menus or footer links. Source files placed in this folder will be parsed as Markdown or Syntext depending on their extension and the resulting HTML made available for inclusion in templates via an inc.<filename> variable.

For example, a simple menu can be constructed in Markdown using nested lists: 

* [Home](@root/)
* [About](@root/about//)
* [Pets](@root/pets//)
    * [Cats](@root/pets/cats//)
    * [Dogs](@root/pets/dogs//)

If this menu was placed in a file named menu.md then the rendered HTML would be available in templates via an inc.menu variable. (Note that filenames are converted to lower case and spaces and hyphens are converted to underscores.)

You can add files with any extension to the inc directory including .html, .js, and .css. If no renderer has been registered for the extension the file's content will be preserved as-is.

Meta Titles and Descriptions

The default theme, graphite, has builtin support for HTML meta titles and descriptions. (A page's meta title is the title shown in the browser's tab bar and on search engine result pages. A page's meta description is often used by search engines as the 'snippet' of content displayed on result pages.)

Just add meta_title and/or meta_description attributes to the page's header: 

---
title: Title On Page
meta_title: Search Engine Title
meta_description: A description of the page's content.
---

This isn't really a feature of Ivy itself — the default theme simply checks for these attributes in its template files and you can add similar support to your own custom themes.