website Recipes

“How Do I…” for website powered sites

What is website?

Settings and Defaults

How can I set a default author for all posts?

In your add a dictionary DEFAULTS with the key AUTHOR:

    "AUTHOR": "John Doe"
How can I add new pseudo-protocols?

Pseudo-protocols allow you to abbreviate hyperlinks in your article posts. New ones are set in the file with the variable PROTOCOLS:

    "foo": ""

You can then use it in your posts like this:


which will turn out as

How do I enable comments for articles?

Since all articles are compiled to static HTML, website uses Disqus to host commenting functionality. Add your Disqus user name to, and the rest comes automatically:

DISQUS_NAME = "foobar"


How do I add meta-data or headers to articles?

The syntax of an article file is quite simple. First there come the headers in the form of key-value pairs, then an empty line followed by the post body (HTML). Header lines may be split by beginning following lines with a single white space. A complete post file looks like this:

Title: My Post
Author: John Doe
Date: 2011-07-01T12:00:00Z
Subject: website, writing, recipe

<p>This is a blog post.</p>
<p>There are lots of paragraphs</p>
<h2>Or Headings</h2>
How can I create categories for articles?

This is simple. Use folders under _article to organize your posts. For example, putting a file under _articles/my_cat/my_post.html gives the post the category “my_cat”. Nesting folders is of course supported.

How can I create tags for articles?

Use the header Subject and a comma-separated list to define tags for a post:

Title: My Post
Subject: Tag 1, Tag 2

<p>Post content goes here…</p>
How do I create a series of articles?

There are two headers, that are used for this. Requires points to another article, that preceeds the current, and isRequiredBy references the next, following part. If you give the article an ID, you can reference it easily:

Title: Part 2 of 3
ID: Part_2
Requires: Part_1
IsRequiredBy: Part_3

<p>This is part 2 of 3…</p>
How can I modify an article’s short description on index pages?

Usually index pages show the first 200 characters of the article. You can change this in two ways: If you add a header Abstract, this abstract is displayed per default before the article text, and is also used as description. If you specify the header Description, this is used as index page description, but doesn’t occur on the article’s page.

Title: My Post
Description: This appears on index pages
Abstract: This is displayed in front of the article and
 on index pages, if Description is not set

<p>This appears, if neither is set…</p>
Can specific articles have no comment form?

The Status header is used for this. Add the value no-discussion and the Disqus code will not be embedded:

Title: There’s nothing to discuss
Status: no-discussion
Can I prevent an article to appear in the index pages?

Add the value noref to the Status header:

Title: This should not appear on index pages
Status: noref
An article should not be indexed by search engines. How?

You can add a robots.txt to your project, that will automatically copied to the project:

User-agent: *
Disallow: /my-secret-post.html

Alternatively use the Robots header to set the corresponding meta element in the finished HTML page:

Title: Don’t spider me
Robots: no-follow, no-index
Can I use custom CSS and JS in my posts?

You can always embed Javascript in your post and it will be output straight through. For CSS it is a bit more complicated, because it should live in the HTML head. You can use the header Stylesheet to embed them. The strings #a# and #s# will be replaced by the absolute path to the article and to the static files, respectively.

Stylesheet: #a#article.css, #s#series.css
I link regularly to other sites like Wikipedia. Can I shorten the input?

website features so-called pseudo-protocols. You can use them instead of HTTP to shorten href and src attributes.

Let’s take Wikipedia as an example. Assume, you have this in your file:

    "w": ""

Then you can write in your articles href="w:Typography", which will automatically expanded to href="".

I’m not yet finished with an article. Can I exclude it from the web site?

Set the Status header to draft. This will keep the article from being embedded. You can combine multiple values for the Status header by separating them with commas.

If you set the variable DEBUG to True in your file, the draft will be included. This gives you the ability to preview it in your development environment.

Categories, Newsfeeds and Sitemaps

Can I prevent an article to appear in the news feed?

Yes. Place the header Robots: noindex in the article, and it will not appear in your news feed. It will also be not spidered by search engines.

I want an introduction on a category/tag index page.

Create a file _doc/<category>.category.html (where <category> is the name of the category) and put any markup there. It will be included before the article list on the index page of the category. For tag index pages use _doc/<tag>.tag.html.

I have some other content I’d like to see in my sitemap.xml file. How can I add it?

Put a file local_sitemap.xml in the folder _doc. This is no full XML file but rather the portion to be included in the generated sitemap.xml.

How can I create categories for articles?

See above.

How can I create tags for articles?

See above.

Dynamic Content

How can I create a simple contact form?

There is a simple contact form included in website. Just set the template of one of your articles to contact and save it with the file ending .php. In your file, set the variable EMAIL to the address the mail should go to. Presto! Your contact form is ready.

If you’re not satisfied with the way the contact template handles things, remember you can always overwrite the original template.

How do I add comment functionality to my posts?
This is answered above. website uses Disqus for this.
How can I offer a site search?

Templates, Static Content and Custom Markup

I need XHTML 1.0 instead of HTML5. Where can I change the markup?

You can overwrite the markup generated by website anytime you like by creating a folder _templates in your project and in that placing a mako template named base.mako.

Can I use a completely different template for a specific post?

Yes. You can have, if you like, a custom template for each one of your posts. This gives you the maximal freedom in creating your articles, from text-only blogs to full photo-diaries or HTML5 experiments.

Place the header Template in your article to choose a template from your _templates folder. The default is _templates/article.mako (this is loaded from the website installation, if it doesn’t exist).

Title: And now for something completely different
Template: funky

<p>This uses the template funky.mako.</p>
Where do I put my global CSS and JS files?
How do I reference images from my static files in articles?

Translations and Languages

How can I provided articles in several languages?
How do I translate the template strings?
I’m not satisfied with the default translation. Can I overwrite it?
I want to translate settings like the title. How do I do that?