README
======

What is it?
-----------
NikiWiki is a simple wiki written in Python with web.py and markdown. It is designed to be simple to use and easy to 
modify to suit my needs (though it may be useful for you too).

Usage
-----
Editing pages is as simple as clicking on the page name in the top right corner, or on any header element within the 
page. Once you are done editing, click save to POST the content back to the server.

Content authoring is done using the [markdown syntax](Markdown_Syntax) allowing you to create nice looking HTML pages 
without the redundancy of writing a bunch of HTML by hand.

Requirements
------------
- A recent Python. Tested with 2.5, but older versions may work as well
- The web.py framework <http://www.webpy.org/>
- Markdown python module <http://www.freewisdom.org/projects/python-markdown/Installation>
or
- Google App Engine (with the appengine branch)

Installation
-----
Open niki.py in your favorite editor and change INSTALL_DIR to point to the directory with the nikiwiki installation 
inside. You may also edit the contents of the vars dict to customize various aspects of the page template.

- SITE_NAME defines the title of the page
- SITE_MOTTO is the text displayed below the site name at the top left of the page
- STATIC_URL should point to the location of the nikiwiki/static/ directory accessible to web users. By default, web.py 
will serve it at /static but using this value is not recommended for performance reasons. Ideally, you would create a 
symlink to this directory from somewhere within your web server's docroot.

Save the niki.py file and run `python niki.py` to start the server for debugging. At this point, you should be able to 
access the wiki at <http://localhost:8080/>. For further customization of the web server and more production-like 
configuration, read the [web.py documentation](http://webpy.org/cookbook)

Example FastCGI/nginx configuration
-----------------------------------
Place the following in your nginx configuration
<code><pre>location / {
    fastcgi_pass  127.0.0.1:9999;
    fastcgi_param   PATH_INFO    $fastcgi_script_name;
    fastcgi_param   REQUEST_METHOD  $request_method;
    fastcgi_param   QUERY_STRING  $query_string;
    fastcgi_param   CONTENT_TYPE  $content_type;
    fastcgi_param   CONTENT_LENGTH  $content_length;
    fastcgi_param   SERVER_ADDR   $server_addr;
    fastcgi_param   SERVER_PORT   $server_port;
    fastcgi_param   SERVER_NAME   $server_name;
    fastcgi_param   SERVER_PROTOCOL $server_protocol;
    fastcgi_pass_header Authorization;
    fastcgi_intercept_errors off;
}
location /static {
    root /path/to/nikiwiki/static;
}</pre></code>

Start the nikiwiki server `python niki.py fcgi 127.0.0.1:9999`

Assuming the rest of your nginx configuration is correct, you should be able to access the wiki through nginx. At this 
point, adding things like authentication and logging are trivial. See the [nginx 
documentation](http://wiki.codemongers.com/NginxModules) for details.

Internals
---------
NikiWiki is a RESTful application in that you can perform the usual view, create, update, and delete actions through 
standard HTTP methods. The implemented methods are as follows:

- GET requests will return an HTML representation of the page with all the JavaScript trimmings. It wouldn't be too 
difficult to add a GET variable along the lines of ?format=txt to return the raw data, but I haven't had a need for that 
sort of functionality yet.
- POST requests are required to pass in a variable named 'content' that contains the full markdown text of the page as 
entered by the user. The response body is the HTML result of running the content through the markdown parser. If the 
page in question does not exist, it will be created, otherwise, it will be overwritten.
- PUT requests behave in exactly the same manner as POST requests.
- DELETE requests will remove the page from the server.

A few quick notes on the implementation details:

- The render() method takes a variable number of keyword arguments that are merged with a pre-populated dict and passed 
to the string content of a template for formatting. This provides rudimentary templating support. If you want a more 
featureful templating system, take a look at [Cheetah](http://www.cheetahtemplate.org/) or 
[Mako](http://www.makotemplates.org/).
- The sanitize() method attempts to remove any malicious characters from a pagename variable. This is in no way 
foolproof and only acts as a measure against the simplest attacks. If you want to make NikiWiki more secure, this is 
probably a good place to start.

Caveats
-------
This code is largely imperfect and was written hastily with little attention to things like security and stability. If 
you intend to deploy NikiWiki to a public web server, **you are putting your server at risk**. You have been warned.