Pwyky (A Python Wiki)

Pwyky is a ~30KB single file wiki in Python. It's very easy to install, requires minimal configuration, and uses a simple structured text format. It's free software: released under a GPL 2 licence. There's a fully functional version online for you to try.

Getting and Installing Pwyky

Requirements: Apache, and Python 2.3+.

• Download: pwyky.py.txt (33,564 bytes)

To install:

• Create a new script-writable directory on your server
• Upload pwyky.py.txt as index.cgi, and CHMOD 755 it
• Visit http://yourserver.tld/directory/index.cgi

Important: you must visit the path with the full file name the first time around, so that it can install itself. From then on, visiting http://yourserver.tld/directory/ will work. As soon as you visit it, it should be fully installed and ready to use!

About: Background, and Features

A wiki is a program, often a CGI, which enables you to edit a website using an HTML form. You can limit the editing priviliges to a single or group of users, or let anyone in the world edit it.

Pwyky was written by Sean B. Palmer, the same guy who wrote wypy, the 18-line Python wiki. After writing one of the world's smallest wikis, he decided to write a proper wiki.

The features that pwyky has are:

• Structured text format with headings, paragraphs, lists, preformatted sections, and blockquotes.
• Unicode support.
• Recent changes, needed pages, and unlinked pages documents.
• A fast links database.
• Quick customization through a config file.
• Diff, grep, and archival functions.
• Quick statistics links on all pages.
• Easy page-removal (post a blank entry).
• File backup (for one previous version).
• Simple (i.e. unbloated) text macros.
• Ability to run as a comand line document conversion script.

The requirements were:

• To not get in the way; to expose as little of the "wikiness" of the site as possible. All of the recent changes, page list, and other metadata are hidden as much as possible from the user whilst still being accessible.
• To be easy to install, easy to set-up, easy to upgrade.
• To be a testbed for some wiki ideas.

One of the main features of a wiki that gives it its character is the nature of its structured text syntax...

The Syntax

Summary:

• Paragraphs are seperated by blank lines.
• "@ " starts a heading.
• "* " starts a list item.
• "{{{" and "}}}" on seperate lines delimit preformatted blocks.
• "[[[" and "]]]" delimit blockquotes.
• "{" and "}" in paragraphs, headings, and list items delimit links.

Example:

@ Heading

Paragraph.

* Bulleted list.
* Bullets can extend over
two lines.
* Third item in the list.

{{{
Preformattted area.
}}}

[[[
A quote
]]] - http://example.org/citation

Links: {LocalLink} will link to ./LocalLink, {Local Link} will 
link to the same, and {http://example.org/ example.org} will be a 
titled link to example.org.

Formatting: Hints and Tips

Generally:

• "{U+HHHH}" will enter a unicode character, in any section (except for blockquote citations). All printable characters except -, ], and } will be added as-is; entities are used for the rest.
• Take care to leave a blank line in front of list sections.
• An "@ Heading" on the very first line will be taken as an <h1>; all other headings will be taken as <h2>s.
• Citations for blockquotes must be valid URIs.
• Note that headings can't extend over more than one line. They have a double space inserted after them on conversion back to wiki format, anyway.

In paragraphs, headings, and list items:

• "{{" will be escaped to "{". This allows you, for example, to type an unescaped "{U+HH}" by typing "{{U+HH}".
• On many occasions, em-dashes will be automatically converted from "--". To type "--", you can do something like "{U+2D}-".

In preformatted sections, and blockquotes:

• Note that em-dashes do not get escaped, and nor do links get resolved. {$function} and {U+HHHH} do get resolved, though.
• If you want to use "}}}" in a preformatted section, you can do "{U+7D}}}". It would also be acceptible to put the escaped reference in any other part of the "}}}". Likewise "{U+5D}]]" for "]]]".

Configuration

Configuration is achieved through a config.txt in the pwyky folder; if the file isn't present, then pwyky will use its own defaults. The syntax is that of RFC 822 message headers; field name, colon, space, entry.

• "default" - the wiki name used by the root of the site, i.e. the page that one gets when visiting "/". Default value: "index"
• "sname" - the short name of the site, which must be suitable to put in a file name if logging is being used. Default value: "pwyky"
• "lname" - the long name of the site. Default value: "my pwyky site"
• "pedit" - configures whether public editing links will be used; set to "False" to turn off. Default value: "True"
• "owner" - HTML fragment which is the address of the author. Default value: the server's domain name
• "logdir" - the directory in which to place log files; note that it's off by default. Default value: "False"

The config file needn't have all fields; you can just have the fields for which you want to override the defaults. For example:

sname: notes
lname: my notes
pedit: False
owner: <a href="http://example.org/person/">Person's Name</a>
logdir: /home/person/web

Other: Using Pwyky

You can use the following bookmarklet to edit your pages if you don't have public editing links enabled: javascript:void(location = document.location.href.replace(/\/([A-Za-z0-9-]+)$/, '/@edit/$1').replace(/\/$/, '/@edit/index'))

Feedback

Send comments to the author, Sean B. Palmer.