Table of Contents

1. Why use Travail
2. Why not use Travail?
3. Setup and Installation
   1. Building Travail
   2. Installing Travail
   3. Configuration
   4. Configuring your webserver
4. How do I organize my site files?

Travail is a simple program to run a personal website or blog. It’s meant to keep easy things simple and complex things possible, per Alan Kay.

Travail looks at Markdown or HTML files in its site folder. The contents of this directory determine what’s on your site. HTML and Markdown become pages, subfolders become subsections, etc.

See the setup section to get started

Why use Travail

I created Travail with two main objectives. One is that it should be easy to host and run on a variety of environments, including self-hosting, or highly restricted hosting environments. The other is that it would be “dead simple.”

My definition of dead simple may be different from others. For me, it meant something like the following:

1. It should be essentially self-contained and have no dependencies on any other programs to do its basic job.
2. It should not require extensive configuration to work in a sensible manner.
3. The contents and layout of the website should be manageable as much as possible by putting and arranging files on the filesystem with normal text editing and file management tools.
4. Plaintext formats wherever possible, and no build-step.
5. It should last essentially forever without needing to be babysat.

Since your whole sites configuration fits a single directory, its easy to backup, version, and otherwise keep track of. You don’t need to install a bunch of programs on your host server to make it work. It can even run as a standalone webserver if you don’t want to configure one (though you probably should, see Setup instructions).

Why not use Travail?

Many other servers could probably meet your needs. Apache or nginx is perfectly capable of serving similar sites, configured in a similar manner. But they require tinkering, maintenance, and continual upgrades.

If you need something that has a concept of publishing i.e making a post that has a “date” and automatically sends info out to subscribers or something like that, Travail does not do this by default, though it could be extended to do so.

I run two Travail sites currently on NearlyFreeSpeech.net. To spin up a new site on their platform, I just have to drop a single file to install Travail, then drop my site folder to the correct location, and tell NFS to forward HTTP traffic to Travail. This can all be done from graphical applications or web interfaces, and then essentially forgotten about.

Don’t use Travail in a security-critical environment, and assume that everything in the site directory is public.

Setup and Installation

You need to acquire the program file first. The releases page (TBD) has some prebuilt executables for common operating systems, so if you download from there you can skip the section about building Travail.

Otherwise, you need to build the program from its source code. Thankfully, this is a relatively straightforward process, but it requires using a terminal.

Building Travail

The best way to acquire the source is to install Fossil and clone this repository. Fossil is also a single-file to install. Once its placed somewhere you want it to be, you can clone the source code by typing/pasting the following in your terminal:

mkdir travail
fossil clone https://chiselapp.com/user/josef/repository/Travail/ travail.fossil --workdir travail
cd travail

Once you are in the travail directory, you will need one more thing to get started, which is to install opam. Run this command and follow the prompts. If it asks you about adding some stuff to a “.bashrc” file or similar, say yes, this is necessary for it to work.

bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh)"
eval $(opam env)

If this went well, just one more step remains before we have our executable.

opam switch create .

If it prompts you to install any additional packages, say yes, as those are necessary for the build to complete. If opam reports no issues, one more step remains to test:

dune exec Travail

As soon as you hit enter, go to http://localhost:8080 in your browser and you should see a basic site!

Installing Travail

If you want to install Travail locally on the machine you just built the source on you can just run and then it can be run simply by typing at the command line. Type for a list of options that can be entered, you can type .

If you don’t want to install it on your computer, you should be able to find the file at _build/default/bin/main.exe. You can rename this file to whatever you want, but travail probably makes the most sense.

If you downloaded a release, you already have the file

Put this file wherever you want to run it from and that’s all that you need to do to install it. There may be additional steps necessary depending on what kind of environment you are hosting from.

Configuration

Travail intentionally has few configuration settings. There are have sensible defaults, but you may want to alter them. You will probably need to specify a different site directory from the default using the option.

Here’s the help text displaying all the options.

travail [-sitedir] <dir> [-title] <sitetitle> [-period_spacing] <single|double>
  -sitedir Set site root
  -title Set site headline/base title
  -period_spacing Set spacings after periods
  -help  Display this list of options
  --help  Display this list of options

Here’s an example showing all of the different options in use with example values provided:

travail -sitedir /var/www/my_site -title "My Site" -period_spacing single

This is all that’s necessary to get it up and running. Put your site files in the site directory you specified and they should start to appear.

Configuring your webserver

TBD

How do I organize my site files?

The top-level of the site directory corresponds to your “home page” that displays when you visit your site.

The easiest way to get the hang of how this works is to see the example site folder in the repository and play around with copying it and manipulating it, but here is a written description:

If you go to this page, you’ll see a list of pages corresponding to files/folders inside of this site directory. If you click into a folder’s page, you will see a similar page, but relative to the folder you are visiting instead of the top-level directory.

If you click on a page that is a Markdown or HTML file, it will show up as the article contents of the page. The left navbar will stay relative to the folder the file is in. The top navbar always has the contents of the top-level folder. Anything else your browser will try to handle according to the media type. Videos will open in a player, zips will be downloaded, etc.

If a folder has an index.md or index.html file, this will be the page content when you click on the folder. It’s a good idea to put an index.md at the top of the site directory, but experiment with what works best for you.

If you want some stuff not to show, like a directory for static files, or a draft of a page, just put an underscore at the beginning of the file name/

If you need to change the order that files appear in, create a file in the requisite directory called _order. Put the names of files, without extensions, in the order you would like them to appear. Anything not in this file will sort after the files listed here in alphanumeric order.