Fork me on GitHub

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 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.

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.

Discussion