Ivy

Ivy is a static website generator built in Python. It transforms a directory of text files into a self-contained website.

Guide


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:

Usage: ivy [FLAGS] [COMMAND]

  Ivy is a static website generator. It transforms a
  directory of text files into a self-contained website.

Flags:
  -h, --help          Print the application's help text.
  -v, --version       Print the application's version.

Commands:
  build               Build the site.
  clear               Clear the output directory.
  init                Initialize a new site directory.
  serve               Run a server on the output directory.
  tree                Print the site's node tree.
  watch               Monitor the site directory and
                      automatically rebuild on changes.

Command Help:
  help <command>      Print the command's help text.

Run ivy help <command> to view the help text for a specific command.

Site Structure

Initializing a new site creates the following directory structure:

site/
    config.py    # site configuration file
    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

Unused directories can be safely deleted. Ivy uses the presence of either a config.py file or a hidden .ivy file to identify a site's home directory.

Static assets such as image files should be placed in the 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: 1979-02-28
---

Content begins here.

Node content can be written in Markdown or Monk. Files with a .md extension are rendered as Markdown, files with a .mk extension are rendered as Monk. (Ivy can be extended via plugins to support other formats and extensions.)

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-cased and correspond to the same node as their parent directory.

Node Meta

Ivy has builtin support for node metadata in YAML format; support for additional formats can be added via extensions. Note that a node file's metadata keys are converted to lowercase and spaces are replaced by underscores so the YAML attribute

---
Date of Birth: 1901-02-28
---

would be accessible in template files as node.date_of_birth.

All nodes have the following default attributes:

html

The node's text content rendered into html.

text

The node's raw text content.

url

The node's url.

Ivy generates page-relative urls and files with a .html extension by default, but you can customize this behaviour to suit your needs.

First, you can specify a root url in your site configuration file. Specify an explicit domain for absolute urls or a single forward slash "/" for site-relative urls.

root = "http://example.com/"

Second, you can specify a file extension in your site configuration file. You can choose an arbitrary file extension or specify a single forward slash "/" to generate directory-style urls.

extension = ".html"

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

@root/scripts/jquery.js

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.

Only urls enclosed in quotes or angle brackets get rewritten; quotes are preserved, angle brackets evaporate.

Includes

The includes directory, inc, is intended for snippets of content that can be reused on multiple pages throughout the site, e.g. menus or footer links. Source files placed in this folder will be parsed as Markdown or Monk depending on their extension and the resulting HTML made available for inclusion in template files via the inc.<name> attribute.

For example, a 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 contained in a file named menu.md then the rendered HTML would be available in templates via the inc.menu attribute. (Note that filenames are converted to lower case and spaces and hyphens are converted to underscores.)

Files with a .html/.js/.css/.txt extension will have their contents preserved as-is.

Note that included files are available for use in templates (e.g. Jinja or Ibis files), not in node content (e.g. Markdown or Monk files). To include elements in node content consider making use of shortcodes.

Shortcodes

Ivy has builtin support for WordPress-style shortcodes with space-separated positional and keyword arguments:

[% tag arg1 key=arg2 %] ... [% endtag %]

Shortcodes are powerful; you can use them to inject content into a node's text or to customize the formatting of a block of content.

Shortcodes are registered by plugins. When you create a new site using the init command, Ivy adds a sample plugin to your site's ext directory that registers an [% include %] shortcode. You can use this shortcode to inject the content of files from your site's inc directory directly into a node's text, e.g.

[% include foobar.md %]

Just supply the shortcode with the name of the file to include. You can learn more about registering custom shortcodes of your own here.

Extension Options

Markdown

Ivy uses the Markdown package to render node files with a .md extension. You can add a dictionary of keyword arguments for the Markdown renderer to your site configuration file via a markdown attribute, e.g.

markdown = { 'extensions': ['markdown.extensions.extra'] }

See the package's documentation for details of its available options.

Jinja

Ivy uses the Jinja2 package to render template files with a .jinja extension. You can add a dictionary of keyword arguments for the Jinja environment to your site configuration file via a jinja attribute.

Shortcodes

Ivy uses the Shortcodes package to process shortcodes in node files. You can add a dictionary of keyword arguments for the shortcode parser to your site configuration file via a shortcodes attribute.

Automenu

The bundled Automenu extension automatically generates a menu containing links to every node in the site. The menu can be accessed in templates via an automenu attribute. This menu can be customized in two ways:

Dependencies

Installing Ivy via pip automatically installs the following required dependencies:

Installing via pip also automatically installs the following optional dependencies:

Ivy will run without any of these optional dependencies installed but the associated functionality will not be available.