- Command Line Interface
- Site Structure
- Meta Titles and Descriptions
Command Line Interface
To initialize a new site, create a site directory,
cd into it, and run the
$ ivy init
To build an existing site, run the
build command from the site directory or any of its subdirectories:
$ ivy build
ivy --help flag to view the full command-line help text.
Ivy assumes that a site uses the following default 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 node files
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.
Default directories can be overridden by adding a
*_dir attribute to the
config.py file, e.g.
out_dir = "custom_name"
The value will be treated as a directory path relative to the site directory.
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
.html) have their content preserved as-is.
Note that the file
and the directory
correspond to a single node in the parse tree. Node files provide content and metadata for a node; node directories store child nodes.
index.* are special — they correspond to the same node as their parent directory.)
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
All nodes have the following default attributes:
The node's text content as read from the source file.
The node's text content after it has been rendered into HTML. (This will only differ from
node.textif a renderer has been registered for the node file's extension. By default a Markdown renderer is registered for
.mdfiles and a Syntext renderer for
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
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.
Linking to the homepage is a special case — a simple
@root/ will always suffice.
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
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
slugify filter hook. (You can find this hook in the
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:
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
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
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
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.)
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.