blosxom :: the zen of blogging

about

  • home/about
  • features
  • colophon
  • news
  • mailing list
  • donate


    • documentation for users

  • overview
  • install
  • configure
  • blog
  • view
  • flavour
  • syndicate
  • plugins
  • plugin registry
  • static
  • faq
  • use cases*
    •

    documentation for developers

  • overview
  • plugins
    •

    downloads

  • mac
  • windows*
  • everyone

  • license
  • contributed*

    • powered by

    *coming soon

    home :: documentation :: users :: configure :: static.txt

    Amazon Honor System Click Here to Pay Learn More

    Static

    Blosxom runs either dynamically (on-the-fly) as a CGI script--the default--or on the command-line for statically rendering the main index, category indexes, and date indexes as regular files on your filesystem.

    Static rendering is useful for those who either prefer to or are only able to (they can't run CGI scripts) serve up files from their Web server. You can render your blog from the command-line on the server or locally--on your laptop, say--and save them to a mounted WebDAV drive, .Mac iDisk, or FTP/rsync them up to your server.

    You can also take a hybrid approach, statically rendering all of your regular Weblog while leaving room for experimentation with search, trackbacks, home-brewed bits of functionality, plugins, and so forth.

    Configure static rendering...

    Blosxom's default is dynamic rendering (i.e. running as a CGI script). To enable static rendering, you'll need to create a directory to hold your static Web pages and configure Blosxom for static rendering.

    1. Create a folder/directory anywhere beneath your Web-accessible document directory to hold your static Web pages. Here are few reasonable suggestions for where to put them:

    2. The confguration of static rendering is held, along with all the rest of Blosxom's configuration options, in the script itself. The default looks something like this:

      # --- Static Rendering -----

# Where are this blog's static files to be created?
$static_dir = "/Library/WebServer/Documents/blog";

# What's my administrative password 
# (you must set this for static rendering)?
$static_password = "";

# What flavours should I generate statically?
@static_flavours = qw/html rss/;

# Should I statically generate individual entries?
# 0 = no, 1 = yes
$static_entries = 0;

# --------------------------------

      Each configuration directive consists of a setting name (e.g. $static_dir, an = sign, and the setting's value (e.g. "/Library/WebServer/Documents/blog"). In the case of words, the value is kept between double-quotes ("); in the case of numbers, the quotes are absent. To change a setting's value, simply replace the current value with your preferred value. Be sure to leave the double-quotes intact if they're there.

      For example, if you were to change the location of your blog's statically rendered files from the default, /Library/WebServer/Documents/blog, to /home/username/www/blog, that setting line would end up looking like: $static_dir = "/home/username/www/blog";

      All clear? Good. Let's move on to the settings themselves.

      • $static_dir: Where to put statically rendered files. This should be the full-path to somewhere in your Web-accessible document directory.

        • ISP
          You'll need to ask your service provider for the full-path to your public Web directory and point $static_dir somewhere underneath that. For instance, if your home public Web directory were /home/sam/www, your static configuration would read: 
          # Where are this blog's static files to be created?
$static_dir = "/home/sam/www/blog";

        • Mac OS X
          If you installed Blosxom under Mac OS X using either the Blosxom for Mac OS X installer or following the install by hand instructions, this'll be: 
          # Where are this blog's static files to be created?
$static_dir = "/Library/WebServer/Documents/blog";

        • Windows 2000/XP
          If you installed Blosxom under Windows 2000/XP and are running IIS, use somewhere under your c:\Inetpub directory. While the Windows filesystem uses backslashes to separate elements of a path, Perl uses forward-slashes, like so: 
          # Where are this blog's static files to be created?
$static_dir = "c:/Inetpub/blog";

      • $static_password: The password you need to feed Blosxom in order for it to kick into static rendering mode. This is added protection against anyone statically rendering your blog from the outside world via a browser -- Blosxom already checks whether or not it's being run in a CGI or command-line environment, but better safe than sorry. Static rendering won't work with a blank password, so be sure and set one

      • @static_flavours: The list of flavours you wish to render statically. The defaults are HTML and RSS. If you have other flavours you've been using (and have the appropriate head.flavour, story.flavour, foot.flavour, and content_type.flavour files in your $datadir), simply add them to the list (separated by spaces).

      • $static_entries: Should Blosxom generate individual files for individual entries in addition to the path-based, yearly, monthly, and daily views when statically rendering? The default is no (0) since this has the potential to generate an awful lot of files if you're a prolific blogger.

    Render your blog...

    Static rendering is designed to run only from the command-line. It looks for the absence of the standard GATEWAY_INTERFACE environment variable set by your Web server to determine if it's running as a CGI or not. Just in case your server doesn't honour this convention, you need to supply Blosxom with the right password or it'll simply spit out a standard index page dynamically.

    To run Blosxom static rendering, on the command-line type:

    perl blosxom.cgi -password='whateveryourpassword'
    (Where whateveryourpassword is the password you set when configuring static rendering above.)

    Blosxom should start rendering pages like so: 

    % perl blosxom.cgi -password='whateveryourpassword'
Blosxom is generating static index pages...
/index.html
/index.rss
2002/index.html
2002/index.rss
2002/06/index.html
2002/06/index.rss
2002/06/29/index.html
2002/06/29/index.rss
...
society/index.html
society/index.rss
society/film/index.html
society/film/index.rss
%
    (Your paths will, of course, differ.)

    Run it again and Blosxom shouldn't render anything since it's smart enough to know that nothing's changed (nothing new's been blogged) since the last run. 

    % perl blosxom.cgi -password='whateveryourpassword'
Blosxom is generating static index pages...
%
    To force Blosxom to regenerate alll pages, add another command-line switch, -all=1 , like so: 
    % perl blosxom.cgi -password='whateveryourpassword' -all=1
    Blosxom should once again render all pages, regardless of how recently they've changed.

    To have Blosxom's static rendering run silently -- perhaps you're running it automatically at regular intervals and you don't want all that output popping up on your screen or being mailed to you--add -quiet=1 like so: 

    % perl blosxom.cgi -password='whateveryourpassword' -quiet=1

    automatic rendering at regular intervals...

    While you can of course run Blosxom by hand from the command-line every time you write something new to your blog, most of you will probably want to have Blosxom make a static rendering pass on a regular basis, automatically.

    If you're running a Unix variant or Mac OS X, the best tool for the job is cron, the agent that takes care of making sure just about every regular activity that's supposed to happen does. While I leave you to the cron man pages (type man cron on the command-line) and this excellent tutorial, here is a sample cron entry for Blosxom rendering every half an hour: 

    0,30 * * * * /usr/bin/perl /path/to/blosxom.cgi
-password='whateveryourpassword' -quiet=1

    (The line above has been split into two for display purposes; be sure to put everything on one line in your crontab.)

    For those of you running operating systems without cron, I'll be making some alternate instructions available in the FAQ shortly. If you have something to contribute, please do let me know.