Skip to content
Newer
Older
100644 194 lines (135 sloc) 5.42 KB
5905ec0 @nuex add example config file, readme edits
authored
1 # zodiac
f7affca @nuex working out zod phases
authored
2
3 ZODIAC is a static website generator powered by sh and awk. The core features of zodiac are:
4
9842c01 @nuex mispelled utilization
authored
5 * utilization of existing tools (i.e. awk, sh, find, etc.)
7dcff44 @nuex updated readme
authored
6 * supports using plain html
f7affca @nuex working out zod phases
authored
7 * built-in support for markdown
8 * a simple, easy to use templating system
9 * supports custom helpers written in awk
10 * configuration, meta, helpers, etc. can be added as you need them
5905ec0 @nuex add example config file, readme edits
authored
11 * convert your markup using any external command that accepts a UNIX-style pipe (smu, asciidoc, discount, rst2html, etc)
5bec8d1 @nuex initial
authored
12
13 ## SYNOPSIS
14
f7affca @nuex working out zod phases
authored
15 zod projectdir targetdir
5bec8d1 @nuex initial
authored
16
17 ## INSTALL
18
339ff2a @nuex fixed clone url
authored
19 git clone git://github.com/nuex/zodiac.git
5bec8d1 @nuex initial
authored
20
f7affca @nuex working out zod phases
authored
21 Edit the config.mk file to customize the install paths. `/usr/local` is the default install prefix.
5bec8d1 @nuex initial
authored
22
f7affca @nuex working out zod phases
authored
23 Run the following (as root if necessary):
5bec8d1 @nuex initial
authored
24
f7affca @nuex working out zod phases
authored
25 make install
5bec8d1 @nuex initial
authored
26
f7affca @nuex working out zod phases
authored
27 ## DESCRIPTION
5bec8d1 @nuex initial
authored
28
29 A typical Zodiac project will look something like this:
30
31 site/
32 index.md
33 index.meta
34 main.layout
35 global.meta
36 projects/
37 project-1.md
38 project-1.meta
39 project-2.md
40 project-2.meta
41 cv.md
42 cv.meta
43 stylesheets/
44 style.css
45
f7affca @nuex working out zod phases
authored
46 And it's output could look like this:
47
48 site/
49 index.html
50 projects/
51 project-1.html
52 project-2.html
53 cv.html
54 stylesheets/
55 style.css
56
5bec8d1 @nuex initial
authored
57 ### Meta
58
59 `.meta` files contain a key / value pair per line. A key and its value must be separated by a ": ". A metafile looks like this:
60
61 this: that
62 title: Contact
63 author: Me
64
d476e9a @nuex readme edits
authored
65 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.
5bec8d1 @nuex initial
authored
66
8c0f20f @nuex more on templates
authored
67 The optional `global.meta` file contains data that is available to all of your site's pages, like a site title.
5bec8d1 @nuex initial
authored
68
69 Page metadata will always override global metadata of the same key.
70
8c0f20f @nuex more on templates
authored
71 ### Templates
5bec8d1 @nuex initial
authored
72
d476e9a @nuex readme edits
authored
73 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.
3728cb7 @nuex plain html page template support
authored
74
5905ec0 @nuex add example config file, readme edits
authored
75 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.
3728cb7 @nuex plain html page template support
authored
76
77 The `main.layout` file wraps HTML content around a page template. A `main.layout` file could look something like this:
8c0f20f @nuex more on templates
authored
78
5bec8d1 @nuex initial
authored
79 <!DOCTYPE html>
80 <html lang="en">
81 <head>
82 <meta charset="utf-8" />
83 <link rel="stylesheet" href="/stylesheets/style.css" />
84 <title>{{page_title}}</title>
85 </head>
86 <body>
87 <header>
88 <h1><a href="/">{{site_title}}</a></h1>
89 </header>
90 <article>
91 {{{yield}}}
92 </article>
93 <footer>
94 <p>powered by static files, compiled by <a href="http://nu-ex.com/projects/zodiac">zodiac</a>.</p>
95 </footer>
96 </body>
97 </html>
98
d476e9a @nuex readme edits
authored
99 `{{{yield}}}` is a special tag that renders the page content within the layout. `{{{yield}}}` can only be used in the `main.layout` file.
6ab9d72 @nuex README fix
authored
100
b53401f @nuex partials support and documentation
authored
101 ### Partials
102
103 Partials are reusable snippets that can be included in different areas of your site. Partials must have the `.partial` extension and must be in the root of your project directory. Partials are called using two curly brackets and a greater than sign.
104
105 <body>
106 <h1>Welcome!</h1>
107
108 {{> nav}}
109
110 <p>Thanks for checking out my site!</p>
111 </body>
112
113 The `nav.partial` file could have the following contents:
114
115 <nav>
116 <ul>
117 <li><a href="/">Home</a></li>
118 <li><a href="/blog">Blog</a></li>
119 <li><a href="/about">About</a></li>
120 </ul>
121 </nav>
122
123 This would make the above template expand to:
124
125 <body>
126 <h1>Welcome!</h1>
127
128 <nav>
129 <ul>
130 <li><a href="/">Home</a></li>
131 <li><a href="/blog">Blog</a></li>
132 <li><a href="/about">About</a></li>
133 </ul>
134 </nav>
135
136 <p>Thanks for checking out my site!</p>
137 </body>
138
139
5bec8d1 @nuex initial
authored
140 ### Helpers
141
0b84b88 @dhempy Typo in readme
dhempy authored
142 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 peek at the script included in the examples folder:
5bec8d1 @nuex initial
authored
143
144 { helpers = "yes" }
145
146 function load_helpers() {
147 # your custom data settings
148 data["page_title"] = page_title()
149 }
150
151 # your custom functions
152 function page_title( title) {
ea8f8c7 @nuex make README and example helpers.awk the same
authored
153 if (data["title"]) {
154 title = data["title"] " - " data["site_title"]
f7affca @nuex working out zod phases
authored
155 } else {
ea8f8c7 @nuex make README and example helpers.awk the same
authored
156 title = data["site_title"]
5bec8d1 @nuex initial
authored
157 }
ea8f8c7 @nuex make README and example helpers.awk the same
authored
158 return title
5bec8d1 @nuex initial
authored
159 }
160
f7affca @nuex working out zod phases
authored
161 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.
162
163 ### Config
164
165 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:
166
167 [parse]
5905ec0 @nuex add example config file, readme edits
authored
168 htm,html
f7affca @nuex working out zod phases
authored
169
170 [parse_convert]
7dcff44 @nuex updated readme
authored
171 md smu
172 txt asciidoc -s -
f7affca @nuex working out zod phases
authored
173
174 [ignore]
7dcff44 @nuex updated readme
authored
175 Makefile
f7affca @nuex working out zod phases
authored
176
177 Here we're only parsing (not converting to a different format) files matching `*.htm` and `*.html`.
178
179 Files matching `*.md` are going to be parsed and converted using the `smu` markdown parsing program.
180
181 Files matching `*.txt` are going to be parsed and converted using `asciidoc`.
182
183 Files matching `Makefile` will be ignored and not copied.
184
185 Conversion programs must accept a UNIX-style pipe and send converted data to stdout.
186
23908cb @nuex credits to zsw
authored
187 ## CREDITS
188
f7affca @nuex working out zod phases
authored
189 * zsw: for the introduction to parameter expansion and other shell scripting techniques
23908cb @nuex credits to zsw
authored
190
8c0f20f @nuex more on templates
authored
191 ## LICENSE
5bec8d1 @nuex initial
authored
192
193 MIT
Something went wrong with that request. Please try again.