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
- Markdown python module <http://www.freewisdom.org/projects/python-markdown/Installation>
- WebOb <http://pythonpaste.org/webob/>
- PAM <http://atlee.ca/software/pam/>

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, the niki app will serve it at /static but this method is slow and has not been tested for security or robustness. 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:8082/>.

Internals
---------
NikiWiki is a (mostly) 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 [Jinja](http://jinja.pocoo.org/) or [Mako](http://www.makotemplates.org/).

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.