Introduction to Bear

Welcome to the Bear CMS docs. This page is a basic documentation effort by way of example. The source file is available at docs.md.

Installation

Copy bear to wherever you want it to reside.
optional: Install Text::Markdown. If you don’t know how to install CPAN modules then you probably want to ask someone who does (it’s not hard, but it’s quirky and if you didn’t know already then you probably have better things to do with your time).

Staging

Set up bear by putting files in a directory structure like this:

$DOCROOT
   staging/
   %template.txt
   file1.txt
   file2.txt
   nontextfile.doc
   nontextfile.gif
   otherdir/
      %template.txt
      file1.txt
      file2.txt

Running

Run bear like this:

bear $DOCROOT destination-path

Rendering

When you run the program it sweeps the staging area looking for files to do something with, and then attempts to render or copy those files so that the $DOCROOT mirrors the structure of the staging area but in rendered form. In general it only does things if the file in the staging area is newer than the file in $DOCROOT, or if the equivalent file does not exist in $DOCROOT.

Directories are created if needed.
. files are ignored.
.git, CVS and .svn directories are ignored, as well as svn meta files (e.g. svn-commit.tmp~).
The %template.txt and %prefs.txt files are used to render .txt files but are not copied themselves.
Other non-.txt files are copied into the $DOCROOT area.
.txt files are rendered.

Rendering is the process of turning a raw (or somewhat marked up) text file and turning it into an HTML page.

Preference directives are inherited from the preference files.
The header of the .txt file is examined for preference directives.
If Markdown is turned on, the content of the .txt file is handled using Markdown format.
The text is entered into the template.
If the directory inherits its template, the rendered text is then entered into the parent template.
The contents of any directive from the source file, and any preference directives, are used to replace tags in the final output.

Preferences

A directory can have a %prefs.txt file, which specifies preferences applying to that directory and all subdirectories that don’t override. Each preference is inherited by all subdirectories that do not override the preference. Each line in the preference file is a directive with a name value pair:

#name value

Only the first space is relevant, so you can do things like

#footer This is a global footer.

You can define your own preferences – just stored text to use in your web pages – but there are two (currently) special preferences that bear relies on:

BEAR_template_inherits – tells bear to shove the output of this directory’s template into the next higher level template:

%BEAR_template_inherits true

BEAR_use_markdown – tells bear to render this directory’s files using the Markdown syntax

%BEAR_use_markdown true

File Specific Preferences

Text files to be rendered can set their own preference directives by starting the file with a block of directives in the same format as the general preference files use. In general, any preference can be set or overridden, but setting or overriding directives affecting how bear renders (e.g. BEAR_template_inherits) is not supported (they may work, but may have perverse effects).

Templates

%template.txt files should be formatted using normal HTML or XHTML, unless they inherit, in which case they should be the relevant fragment of HTML/XHTML.

Templates have two special tags that bear uses to render contained text:

The BEAR_bodytext tag is replaced by the source file’s text, or the rendered output of a template which inherits from this one.

<%BEAR_bodytext%>

The transform tag will eventually support a number of special text transformations, but currently is a one-time hack to get Faisal’s Quotes File.

Templates cannot declare their own preference directives.

Publishing

If you declare a destination path then the contents of $DOCROOT are synchronized to the destination location by rsync (via SSH if to a remote site).

Note: The staging area is published to the server along with the rendered output. This is intentional. You may wish to put a .htaccess file in there.