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:
  --help              Print the application's help text and exit.
  --version           Print the application's version number and exit.

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

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

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/
    site.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

The site configuration file can be deleted if the site does not require custom settings; unused directories can likewise be deleted. (Note however that Ivy requires the presence of either a site.py file or both src and out directories 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 a 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: 1901-07-21
---

Content begins here.

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

Note that the files

/src/sampledir/samplenode.md
/src/sampledir/samplenode/index.md

and the directory

/src/sampledir/samplenode

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

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.

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 Syntex 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//)
* [Posts](@root/posts/index//)
    * [Cats](@root/posts/cats/index//)
    * [Dogs](@root/posts/dogs/index//)

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.

Extension Options

Markdown

Ivy uses the Markdown package to render record files with a .md extension. You can add a dictionary of keyword arguments for the 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 record files. You can add a dictionary of keyword arguments for the shortcode parser to your site configuration file via a shortcodes attribute.

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.