{ 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. skin.html --------- This is the first file you want personalise. By default, it looks like this: <?module title ?>

Default header

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 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][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 server). If you use this multilingual support, the default language is `en` (English). [MD]: http://daringfireball.net/projects/markdown/ (official site) [here]: skin.txt (source file for this page) [Apache]: http://projects.apache.org/projects/http_server.html (official site) 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.)