Hi, I'm Bruce Williams.

RTex Webby Filter (2008-04-29)

Good news today. Webby, my favorite little static website generator that could, is now being developed on GitHub. This will make contributing to the project easier for those of a git persuasion, and hopefully take a bit of pressure off Tim’s shoulders in the long-term. I’ll be maintaining a fork for contribution.

I really enjoy playing with Webby, and my recent work with RTeX has tweaked my interest in integrating PDF generation. Here’s a walkthrough on how to add a quick filter to do just that.

Installing the Goods

First of all, some prerequisites:
  1. Get started on Webby, and create a project.
  2. Install RTeX
  3. Brush up on your LaTeX (see the RTeX FAQ for a pointer on resources).

If you’ve done all this, you’re ready… if you haven’t, you’re just skimming to see if this is interesting and/or simple, and that’s okay, too.

Creating a Document

Let’s create a file in your Webby content/ directory called example.tex and put the following in it:

---
extension: pdf
created_at: 2008-04-29 08:12:58.135564 -05:00
layout: false
filter: rtex
---
\documentclass[12pt]{article}
\begin{document}

\title{A simple RTeX-generated PDF}
\author{You \\ your-address@your-site.com}
\maketitle

\newpage

See, it's simple\ldots

\end{document}

Okay, LaTeX content aside (it can be a bit much to take in if you’re not used to it), this is a simple document.

The first portion of the file (the part that looks suspiciously like a YAML document) is the metadata. The first thing you should notice is the rtex filter we’re assigning, which we’ll work on shortly.

We also set some other bits; the extension so that the generated document is named correctly (ie, example.pdf), and layout, which we unset (you could use a nice, reusable LaTeX layout, but let’s skip that for this example).

A Simple Filter

Creating the filter for Webby is easy; it’s just the bit of glue that sticks RTeX and Webby together.

In your Webby project’s lib/ directory (create it if needed), add a file. You can call it whatever you like, but let’s use rtex_filter.rb for now.

Here’s the contents of the file:

require 'rtex'
Webby::Filters.register :rtex do |input, cursor|
  RTeX::Document.new(input).to_pdf
end

Not exactly rocket science, is it?

The Results

Now, regenerate your site. I commonly keep this running, as you can read about in the Webby documentation:

  rake autobuild

You should find example.pdf in the corresponding location under output/. Just link it from your normal Webby pages; and here’s mine, freshly generated.

Obviously this is a simple document, but don’t let that fool you. Much more complex documents can be generated, for example this fancy sample from an TeX Tutorial was also generated live.

With very few changes to the filter (eg, looking for additional processing options in a page’s metadata), arbitrarily complex documents can be created directly from Webby.

Not bad for a “runt with a special knack for transforming text” and a gem that’s a poor man’s binding.