wok

Tutorial

Wok is simple. To demonstrate that, we are going to make a simple wok site from scratch.

Note: All paths in this document will be relative to the web root, unless otherwise stated.

0. Installation

If you don't already have wok, install it with

sudo pip install wok

markdown and docutils are optional, but will be installed as dependencies. They allow the use of the Markdown and reStructuredText markup languages, so you want at least one of them.

1. File Layout

First, make a directory to hold all your site's code. Wok expects to find at least content and templates directories. It will also use the directories media and hooks, as well as the file config.

--MySite/
  |-- content/
  |-- templates/
  |-- media/
  |-- hooks/
  \-- config

The content directory is where we will store the text of the web site. The templates directory will store the templates that give the site form and function. The media directory is optional, and will contain all of your CSS, JavaScript, images, and various other support files that simply need to be copied to the web site's root. The hooks directory is for adding Python code to the rendering process of wok, which we won't be covering in this tutorial. Finally the config file, which is also optional, may contain some setting that wok will use to change the way it renders the site.

Go ahead and make this directories, and create an empty file named config, because we will be using them all in this tutorial, except for hooks.

2. Content

What is a site without content? Wok defines content as the user generated text that goes on a page. For example, if you were to look at the source of this site (which is highly recommend by the way), you would fine the file that describes this page is a mostly plain text document, with some metadata and Markdown formatted syntax. Content is the unique part of every page, and can't be automatically generated by wok -- you have to write it yourself.

For now our simple site will have 3 pages, home, about, and contact. We will be using the Markdown markup languages, one of the several that wok supports. Wok also support reStructuredText, Textile, plain text, and raw text.

What's the difference between plain and raw text? Raw text will preserve the file exactly as it is when it goes into the generated site. Plain text will add HTML <br> tags at newlines, to preserve the visual structure of the file.

Home

The home page will be the main landing page for our website. As such it's URL should be /index.html. Sounds pretty simple, and it is. Make a file named home.mkd in your content directory, and give it these contents.

home.mkd

title: Home
url: /index.html
---
This is the home page. It is kind of bare right now.

That is all it takes to tell wok what it needs to know. The part above the --- is the metadata for the page. It is technically optional, but every page should have at least the title attribute, or else wok will complain. The url field is optional, and isn't normally specified. It is usually generated based on the url-pattern rules. In this case however, since we want home to always be at /index.html no matter what, we can define that here. Below the --- is simply the content of the page. Since we have given the file the extension of .mkd, wok will use Markdown to render the content.

That is all we need to make a simple page. We will come back to this later and add some features, but for now, we are done.

Contact

Contact is even simpler than home, because it doesn't need a particular URL. We will put it in contact.mkd; here are the contents of that file.

title: Contact
---
You can call me at 555-555-5555, or by email at `noone@nowhere.foo`.

Since we didn't define a URL field, wok will auto generate one, based on the URL rule. Since we haven't specified one of those (it would go in the config file), wok will use the default, which is /{category}/{slug}.{ext}. The slug for this site is contact, and we don't have any category defined, and the extension on the template is (going to be) 'html'. So this page's URL will be /contact.html.

What's a slug? A slug is a string that refers to the page that will good for URLs. Wok will generate them based on the title, by converting it to lower case ASCII, with no punctuation or spaces. You could also define your own by saying slug: something in the metadata.

About

About will be a little more complicated then contact, but not by much.

about.mkd

title: About This Site
slug: about
---
This is a sample wok site, use to demonstrate that yes, it is easy to make
a wok site.

Notice that we defined a slug here. We didn't have to, but if we didn't wok would have generated a slug of about-this-site. www.example.com/about-this-site.html doesn't look very good, so we defined our own slug, shortening it to simply about.

Organization

We put these page's content in files that matched their slugs. But wok doesn't really look at the file name, except to determine that they are Markdown files. Every file in the content directory is treated the same, regardless of file name, or directory structure. That means we could have called the about page page foo/bar/bob.mkd, and it wouldn't have changed anything, in wok's eyes. Feel free to organize the content files into any structure you want: completely flat, with no directories at all, one directory per month of writing, or a directory per category. It doesn't matter to wok.

Templates

If you tried to run wok right now, it would give an error that the template default.* can not be found. That is because if a template wasn't specified in a content file -- which we didn't do -- default.* is used.

Why default.*, instead of default.html? Wok has the ability to generate more than just HTML. If you wanted to render some LaTeX files, you could make your default template default.tex, and wok will generate index.tex instead of index.html (if your url-pattern allowed for this, which the default does). This is also useful for generating things like RSS feeds.

For now we will just make a single template file, and all of our pages will be the same. Templates are made using the Jinja template engine, which is very similar to Django's templates. Here is the content of templates/default.html

<doctype html>
<html>

<head>
    <title>Wok Quickstart</title>
</head>

<body>

    <header>
        <h1>{{ page.title }}<h1>
        <nav>
            <a href="/">Home</a>
            <a href="/about.html">About This Site</a>
            <a href="/contact.html">Contact</a>
        </nav>
    </header>

    <article>
        {{ page.content }}
    </article>

</body>

<html>

header? nav? article? What are all these strange tags you keep using?

This template was made using the HTML5 semantic elements. Adding additional semantics to your code is a Good Thing (tm). For more information, check out Dive into HTML5's page about semantics.

This is an extremely basic HTML5 template, that without some snazzy CSS is going to look awfully boring, but it will serve for our purposes.

Notice the sections in wrapped in {{ }}. Those are Jinja variables. Wok provides several objects for the template engine, such as page, which contains the title of the page, the actual text content, and the author of the page (if you specified one).

Each content file will be generated with a template, and since we didn't specify otherwise, they will all use the default template: this one. The resulting output will be saved in the output directory, with a path built from either the URL specified on the page, or the url-patterns of the site.

Rendering

Now we are ready to turn our pile of code into a tasty web site. If you ran wok by itself, it would create an output directory, copy the contents of our (empty or nonexistent) media directory to it, and then render everything to that directory. This is good for copying serving your website from a real web server, like Apache, or uploading to your web server, but isn't very nice to preview during development, since root-relative links (which you should be using!) won't work when we view these files from a web browser.

To fix this problem, wok provides the --server option, that will make wok run a simple, naive web server from the output directory. This isn't a production ready server by any means, but is nice to see your changes without uploading everything. Run this command from the base of your wok directory.

wok --server

It will say it is running a server, and then wait. Open the link it printed out (http://localhost:8000), and check out the site in your browser.

Additionally, the development server will re-render the site on page load if any files have changed. This way you can edit a content, template, or media file, and then reload your browser to see the changes, instead of having to restart the server.

Next steps

Congratulations, you have made a simple wok site. This should be enough to make a basic site, and combined with some HTML and CSS know-how, can lead to a good looking site that is quick and easy to add new content to, such as a blog.

But wok has more power than this. For more advanced features, check out the rest of the documentation on this site. Additionally, users are encouraged to share and trade tips and cool things that can be done with wok on the Github wiki.