# Gazest site deployment manual

## About

Gazest is a community engine centered around a Wiki. This document describes how to setup and administer a Gazest site.

Gazest has two types of target users: systems administrators running a Gazest powered site and visitors of such a site. To prevent confusion, this document use "user" or "visitor" for a person visiting a Gazest powered site and "site admin" or "webmaster" for someone deploying a Gazest site.

## Install

See `README.txt`.

## Configuration

Most of the configuration is done through you `.ini` file. Most values should be self explanatory but the most obscure are described here.

- `staging`: If `true`, robots and spiders are not allowed to the site. Use this in the final stage of deployment but before you go live.

- `wiki_index`: Name of the page returned when accessing the wiki without a page name. Most sites will never change that but there is a similar setting in MediaWiki so I suppose there is a use for that.

- `wiki_indexing_delay`: Time to way after a new page revision is committed before a spider can index it. The time spec is the same format at GNU `sleep`. This is good against spammers since you can weed out their links before the pages are indexed.

## Customizing

Your Gazest site will hopefully have some branding of his own. The default `.ini` includes the lines

    extra_templates = %(here)s/extra_templates
    extra_statics = %(here)s/extra_statics

which refers to directories relative to your `.ini` file where you can put files that will override the files included in the Gazest distribution.

The first step in customizing the look of your site will be to add a 90 pixel hight image as `extra_static/img/top-banner.jpg`. You can change much of the style by CSS. Just save your custom styles in `extra_static/css/site.css`. Have a look at the files packaged in `gazest/public` to see what kind of style you need to produce.

It might happen that need more than CSS. In that case you'll have to override the Mako templates. You should consult the Mako manual before you engage in this adventure. Now, have a look at the files packaged in `gazest/templates`. Most of the pages inherit from `base.mako` so it will probably be your primary target for customization. You can override the template called `gazest/templates/foo.mako` by just creating a file called `extra_templates/foo.mako`. This include templates rendered directly as a page, inherited templates, and templates included in another template through `<% include …%>`.

## Wiki Macros

You can add "macros" to the wiki markup. Tags like `{{foo.bar qux}}` will look for a function `bar` in module `foo` and call it with a `Page` object and the string `"qux"`. You only have to register in which modules the wiki can look for function with the `gazest.wiki_macros` Setuptools entry point.

The lookup will not cross modules so in your macro module you can do

    import math
    from os import path

but not

    from math import *

You can prevent a function from becoming a macro by naming it with a leading underscore ("_"). Look at the `gazest_extra_macros` package distribution for examples.

Note | You can use the `Page` object to produce "out of page" side effects and other advanced rendering but this part of the API is not stable yet.

## Wiki Syntax

The syntax is handled in two parts: the wiki stuff and the presentation stuff. The wiki stuff is

    [[some page]]
    {{somemacro arg1 arg2}}

all the rest is left to the presentation renderer to expand. The default renderer is Markdown but the user can enable another one with a macro. See the `gazest_extra_macros` package for alternative renderer. As an example, to enable restructured text, one would add this macro to his page:

    {{rst.enable}}

The choice of renderer is global to the page. If more than one renderer enabling macro is supplied, the last renderer is used.

You can change the rendered preferences from your `.ini`. To change the default renderer, put the enabling macro in the `wiki_header`; to force the same renderer on all pages, put the enabling macro in `wiki_footer`.