How to skin your site

You will have noted that the default appearance of the web site is a bit spartan. Plus, it features text you didn’t even write in the first place. You probably want to change that before you release the actual web site.

Take a look at your _ussm/ directory.

$ ls -F _ussm/
tmp/  www/  settings  skin.html  ussm
$

The tmp/ directory contains temporary files.
The www/ directory contains the compiled web site.
The settings file is a configuration file you can modify.
The ussm file is the program that is actually launched when you run USSM. By default, this is a simple shell script that you can easily modify (but you probably don’t need to).
The skin.html file is the template around which your web site will be formed. Basically, it is how your site will look.

skin.html

This is the first file you want personalise. By default, it looks like this:

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title><?module title ?></title>
    <meta name="description" content="<?module description ?>"/>
  </head>

  <body>
    <header> <h1>Default header</h1> </header>

    <nav>
      <a href="/">Home</a>
      <?module menu ?>
    </nav>

    <article> <?module core ?> </article>

    <footer>
      Default footer. Legalese typically goes here. <br />
      If you have <em>any</em> trouble using
      <a href="http://loup-vaillant.fr/projects/ussm">USSM</a>,
      please <a href="mailto:l@loup-vaillant.fr">send me an email</a>. <br />
      Your confusion is my problem.
    </footer>
  </body>
</html>

This is valid HTML, except for those <?ussm xxx?> things. they are place holders for content specific to each page. Everything else is shared among every pages. Here, we have 4 different place holders:

Title. The title of the page.
Description. The description of the page (useful for search engines).
Menu. A hierarchical menu for the page.
Core. The main content of the page.

Those place holders generate reasonable code by default, you probably don’t need to tweak them. Otherwise, you can edit the setting and ussm files.

settings

This file contains the default parameters for USSM. Here it is:

{
  boring: ^_\n.*~$\n^#.*#$
  source-extension: txt
  html-processor  : markdown
  default-language: en
}

(Note that it looks like a source file header: indeed, it is of the same format.) Currently, USSM uses 4 different settings:

boring. Some files just should be ignored most of the time. such files include configuration files and backup files. This parameter is a list of line-break separated regular expressions. Any file whose name match at least one of those regular expression is considered “boring”, and USSM will ignore it.

By default, boring files are those whose name:
- Begins by ‘_’ (configuration files).
- Ends by ‘~’ (emacs backup files).
- Are enclosed in ‘#’ (emacs temporary backup files).
Tip: when you want to compile your site, but don’t want to publish a page that you are currently writing, just add an underscore at the beginning of the name of the corresponding file. The boring parameter will tell USSM to ignore your unfinished text.
source-extension. Not every file in your source tree is meant to spawn a web page. Only those whose file name have the provided extension will.

By default, source pages are files whose name ends by .txt. (They also must have a valid header)
html-processor. Writing HTML code by hand is tedious. Most of the time, you wish to just write your text, and let the system figure out the proper HTML code, just like any decent blog engine.

By default, source files are processed with markdown (this is the format I use to write this very page).
default-language. USSM has limited multilingual support, letting you translate all or part of your web site. It is meant to be used with content negotiation (it works with the Apache web server).

If you use this multilingual support, the default language is en (English).

ussm

Where everything happens. Literally. _ussm/ussm is the executable file that gets invoked when you compile your web site. The main ussm command does only two things:

Jumps to the root directory of your source files.
Invoke _ussm/ussm, which does all the rest.

With this approach, USSM can be anything you like. you just have to edit your _ussm/ussm file, which by default is a shell script. Here is its whole content:

#! /bin/sh
# Clean up
rm -rf _ussm/tmp/ _ussm/www/

# Copy the directory structure
for dir in $(ussm-source-dirs); do
    mkdir -p _ussm/tmp/$dir
    mkdir -p _ussm/www/$dir
done

# Copy every non-boring files
for file in $(find . -name _ussm -prune -o -type f -print |\
              ussm-remove-boring); do
    ln $file _ussm/www/$file
done

# Run the modules
ussm-core
ussm-title
ussm-description
ussm-menu         # must be run after ussm-title

# Put together the web pages (must be done after the modules)
ussm-assemble

Most of it should be obvious. We need a few more words about the modules though.

The modules are programs that generate a “module file” for each source file, and put it in the _ussm/tmp/ directory. For instance, the ussm-core program will generate the _ussm/tmp/foo.core from foo.txt. Currently, there are 4 modules:

ussm-core processes the main text of the source files, generating html code for each. It uses the html-processor setting to know which program shall do the actual translation (Markdown by default).
ussm-title extract the title of each source file, using its header.
ussm-description does the same, for the description.
ussm-menu generates a hierarchical menu for each source page, to help with navigation. This is in my eyes the single most important module. I wouldn’t use USSM without it. (Or maybe I’d write the damn feature, then modify the _ussm/ussm script accordingly.)