title: How to skin your site
description: You want to customise you site.
Believe me, you do.
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.
This is the first file you want personalise. By default, it looks like
This is valid HTML, except for those `` 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
- **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
This file contains the default parameters for USSM. Here it is:
html-processor : markdown
(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
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][MD] (this is
the format I use to write [this very page][here]).
- **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
If you use this multilingual support, the default language is `en`
[MD]: http://daringfireball.net/projects/markdown/ (official site)
[here]: skin.txt (source file for this page)
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:
# 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
# Copy every non-boring files
for file in $(find . -name _ussm -prune -o -type f -print |\
ln $file _ussm/www/$file
# Run the modules
ussm-menu # must be run after ussm-title
# Put together the web pages (must be done after the modules)
Most of it should be obvious. We need a few more words about the
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
- `ussm-title` extract the title of each source file, using its
- `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.)