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.
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).
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
bear like this:
bear $DOCROOT destination-path
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
$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.
.svndirectories are ignored, as well as svn meta files (e.g.
%prefs.txtfiles are used to render
.txtfiles but are not copied themselves.
- Other non-
.txtfiles are copied into the
.txtfiles 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.
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:
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_use_markdown – tells bear to render this directory’s files using
the Markdown syntax
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
BEAR_template_inherits) is not supported (they may work,
but may have perverse effects).
%template.txt files should be formatted using normal HTML or XHTML,
unless they inherit, in which case they should be the relevant fragment
Templates have two special tags that bear uses to render contained text:
BEAR_bodytext tag is replaced by the source file’s text, or the
rendered output of a template which inherits from this one.
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.
If you declare a destination path then the contents of
synchronized to the destination location by rsync (via SSH if to a
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.