===================== Configuring Pyblosxom ===================== You configure a Pyblosxom blog by setting configuration variables in a Python file called ``config.py``. Each Pyblosxom blog has its own ``config.py`` file. This chapter documents the ``config.py`` variables. Some of these are required, others are optional. .. Note:: Pyblosxom comes with a sample config file. This file does **not** have everything listed below in it. If you want to use a variable that's not listed in your config file---just add it. Config variables and syntax =========================== Each configuration variable is set with a line like:: py["blog_title"] = "Another pyblosxom blog" where: * *blog_title* is the name of the configuration variable * *"Another pyblosxom blog"* is the value Most configuration values are strings and must be enclosed in quotes, but some are lists, numbers or other types of values. Examples:: # this has a string value py["foo"] = "this is a string" # this is a long string value py["foo"] = ( "This is a really long string value that breaks over " "multiple lines. The parentheses cause Python to " "allow this string to span several lines.") # this has an integer value py["foo"] = 4 # this is a boolean--True has a capital T py["foo"] = True # this is a boolean--False has a capital F py["foo"] = False # this is a list of strings py["foo"] = [ "list", "of", "strings" ] # this is the same list of strings formatted slightly differently py["foo"] = ["list", "of", "strings"] Since ``config.py`` is a Python code file, it's written in Python and uses Python code conventions. Plugin variables ================ If you install any Pyblosxom plugins those plugins may ask you to set additional variables in your ``config.py`` file. Those variables will be documented in the documentation that comes with the plugin or at the top of the plugin's source code file. Additional plugin variables will not be documented here. Personal configuration variables ================================ You can add your own personal configuration variables to ``config.py``. You can put any ``py["name"] = value`` statements that you want in ``config.py``. You can then refer to your configuration variables further down in your ``config.py`` file and in your flavour templates. This is useful for allowing you to centralize any configuration for your blog into your ``config.py`` file. For example, you could move all your media files (JPEG images, GIF images, CSS, ...) into a directory on your server to be served by Apache and then set the config.py variable ``py["media_url"]`` to the directory with media files and use ``$media_url`` to refer to this URL in your flavour templates. Codebase configuration ====================== .. py:data:: codebase (optional) string If you have installed Pyblosxom on your web server using your distribution's package manager or Python setuptools then you don't need to set the codebase variable. If you cannot install Pyblosxom on your web server then you can save the Pyblosxom source code to a location on your server and use the codebase setting instead. The codebase setting tells the Python interpreter where to find the Pyblosxom codebase. This should be the full path to where the Pyblosxom directory is on your system. It should be the path to the directory that holds the "Pyblosxom" directory (note the case--uppercase P lowercase b!). For example, if you untarred Pyblosxom into ``/home/joe/pyblosxom-1.5/``, then the Pyblosxom (uppercase P and lowercase b) directory should be in ``/home/joe/pyblosxom-1.5/`` and you would set your codebase variable like this:: py["codebase"] = "/home/joe/pyblosxom-1.5/" Blog configuration ================== .. py:data:: blog_title string This is the title of your blog. Typically this should be short and is accompanied by a longer summary of your blog which is set in ``blog_description``. For example, if Joe were writing a blog about cooking, he might title his blog:: py["blog_title"] = "Joe's blog about cooking" .. py:data:: blog_description (optional) string; defaults to ``""`` This is the description or byline of your blog. Typically this is a phrase or a sentence that summarizes what your blog covers. If you were writing a blog about restaurants in the Boston area, you might have a ``blog_description`` of:: py["blog_description"] = "Critiques of restaurants in the Boston area" Or if your blog covered development on Pyblosxom, your ``blog_description`` might go like this:: py["blog_description"] = ( "Ruminations on the development of Pyblosxom and " "related things that I discovered while working on " "the project") .. py:data:: blog_author (optional) string, defaults to ``""`` This is the name of the author of your blog. Very often this is your name or a pseudonym. If Joe Smith had a blog, he might set his blog_author to "Joe Smith":: py["blog_author"] = "Joe Smith" If Joe Smith had a blog, but went by the pseudonym "Magic Rocks", he might set his blog_author to "Magic Rocks":: py["blog_author"] = "Magic Rocks" .. py:data:: blog_email (optional) string; defaults to ``""`` This is the email address you want associated with your blog. For example, say Joe Smith had an email address ``joe@joesmith.net`` and wanted that associated with his blog. Then he would set the email address as such:: py["blog_email"] = "joe@joesmith.net" .. py:data:: blog_rights (optional) string; defaults to ``""`` These are the rights you give to others in regards to the content on your blog. Generally this is the copyright information, for example:: py["blog_rights"] = "Copyright 2005 Joe Bobb" This is used in the Atom and RSS 2.0 feeds. Leaving this blank or not filling it in correctly could result in a feed that doesn't validate. .. py:data:: blog_language string This is the primary language code for your blog. For example, English users should use ``en``:: py["blog_language"] = "en" This gets used in the RSS flavours. Refer to `ISO 639-2`_ for language codes. Many systems use two-letter ISO 639-1 codes supplemented by three-letter ISO 639-2 codes when no two-letter code is applicable. Often ISO 639-2 is sufficient. If you use very special languages, you may want to refer to `ISO 639-3`_, which is a super set of ISO 639-2 and contains languages used thousands of years ago. .. _ISO 639-2: http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes .. _ISO 639-3: http://www.sil.org/iso639-3/ .. py:data:: blog_encoding string This is the character encoding of your blog. For example, if your blog was encoded in utf-8, then you would set the ``blog_encoding`` to:: py["blog_encoding"] = "utf-8" .. Note:: This value must be a valid character encoding value. In general, if you don't know what to set your encoding to then set it to ``utf-8``. This value should be in the meta section of any HTML- or XHTML-based flavours and it's also in the header for any feed-based flavours. An improper encoding will gummy up some/most feed readers and web-browsers. W3C has a nice `tutorial on encoding`_. You may refer to `IANA charset registry`_ for a complete list of encoding names. .. _tutorial on encoding: http://www.w3.org/International/tutorials/tutorial-char-enc/ .. _IANA charset registry: http://www.iana.org/assignments/character-sets .. py:data:: locale (optional) string; defaults to ``"C"`` Pyblosxom uses the locale config variable to adjust the values for month names and dates. In general, you don't need to set this unless you know you're not using en_US or en_UK. A listing of language codes is at http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt A listing of country codes is at: http://userpage.chemie.fu-berlin.de/diverse/doc/ISO_3166.html For example, if you wanted to set the locale to the Dutch language in the Netherlands you'd set locale to:: py["locale"] = "nl_NL.UTF-8" .. py:data:: datadir string This is the full path to where your blog entries are kept on the file system. For example, if you are storing your blog entries in ``/home/joe/blog/entries/``, then you would set the ``datadir`` like this:: py["datadir"] = "/home/joe/blog/entries/" .. Note:: A note about ``datadir`` on Windows: Use ``/`` to separate directories in the ``datadir`` path even if you are using Windows. Examples of valid datadirs on Windows:: py["datadir"] = "/blog/entries/" and:: py["datadir"] = "e:/blog/entries/" .. py:data:: depth (optional) integer; defaults to 0 The depth setting determines how many levels deep in the directory (category) tree that Pyblosxom will display when doing indexes. * 0 - infinite depth (aka grab everything) DEFAULT * 1 - datadir only * 2 - two levels * 3 - three levels * ... * *n* - *n* levels deep .. py:data:: ignore_directories (optional) list of strings; defaults to ``[]`` The ``ignore_directories`` variable allows you to specify which directories in your datadir should be ignored by Pyblosxom. This defaults to an empty list (i.e. Pyblosxom will not ignore any directories). For example, if you use CVS to manage the entries in your datadir, then you would want to ignore all CVS-related directories like this:: py["ignore_directories"] = ["CVS"] If you were using CVS and you also wanted to store drafts of entries you need to think about some more in a drafts directory in your datadir, then you could set your ``ignore_directories`` like this:: py["ignore_directories"] = ["drafts", "CVS"] This would ignore all directories named "CVS" and "drafts" in your datadir tree. .. py:data:: flavourdir (optional) string This is the full path to where your Pyblosxom flavours are kept. If you do not set the ``flavourdir``, then Pyblosxom will look for your flavours and templates in the datadir alongside your entries. .. Note:: "flavour" is spelled using the British spelling and not the American one. For example, if you want to put your entries in ``/home/joe/blog/entries/`` and your flavour templates in ``/home/joe/blog/flavours/`` you would set ``flavourdir`` and ``datadir`` like this:: py["datadir"] = "/home/joe/blog/entries/" py["flavourdir"] = "/home/joe/blog/flavours/" .. Note:: Use ``/`` to separate directories in the ``flavourdir`` path even if you are using Windows. Examples of valid ``flavourdir`` on Windows:: py["flavourdir"] = "/blog/flavours/" and:: py["flavourdir"] = "e:/blog/flavours/" .. py:data:: default_flavour (optional) string; defaults to ``"html"`` This specified the flavour that will be used if the user doesn't specify a flavour in the URI. For example, if you wanted your default flavour to be "joy", then you would set ``default_flavour`` like this:: py["default_flavour"] = "joy" Doing this will cause Pyblosxom to use the "joy" flavour whenever URIs are requested that don't specify the flavour. For example, the following will all use the "joy" flavour:: http://example.com/blog/ http://example.com/blog/index http://example.com/blog/movies/ http://example.com/blog/movies/supermanreturns .. py:data:: num_entries (optional) int; defaults to 5 The ``num_entries`` variable specifies the number of entries that show up on your home page and other category index pages. It doesn't affect the number of entries that show up on date-based archive pages. It defaults to 5 which means "show at most 5 entries". If you set it to 0, then it will show all entries that it can. For example, if you wanted to set ``num_entries`` to 10 so that 10 entries show on your category index pages, you sould set it like this:: py["num_entries"] = 10 .. py:data:: truncate_frontpage (optional) boolean; defaults to True Whether or not to truncate the number of entries displayed on teh front page to ``num_entries`` number of entries. For example, this causes all entries to be displayed on your front page (which is probably a terrible idea):: py["truncate_frontpage"] = False .. py:data:: truncate_category (optional) boolean; defaults to True Whether or not to truncate the number of entries displayed on a category-based index page to ``num_entries`` number of entries. For example, this causes all entries in a category to show up in all category-based index pages:: py["truncate_category"] = False .. py:data:: truncate_date (optional) boolean; defaults to False Whether or not to truncate the number of entries displayed on a date-based index page to ``num_entries`` number of entries. .. py:data:: base_url (optional) string; default is calculated based on HTTP server variables This is the base url for your blog. If someone were to type this url into their browser, then they would see the main index page for your blog. For example, if Joe Smith put his ``pyblosxom.cgi`` script into a cgi-bin directory and he was using Apache, his base_url might look like this:: py["base_url"] = "http://example.com/~joe/cgi-bin/pyblosxom.cgi" However, it's common that this can be determined by Pyblosxom by looking at the HTTP environment variables--so if you're not doing any url re-writing, it's possible that Pyblosxom can correctly determine the url and you won't have to set the base_url variable at all. If Joe got tired of that long url, Joe might set up some url re-writing on my web server so that the base_url looked like this:: py["base_url"] = "http://example.com/~joe/blog" .. Note:: Your ``base_url`` property should *not* have a trailing slash. .. Note:: If you use mod_rewrite rules or some other url rewriting system on your web server, then you'll want to set this property. .. py:data:: parser (optional) string; defaults to "plain" The default entry parser that Pyblosxom will use to parse this blog's entry files. See :ref:`Entry parsers`. Logging configuration ===================== .. py:data:: log_file (optional) string This specifies the file that Pyblosxom will log messages to. If this is set to "NONE", then log messages will be silently ignored. If Pyblosxom cannot open the file for writing, then log messages will be sent to sys.stderr. For example, if you wanted Pyblosxom to log messages to ``/home/joe/blog/logs/pyblosxom.log``, then you would set ``log_file`` to:: py["log_file"] = "/home/joe/blog/logs/pyblosxom.log" If you were on Windows, then you might set it to:: py["log_file"] = "c:/blog/logs/pyblosxom.log" .. Note:: The web server that is executing Pyblosxom must be able to write to the directory containing your ``pyblosxom.log`` file. .. py:data:: log_level (optional) string This is based on the Python logging module, so the levels are the same: * ``critical`` * ``error`` * ``warning`` * ``info`` * ``debug`` This sets the log level for logging messages. If you set the ``log_level`` to ``critical``, then *only* critical messages are logged. If you set the ``log_level`` to ``error``, then error and critical messages are logged. If you set the ``log_level`` to ``warning``, then warning, error, and critical messages are logged. So on and so forth. For "production" blogs (i.e. you're not tinkering with configuration, new plugins, new flavours, or anything along those lines), then this should be set to ``warning`` or ``error``. For example, if you're done tinkering with your blog, you might set the ``log_level`` to ``info`` allowing you to see how requests are being processed:: py['log_level'] = "info" .. py:data:: log_filter (optional) string This let's you specify which channels should be logged. If ``log_filter`` is set, then ONLY messages from the specified channels are logged. Everything else is silently ignored. Each plugin can log messages on its own channel. Therefore channel name == plugin name. Pyblosxom logs its messages to a channel named "root". .. Warning:: A warning about omitting root: If you use ``log_filter`` and don't include "root", then Pyblosxom messages will be silently ignored! For example, if you wanted to filter log messages to "root" and messages from the "comments" plugin, then you would set ``log_filter`` like this:: py["log_filter"] = ["root", "comments"] .. _plugin-configuration: Plugin Configuration ==================== There are two properties in your ``config.py`` file that affect the behavior for loading plugins: ``plugin_dirs`` and ``load_plugins``. .. py:data:: plugin_dirs (optional) list of strings; defaults to an empty list The ``plugin_dirs`` variable tells Pyblosxom which directories to look in for plugin files to load. You can list as many plugin directories as you want. For example, if you stored your Pyblosxom plugins in ``/home/joe/blog/plugins/``, then you would set ``plugin_dirs`` like this:: py["plugin_dirs"] = ["/home/joe/blog/plugins/"] .. Note:: Plugin directories are not searched recursively for plugins. If you have a tree of plugin directories that have plugins in them, you'll need to specify each directory in the tree. For example, if you have plugins in ``~/blog/my_plugins/`` and ``~/blog/phils_plugins/``, then you need to specify both directories in ``plugin_dirs``:: py["plugin_dirs"] = [ "/home/joe/blog/my_plugins", "/home/joe/blog/phils_plugins" ] You can't just specify ``~/blog/`` and expect Pyblosxom to find the plugins in the directory tree:: # This won't work! py["plugin_dirs"] = [ "/home/joe/blog" ] .. Note:: Core plugins are automatically found---you don't have to specify anything in your ``plugin_dirs`` in order to use core plugins. .. py:data:: load_plugins (optional) list of strings If there is no ``load_plugins`` setting in ``config.py`` Pyblosxom loads all plugins it finds in the directories specified by ``plugins_dir`` in alphanumeric order by filename. Specifying ``load_plugins`` causes Pyblosxom to load only the plugins you name and in in the order you name them. The value of ``load_plugins`` should be a list of strings where each string is the name of a plugin module (i.e. the filename without the .py at the end). If you specify an empty list no plugins will be loaded. For example, if you had:: py["plugin_dirs"] = ["/home/joe/blog/plugins/"] # py["load_plugins"] = [] in your ``config.py`` file and there were three plugins in ``/home/joe/blog/plugins/``:: /home/ +- joe/ +- blog/ +- plugins/ +- plugin_a.py +- plugin_b.py +- plugin_c.py then Pyblosxom would load all three plugins in alphabetical order by filename: ``plugin_a``, then ``plugin_b``, then ``plugin_c``. If you wanted Pyblosxom to only load ``plugin_a`` and ``plugin_c``, then you would set ``load_plugins`` to:: py["load_plugins"] = ["plugin_a", "plugin_c"] .. Note:: In general, it's better to explicitly set ``load_plugins`` to the plugins you want to use. This reduces the confusion about which plugins did what when you have problems. It also reduces the potential for accidentally loading plugins you didn't intend to load. .. Note:: Pyblosxom loads plugins in the order specified by ``load_plugins``. This order also affects the order that callbacks are registered and later executed. For example, if ``plugin_a`` and ``plugin_b`` both implement the ``handle`` callback and you load ``plugin_b`` first, then ``plugin_b`` will execute before ``plugin_a`` when the ``handle`` callback kicks off. Usually this isn't a big deal, however it's possible that some plugins will want to have a chance to do things before other plugins. This should be specified in the documentation that comes with those plugins. Caching Configuration ===================== Enabling caching by setting the ``cacheDriver`` and ``cacheConfig`` variables in ``config.py`` speeds up rendering of your Pyblosxom pages. .. py:data:: cacheDriver (optional) string; defaults to "" Pyblosxom has multiple cache mechanisms. Look at the source files in ``Pyblosxom/cache`` to see what mechanisms are available, then set ``cacheDriver`` to the cache mechanism that you want. For example:: py["cacheDriver"] = "entrypickle" .. py:data:: cacheConfig (optional) string; defaults to "" Read the top of the source code file in ``Pyblosxom/cache`` for your selected cache driver (e.g. ``entrypickle.py``) to see how to set the ``cacheConfig`` variable for it. For example:: py["cacheConfig"] = "/path/to/a/cache/directory" .. Note:: ``load_plugins`` should contain a list of strings where each string is a Python module---not a filename. So don't add the ``.py`` to the end of the module name! Static Rendering Configuration ============================== If you are using static rendering to deploy your Pyblosxom blog you need to set some additional configuration variables in your ``config.py`` file, see :ref:`static-rendering`.