Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 186 lines (144 sloc) 7.325 kB
f3c0075 @mythmon Tweak the readme
authored
1 Wok
8f1c581 @mythmon Add a readme.
authored
2 ===
f7e2891 @mythmon Add Travis badge.
authored
3
7995969 @mythmon Fix Travis badge.
authored
4 [![Build Status](https://travis-ci.org/mythmon/wok.svg?branch=master)](https://travis-ci.org/mythmon/wok)
f7e2891 @mythmon Add Travis badge.
authored
5
f3c0075 @mythmon Tweak the readme
authored
6 Wok is a static website generator. It turns a pile of templates,
7 content, and resources (like CSS and images) into a neat stack of plain
3370fcc @edunham mention license name in readme
edunham authored
8 HTML. Wok is distributed under the MIT license (see the LICENSE file for
9 more details).
8f1c581 @mythmon Add a readme.
authored
10
f3c0075 @mythmon Tweak the readme
authored
11 The idea is that you don't need a big server-side engine like PHP to
12 generate every page every visit: you can generate them all ahead of
13 time, and only regenerate things when something has changed. A good way
14 this could be done would be with a post-commit hook on a git repository
15 containing your content or layout.
e550c4c @mythmon Update README.mkd
authored
16
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
17 I made wok because projects like [Jekyll][jekyll], [Hyde][hyde], and
f3c0075 @mythmon Tweak the readme
authored
18 [Static][static] were intriguing, but in the end didn't quite match what
19 I wanted to do with my website. So I am writing my own. Funnily, the
20 mythical website that inspired wok still hasn't been written.
e550c4c @mythmon Update README.mkd
authored
21
22 [jekyll]: https://github.com/mojombo/jekyll
88286c6 @ngokevin added kevin and corbin's site to readme
ngokevin authored
23 [hyde]: https://github.com/lakshmivyas/hyde
24 [static]: http://static.newqdev.com/
8f1c581 @mythmon Add a readme.
authored
25
baebdf0 @mythmon Talk about sample sites in the readme.
authored
26 Sample Sites
27 ------------
b03ea6d @mythmon Update readme.
authored
28 A bare bones site is included in the wok git repo, in the `test` directory.
f3c0075 @mythmon Tweak the readme
authored
29 It is really just a playground for devs to test new features, and not a good
30 learning tool.
baebdf0 @mythmon Talk about sample sites in the readme.
authored
31
5bcaf3a @mythmon Tweaks to README and the Contributors page.
authored
32 The documentation site available in the `doc` directory should be a fairly
33 complete example of a small site that is good to learn from.
34
baebdf0 @mythmon Talk about sample sites in the readme.
authored
35 For some real world examples check out these sites.
36
57aedf9 @mythmon Add LUG's site to the README.
authored
37 - [Oregon State University Linux Users Group](http://lug.oregonstate.edu)
38 ([source](https://github.com/OSULUG/OSULUG-Website))
07dfcb4 @mythmon Update the readme.
authored
39 - [Bravo Server](http://bravoserver.org)
40 ([source](https://github.com/MostAwesomeDude/bravo/tree/master/website)) -
41 A custom Minecraft server written in Python.
57aedf9 @mythmon Add LUG's site to the README.
authored
42 - [robmd.net](http://robmd.net)
43 ([source](https://github.com/robatron/robmd.net)) - Personal website of
44 Rob McGuire-Dale.
9dce702 @mythmon Add another example site: uberj.com. Thanks Jacques!
authored
45 - [uberj.com](http://www.uberj.com)
46 ([source](https://github.com/uberj/wbsite)) - Personal website of Jacques
47 Uber
88286c6 @ngokevin added kevin and corbin's site to readme
ngokevin authored
48 - [ngokevin.com](http://ngokevin.com)
49 ([source](https://github.com/ngokevin/ngokevin)) - Personal website of
50 Kevin Ngo
51 - [corbinsimpson.com](http://corbinsimpson.com)
52 ([source](https://github.com/mostawesomedude/website)) - Personal website
53 of Corbin Simpson
bb00c20 @philipbjorge Added new demo site to README
philipbjorge authored
54 - [philipbjorge.com](http://www.philipbjorge.com)
173c4b1 @mythmon Add philip's site to the website too.
authored
55 ([source](https://github.com/philipbjorge/philipbjorge.com)) - Personal
bb00c20 @philipbjorge Added new demo site to README
philipbjorge authored
56 website of Philip Bjorge
5bcaf3a @mythmon Tweaks to README and the Contributors page.
authored
57 - [dmbaughman.com](http://dmbaughman.com) - Personal website of
58 David Baughman
07dfcb4 @mythmon Update the readme.
authored
59 - Your site here! If you are using wok to generate sites, and don't mind
60 serving as an example, let me know and I will add a link to your site
61 here.
baebdf0 @mythmon Talk about sample sites in the readme.
authored
62
b03ea6d @mythmon Update readme.
authored
63 For some more documentation, checkout [the doc site][docs]. To learn and share
64 with other users, you can check out [the wiki][wiki].
f3c0075 @mythmon Tweak the readme
authored
65
b03ea6d @mythmon Update readme.
authored
66 [docs]: http://wok.mythmon.com
f3c0075 @mythmon Tweak the readme
authored
67 [wiki]: https://github.com/mythmon/wok/wiki
68
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
69 Installation
70 ------------
5bcaf3a @mythmon Tweaks to README and the Contributors page.
authored
71 The recommended way to install wok is from the [Python Package Index][pypi]
72 with this command.
5bf35de @mythmon Update readme.
authored
73
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
74 sudo pip install wok
75
f3c0075 @mythmon Tweak the readme
authored
76 Alternatively, if you want to hack on wok or just need the latest code,
77 you can run from git head, and if you want to you can install to your
78 system directories with this command. Note that you will need to install
79 dependencies by hand in this case.
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
80
81 sudo python2 setup.py install
8f1c581 @mythmon Add a readme.
authored
82
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
83 [pypi]: http://pypi.python.org/pypi
84
07dfcb4 @mythmon Update the readme.
authored
85 ###Dependencies
86 All dependencies are available from pip. Although optional, you really should
b03ea6d @mythmon Update readme.
authored
87 install either markdown or docutils, and if you install from pip, they will be
88 installed for you. Pygments is used for syntax highlighting, and will also be
89 installed from pip.
07dfcb4 @mythmon Update the readme.
authored
90
91 ####Required
92
93 - `pyyaml`
94 - `jinja2`
95
96 ####Optional
97
b03ea6d @mythmon Update readme.
authored
98 - `Markdown` - for rendering markdown documents.
07dfcb4 @mythmon Update the readme.
authored
99 - `docutils` - for rendering reStructuredText documents.
b03ea6d @mythmon Update readme.
authored
100 - `Pygments` - for syntax highlighting.
07dfcb4 @mythmon Update the readme.
authored
101
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
102 Usage
cf7269e @mythmon Add media directory support.
authored
103 -----
5bcaf3a @mythmon Tweaks to README and the Contributors page.
authored
104 > You might be interested in [the tutorial](http://wok.mythmon.com/tutorial/)
105
b03ea6d @mythmon Update readme.
authored
106 To use wok, go to the directory where your site files are located, and run the
107 command `wok`. No output will be given unless something goes wrong. If it
108 returns without error, you should have a shiny new output folder containing
109 some HTML, and your media that represents your shiny new site.
89ace5f @mythmon Version 0.4
authored
110
f3c0075 @mythmon Tweak the readme
authored
111 To aid in testing links on the site, wok includes a development server.
112 You can run it with the command `wok --server`, which will generate the
113 site as normal, and then run a webserver on port 8080. The comments on
114 that particular file say:
89ace5f @mythmon Version 0.4
authored
115
f3c0075 @mythmon Tweak the readme
authored
116 > Do *NOT* attempt to use this as anything resembling a production
117 > server. It is meant to be used as a development test server only.
89ace5f @mythmon Version 0.4
authored
118
f3c0075 @mythmon Tweak the readme
authored
119 This test server is slow, and likely insecure, but for local testing of
120 the site during development, it is really convenient.
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
121
f3c0075 @mythmon Tweak the readme
authored
122 Wok pulls the pieces of your site from three places. For each of these
123 places, you can modify the path wok looks for them in the configuration
124 file.
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
125
126 ### Content ###
f3c0075 @mythmon Tweak the readme
authored
127 Pulled from a directory named `content` by default. Content is written
128 in lightweight markup or in plain text, with an optional YAML header
129 section. The directory structure of the file mean nothing to wok. It
130 builds the structure of the site based on the titles and the category
131 meta data.
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
132
22a4178 @mythmon Update readme.
authored
133 Since wok uses lightweight mark up languages like [Markdown][mkd] and
f3c0075 @mythmon Tweak the readme
authored
134 [reStructuredText][rst], it is easy to do nice formatting in the pages
135 without using a GUI editor or a cumbersome language like HTML. Built in
136 syntax highlighting and media copying make things even easier.
22a4178 @mythmon Update readme.
authored
137
138 [mkd]: http://daringfireball.net/projects/markdown/
139 [rst]: http://docutils.sourceforge.net/rst.html
140
b03ea6d @mythmon Update readme.
authored
141 [More info](http://wok.mythmon.com/docs/content/)
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
142
143 ### Templates ###
f3c0075 @mythmon Tweak the readme
authored
144 Pulled from `templates` by default. Wok uses [Jinja2][jinja] templates,
145 with various variables exposed to build pages. This is a very flexible
146 templating environment with control flow, filters, and other ways to
147 slice and dice the data that wok gives you.
a6908b8 @mythmon Change the README. The information that was there is now on the githu…
authored
148
149 [jinja]: http://jinja.pocoo.org/
cf7269e @mythmon Add media directory support.
authored
150
b03ea6d @mythmon Update readme.
authored
151 [More info](http://wok.mythmon.com/docs/templates/)
cf7269e @mythmon Add media directory support.
authored
152
4749ec9 @mythmon Add a config file, and pull options from it. Document it.
authored
153 Configuration
154 -------------
155 Settings can be changed in the file `config` in the current directory.
a2dcfcb @mythmon Readme.
authored
156
4749ec9 @mythmon Add a config file, and pull options from it. Document it.
authored
157 Possible configuration options (and their defaults) are
96ef6b2 @mythmon Apparently markdown is picky about lists.
authored
158
f372606 @mythmon Add template variable: `page.slugs`. Dictionary {slug: page}.
authored
159 - `output_dir` ('output') - Where the outputted files are put.
160 - `content_dir` ('content') - Where to find the content.
161 - `templates_dir` ('templates') - Where the templates are.
162 - `media_dir` ('media') - Where the media files are copied from.
163 - `site_title` ('Some Random wok Site') - Available to templates as
164 `site.title`.
165 - `author` (No default) - Fills `site.author`, and provides a default to
166 `page.author`.
167 - `url_pattern` (`/{category}/{slug}.html`) - The pattern used to name and
168 place the output files. The default produces URLs like
169 `/category/subcategory/foo.html`. To get "wordpress style" urls, you could
170 use `/{category}/{slug}/index.html`.
b87bcd1 @mythmon Talk about url_patterns in the README.
authored
171
172 Available variables:
173
238c805 @mythmon Give another example about url_pattern in the readme.
authored
174 - `{category}` - The category of the site, slash seperated.
b87bcd1 @mythmon Talk about url_patterns in the README.
authored
175 - `{slug}` - The slug of the page.
b03ea6d @mythmon Update readme.
authored
176 - `{page}` - The current page.
177 - `{ext}` - The extension that the page should used.
178 - `{date}`, `{datetime}`, and `{time}` - The date/time from the metadata
179 of the page
180
181 - `url_use_index` (Yes) - If true, keep `index.*` in urls.
182
183 More info:
184 [config](http://wok.mythmon.com/docs/config/),
185 [urls](http://wok.mythmon.com/docs/urls/).
Something went wrong with that request. Please try again.