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