extra_templates = %(here)s/extra_templates extra_statics = %(here)s/extra_statics
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.
See README.txt.
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.
nb_site_proxy: Used to infer the right client IP address. For most sites, this will be 1 if running behind mod_rewrite or mod_proxy and 0 if running standalone, under mod_wsgi or under mod_python.
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 …%>.
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. |
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.