README.mkd

Wok

Wok is a static website generator. It turns a pile of templates, content, and resources (like CSS and images) into a neat stack of plain HTML.

The idea is that you don't need a big server-side engine like PHP to generate every page every visit: you can generate them all ahead of time, and only regenerate things when something has changed. A good way this could be done would be with a post-commit hook on a git repository containing your content or layout.

I made wok because projects like Jekyll, Hyde, and Static were intriguing, but in the end didn't quite match what I wanted to do with my website. So I am writing my own. Funnily, the mythical website that inspired wok still hasn't been written.

Sample Sites

A bare bones site is included in the wok git repo, in the test directory. It is really just a playground for devs to test new features, and not a good learning tool.

The documentation site available in the doc directory should be a fairly complete example of a small site that is good to learn from.

For some real world examples check out these sites.

• Oregon State University Linux Users Group (source)
• Bravo Server (source) - A custom Minecraft server written in Python.
• robmd.net (source) - Personal website of Rob McGuire-Dale.
• uberj.com (source) - Personal website of Jacques Uber
• ngokevin.com (source) - Personal website of Kevin Ngo
• corbinsimpson.com (source) - Personal website of Corbin Simpson
• philipbjorge.com (source) - Personal website of Philip Bjorge
• dmbaughman.com - Personal website of David Baughman
• Your site here! If you are using wok to generate sites, and don't mind serving as an example, let me know and I will add a link to your site here.

For some more documentation, checkout the doc site. To learn and share with other users, you can check out the wiki.

Installation

The recommended way to install wok is from the Python Package Index with this command.

sudo pip install wok

Alternatively, if you want to hack on wok or just need the latest code, you can run from git head, and if you want to you can install to your system directories with this command. Note that you will need to install dependencies by hand in this case.

sudo python2 setup.py install

###Dependencies All dependencies are available from pip. Although optional, you really should install either markdown or docutils, and if you install from pip, they will be installed for you. Pygments is used for syntax highlighting, and will also be installed from pip.

####Required

• pyyaml
• jinja2

####Optional

• Markdown - for rendering markdown documents.
• docutils - for rendering reStructuredText documents.
• Pygments - for syntax highlighting.

Usage

You might be interested in the tutorial

To use wok, go to the directory where your site files are located, and run the command wok. No output will be given unless something goes wrong. If it returns without error, you should have a shiny new output folder containing some HTML, and your media that represents your shiny new site.

To aid in testing links on the site, wok includes a development server. You can run it with the command wok --server, which will generate the site as normal, and then run a webserver on port 8080. The comments on that particular file say:

Do NOT attempt to use this as anything resembling a production server. It is meant to be used as a development test server only.

This test server is slow, and likely insecure, but for local testing of the site during development, it is really convenient.

Wok pulls the pieces of your site from three places. For each of these places, you can modify the path wok looks for them in the configuration file.

Content

Pulled from a directory named content by default. Content is written in lightweight markup or in plain text, with an optional YAML header section. The directory structure of the file mean nothing to wok. It builds the structure of the site based on the titles and the category meta data.

Since wok uses lightweight mark up languages like Markdown and reStructuredText, it is easy to do nice formatting in the pages without using a GUI editor or a cumbersome language like HTML. Built in syntax highlighting and media copying make things even easier.

More info

Templates

Pulled from templates by default. Wok uses Jinja2 templates, with various variables exposed to build pages. This is a very flexible templating environment with control flow, filters, and other ways to slice and dice the data that wok gives you.

More info

Configuration

Settings can be changed in the file config in the current directory.

Possible configuration options (and their defaults) are

• output_dir ('output') - Where the outputted files are put.

• content_dir ('content') - Where to find the content.

• templates_dir ('templates') - Where the templates are.

• media_dir ('media') - Where the media files are copied from.

• site_title ('Some Random wok Site') - Available to templates as site.title.

• author (No default) - Fills site.author, and provides a default to page.author.

• url_pattern (/{category}/{slug}.html) - The pattern used to name and place the output files. The default produces URLs like /category/subcategory/foo.html. To get "wordpress style" urls, you could use /{category}/{slug}/index.html.

  Available variables:

  • {category} - The category of the site, slash seperated.
  • {slug} - The slug of the page.
  • {page} - The current page.
  • {ext} - The extension that the page should used.
  • {date}, {datetime}, and {time} - The date/time from the metadata of the page

• url_use_index (Yes) - If true, keep index.* in urls.

More info: config, urls.