2011-10-24 15:59:43 +02:00
# zodiac
2011-10-18 07:07:12 +02:00
ZODIAC is a static website generator powered by sh and awk. The core features of zodiac are:
* utliization of existing tools (i.e. awk, sh, find, etc.)
2011-10-24 15:40:17 +02:00
* supports using plain html
2011-10-18 07:07:12 +02:00
* built-in support for markdown
* a simple, easy to use templating system
* supports custom helpers written in awk
* configuration, meta, helpers, etc. can be added as you need them
2011-10-24 15:59:43 +02:00
* convert your markup using any external command that accepts a UNIX-style pipe (smu, asciidoc, discount, rst2html, etc)
2011-09-22 17:28:24 +02:00
## SYNOPSIS
2011-10-18 07:07:12 +02:00
zod projectdir targetdir
2011-09-22 17:28:24 +02:00
## INSTALL
2011-09-22 18:51:59 +02:00
git clone git://github.com/nuex/zodiac.git
2011-09-22 17:28:24 +02:00
2011-10-18 07:07:12 +02:00
Edit the config.mk file to customize the install paths. `/usr/local` is the default install prefix.
2011-09-22 17:28:24 +02:00
2011-10-18 07:07:12 +02:00
Run the following (as root if necessary):
2011-09-22 17:28:24 +02:00
2011-10-18 07:07:12 +02:00
make install
2011-09-22 17:28:24 +02:00
2011-10-18 07:07:12 +02:00
## DESCRIPTION
2011-09-22 17:28:24 +02:00
A typical Zodiac project will look something like this:
site/
index.md
index.meta
main.layout
global.meta
projects/
project-1.md
project-1.meta
project-2.md
project-2.meta
cv.md
cv.meta
stylesheets/
style.css
2011-10-18 07:07:12 +02:00
And it's output could look like this:
site/
index.html
projects/
project-1.html
project-2.html
cv.html
stylesheets/
style.css
2011-09-22 17:28:24 +02:00
### Meta
`.meta` files contain a key / value pair per line. A key and its value must be separated by a ": ". A metafile looks like this:
this: that
title: Contact
author: Me
2011-10-04 23:45:03 +02:00
Each page can have its own meta file. The only requirement is that the meta file is in the same directory as the page, has the same name as the page and has the `.meta` file extension.
2011-09-22 17:28:24 +02:00
2011-09-22 17:42:14 +02:00
The optional `global.meta` file contains data that is available to all of your site's pages, like a site title.
2011-09-22 17:28:24 +02:00
Page metadata will always override global metadata of the same key.
2011-09-22 17:42:14 +02:00
### Templates
2011-09-22 17:28:24 +02:00
2011-10-04 23:45:03 +02:00
Templates come in two forms, page templates and layout templates. Metadata can be bound to templates by using the `{{key}}` notation in your pages and layout files.
2011-10-04 23:34:34 +02:00
2011-10-24 15:59:43 +02:00
Page templates can have any extension that zodiac can convert. Out of the box, page templates can have an `md` , `htm` , or `html` extension. Other extensions and markup types can be supported if they are configured in the `.zod/config` file in the project directory.
2011-10-04 23:34:34 +02:00
The `main.layout` file wraps HTML content around a page template. A `main.layout` file could look something like this:
2011-09-22 17:42:14 +02:00
2011-09-22 17:28:24 +02:00
<!DOCTYPE html>
< html lang = "en" >
< head >
< meta charset = "utf-8" / >
< link rel = "stylesheet" href = "/stylesheets/style.css" / >
< title > {{page_title}}< / title >
< / head >
< body >
< header >
< h1 > < a href = "/" > {{site_title}}< / a > < / h1 >
< / header >
< article >
{{{yield}}}
< / article >
< footer >
< p > powered by static files, compiled by < a href = "http://nu-ex.com/projects/zodiac" > zodiac< / a > .< / p >
< / footer >
< / body >
< / html >
2011-10-04 23:45:03 +02:00
`{{{yield}}}` is a special tag that renders the page content within the layout. `{{{yield}}}` can only be used in the `main.layout` file.
2011-09-22 17:44:49 +02:00
2011-09-22 17:28:24 +02:00
### Helpers
The `helpers.awk` file is an awk script that can make custom data available to your templates. You also have access to the page and global data. Here is a peak at the script included in the examples folder:
{ helpers = "yes" }
function load_helpers() {
# your custom data settings
data["page_title"] = page_title()
}
# your custom functions
function page_title( title) {
2011-10-18 07:07:12 +02:00
if ("title" in data) {
return data["title"] "-" data["site_title"]
} else {
return data["site_title"]
2011-09-22 17:28:24 +02:00
}
}
2011-10-18 07:07:12 +02:00
Just be sure to set the data array in the `load_helpers()` function at the top of the script to make your custom data available to the template.
### Config
For more control over the parsing and conversion process, a `.zod/config` file can be created within your project directory. Here is a sample config:
[parse]
2011-10-24 15:59:43 +02:00
htm,html
2011-10-18 07:07:12 +02:00
[parse_convert]
2011-10-24 15:40:17 +02:00
md smu
txt asciidoc -s -
2011-10-18 07:07:12 +02:00
[ignore]
2011-10-24 15:40:17 +02:00
Makefile
2011-10-18 07:07:12 +02:00
Here we're only parsing (not converting to a different format) files matching `*.htm` and `*.html` .
Files matching `*.md` are going to be parsed and converted using the `smu` markdown parsing program.
Files matching `*.txt` are going to be parsed and converted using `asciidoc` .
Files matching `Makefile` will be ignored and not copied.
Conversion programs must accept a UNIX-style pipe and send converted data to stdout.
2011-10-06 18:35:38 +02:00
## CREDITS
2011-10-18 07:07:12 +02:00
* zsw: for the introduction to parameter expansion and other shell scripting techniques
2011-10-06 18:35:38 +02:00
2011-09-22 17:42:14 +02:00
## LICENSE
2011-09-22 17:28:24 +02:00
MIT
