1. Introduction

Aspen is designed around the idea that there are basically two kinds of websites, publications and applications, differentiated by their organization and interface models. A publication website organizes information into individual pages within a hierarchical folder structure that one navigates by browsing. In an application website, on the other hand, data is not organized into hierarchical pages but is dealt with via a non-browsing interface such as a search box.

The HTML version of this documentation is an example of a publication website: a number of hypertext documents organized into sections. If we weren't using LaTeX (or if I knew how to use it better), the sections would probably be encoded in folders. Gmail is a pure application website, one which organizes and presents information non-hierarchically. Most websites, however, are hybrids. That is, within an overall hierarchical organization you will find both individual pages of information as well as applications such as a site search feature, or a threaded discussion forum.

Publication websites are actually a subset of application websites, of course. An application site can use any interface metaphor; a publication is an application that uses the familiar folder/page metaphor to organize and present its information. Therefore, every website is fundamentally an application.

Aspen enables the full range of websites: publications, applications, and hybrids. It uses the filesystem for the hierarchical structure of publication and hybrid websites, and provides a mechanism for including applications within that hierarchy.

An Aspen website is a collection of files, self-contained within a single directory, called the root of the website (cf. Apache's DocumentRoot directive). In general, URLs map directly to the filesystem. That is, given a root of:

/usr/local/www/example.com

A request for /foo.html would serve a file at:

/usr/local/www/example.com/foo.html

If all you want to do is serve static files, then that's most of what you need to know.

To extend an Aspen website, you use a Unix-style userland located within a directory under the website root named __ (that's two underscores), also called the website's magic directory. The existence and contents of this directory are safe from prying eyes, because Aspen will respond to any requests mapping to the magic directory with a 404 Not Found.