Getting Started December 10, 2015

Getting Started

This guide outlines the minimal steps to get PyKwiki serving static files.

Requirements

PyKwiki does not require anything outside of Python, but it does require the following Python packages:

  • jinja2 (>=2.6) - Jinja2 is used to compile themes into .html.
    • Install with sudo pip install jinja2
  • markdown (>=2.3) - MarkDown is the syntax used for PyKwiki.
    • Install with sudo pip install markdown
  • pyyaml (>=3.0) - Configuration files use YAML
    • Install with sudo pip install pyyaml

The above packages should be auto-installed when PyKwiki is installed.

Install PyKwiki

You can download the setup.py directly, or simply run:

$ sudo pip install -I pykwiki==1.1.6

Create a new project

The pykwiki new <Name> command creates a project directory in the current working directory. The project directory will be named <Name>.

$ cd ~
$ mkdir pykwiki_projects
$ cd pykwiki_projects
$ pykwiki new MySite
...

Serve the default content

$ cd MySite/
$ pykwiki cache -f
...
$ cd docroot
$ python -m SimpleHTTPServer 5000

Now you can navigate to http://localhost:5000 to see that PyKwiki is working.

Configuration

PyKwiki is now ready for final tweaks.

Configuration:

...
About Search December 10, 2015

About Search

How it works

1. The search index

Existing content is cached, and a search index is built.

$ pykwiki cache
...

The search index gets written to conf.index_file (default: idx.json).

Sample JSON index file format

{
    "index":{
        "foo":[3,2,5], "bar":[3,1,6], "baz":[2],
        ...
    },
    "ids":{
        "1": "somepage.html", "2": "other-page.html", "3": "baz.html",
        ...
    }
    ...
}

The index object contains a list of words as properties. Each word has a list of page ids after it. The list is sorted by the number of times that word appears in a page. In the above example, "foo" appears most in page id 3, which is baz.html. The "ids" object holds the mapping of ids to pages.

2. Themes load the index

Themes that support basic search (currently all of them) also use conf.post_data_file (default: posts.json) to load information about a page after filtering search results.

Sample JSON post data file format

{
    "info":{
        "somepage.html": { 
            "title":"Some Page",
            "url":"/somepage.html", // Relative URL
            "mtime":123456789000, // Miliseconds since 1/1/1970
            "mtimestamp":"2010-01-01 10:10", // Page().mtimestamp
            "mdate_string":"January 01, 2010", // Page().mdate_string
            "mtime_string":"10:10", // Page().mtime_string
        },
        ...
    },        
}

3. Users enter search terms

Themes specify how to compare user search terms against conf.index_file. In most cases, it goes like this:

  1. Split users' search terms into a list
  2. Remove non alphanumeric characters
  3. Compare each word in the list against the index to determine the order to display pages.
...