Tutorial

mythmon edited this page Sep 8, 2011 · 3 revisions
Clone this wiki locally

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 either the web root, unless otherwise stated.

0. Installation

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

sudo pip install wok
sudo pip install Markdown
sudo pip install docutils

markdown and docutils are optional, but they allow the use of the Markdown and reStructredText markup languages, so you want at least one of them.

For more information, see installation.

1. File Layout

First, make a directory to hold all your site's code. Wok expects to find 2 or 3 directories here, and possible one file in your site's source directory.

--MySite/
  |-- content/
  |-- templates/
  |-- media/
  \-- 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. 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.

2. Content

What is a site without content? Wok defined content as the text that goes on the page. For example, if you edit this wiki page, you will say plain text, structured so that the reStructuredText markup language will produce the pretty output you are reading. 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 two that wok supports. Wok also support reStructuredText, 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 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 optional, but every page should have at least the title attribute, or else wok will throw some warning messages. The url field is totally optional, and is normally 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}.html. The slug for this site is contact, and we don't have any category defined. 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.

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

About file names. 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.html can not be found. That is because if a template wasn't specified in a content file -- which we didn't do -- default.html is use.

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>

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

This template was made using the HTML 5 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).

This template will be generated for each content file, and each file will be saved based on the URL specified, or the URL pattern.

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 could for copying serving your website from a real webserver, like apache, or uploading to your web server, but isn't very nice to preview on your computer, 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, work 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.

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 tips and tricks section of the wiki.