“Secretary of Foreign Relations”
(A test Pollen site: version 0.25)
I’ve created this site to experiment with making websites that are also printed books using Pollen, as well as to help explain Pollen to people who might be interested in using it for themselves. The official Pollen documentation is well done and improving all the time, and you should really start by reading it thoroughly. But a quasi-guided tour through a simple working site might help put the pieces together, and illustrate the benefits of the Pollen system.
You can see the site live at https://thelocalyarn.com/excursus/secretary. While browsing there, be sure to click on the “◊ Pollen Source” links at the top of the individual pages to see the Pollen markup that was used to generate that page.
The code is not very well commented yet. I’m working on it though.
- Install Pollen (instructions)
- Install libuuid at the command line with
raco pkg install libuuid
- (Optional) To be able to generate PDFs as well as HTML, you should have a working installation of LaTeX (specifically
xelatex) and the Tufte-Latex classes installed. If you're on a Mac, installing MacTeX will satisfy both of these. (Note, if your shell is something other than bash, you'll need to take steps to ensure
/Library/TeX/texbinis on your PATH.) Also see the note in the LaTeX/PDF section (further down) on specifying fonts that you have installed on your system, otherwise PDF builds may fail.
- Clone or download this repo
raco pollen startfrom the main folder, then point your browser to
If you have GNU Make installed (Mac or Linux) you can run
make all from the main project folder. Run
make spritz to clean up various working directories, or
make zap to delete all the output files and start fresh. See the makefile for more info (it’s pretty well commented), and of course see the docs on
raco pollen for more on generating the files in Pollen.
Points of interest
A brief and incomplete self-guided tour of the code follows. I add new things from time to time, so check back.
- Look at
pollen.rktto see the definitions for the markup I use in this project, and the code that glues everything together.
feed.xml.ppis where the RSS feed is generated.
- The two files
flatland-book.ltx.ppgenerate a complete PDF book of Flatland using the same
.poly.pmsource files in the
flatland/subfolder. This PDF file can be sent right to CreateSpace or any other print-on-demand service; as a demonstration, I’ve made the print book available for order at CreateSpace.
- Look through the
.pmfiles to see what writing in Pollen markup looks like. (Another way to do this is to click the “Pollen source” links on sub-pages at the live site.)
So far I’ve added two minor markup innovations to this project:
◊versetag for poetry: This is one example of an area that Markdown does not (and likely will never) address properly. By using this tag I can output the exact HTML markup I need, which I can then style with CSS to center based on the width of the longest line. In LaTeX/PDF, this tag also automatically replaces double-spaces with
\vinto indent lines.
◊index-entrytag: Intended to mark passages of text for inclusion in a book-style index. A separate page,
bookindex.html, iterates through the pagetree, gathers up all of these entries and displays them in alphabetical order, grouped by heading. (Basically just like the index at the back of any serious book you have on your shelf.) This is another example of something that would be impossible in Markdown. Of course, on the web, this is something of an anachronism: it would probably be better for the reader to have a normal search form to use. However, besides serving as an illustration, this tag will allow for effortless inclusion of an index when I add support for this in LaTeX/PDF.
You can see the code used to generate the index at the bottom of
pollen.rktand in the
Any file with the
.poly.pm extension can be generated as a pretty darn nice-looking PDF file as well as HTML. My LaTeX templates make use of the Tufte-LaTeX document classes, to match the Tufte-CSS in use on the web side.
In addition, the preprocessor files
flatland/flatland-book.pdf.pp generate a complete PDF of the entire Flatland book.
You may want to edit the fonts specified in the
\setmonofont commands in
flatland/flatland-book.ltx.pp; I have them set to Adobe Caslon Pro and Triplicate, respectively, so if you don't have those fonts installed you will get errors.
The official Pollen docs describe the basic method for LaTeX and PDF targets, but my method differs somewhat due to the need for additional cleverness.
In my LaTeX template, any hyperlinks also get auto-converted to numbered side-notes. Unfortunately, this niftiness also means that when targeting LaTeX, you can't have a hyperlink inside a side-note since that would equate to a side-note within a side-note, which causes Problems. I could simply stipulate "don't put hyperlinks in margin notes" but I wanted a more elegant solution. Solving this problem meant departing from the methods in the official tutorial. The details are in this post at the Pollen mailing list.
The site now generates an RSS feed in Atom 1.0 format (tested at the Feed Validator, of course). The
feed.xml.pp file is heavily commented and explains how this works.
Grouping pages by series
I implemented a simple system for grouping pages according to a “series” — think of a series of articles in a journal or magazine (or maybe what you’d call categories in a blog).
As specified in
index.ptree all posts sit together in one big pool in the
posts subfolder. Each post can optionally specify a series:
◊(define-meta series "series/poems.html")
I opted to specify the series by the Pollen target filename, but it could just as easily be the human-friendly name of the series (doing it this way allows me to change that name without affecting the posts that refer to it).
Then for every series, I create a Pollen file in the
series subfolder which serves as a brief introduction to the series, and manually add that to
template-index.html (the template specified in
index.html.pm) includes code that iterates over all the pages in the
series subfolder, prints out its contents, then lists all the posts that specify that series in their metadata (using the
list-posts-in-series function defined in
Converting Markdown to Pollen
I’ve created a basic custom writer for pandoc that allows you to convert Markdown files (or anything, really) into Pollen markup. I’d see three appropriate uses for this. One is for banging out first drafts that consist of long stretches of simple prose. In those cases there's not a lot of structure or metadata to be concerned with at the very outset, and you can take advantage of editors and tools that recognize Markdown syntax. Second, it allows you to more easily accept drafts in other formats from other people who aren't familiar with Pollen concepts. Third (the big one for me) it can help a lot with automating the process of mass-importing old material into a Pollen publication.
The code is in
util/pandoc-pollen.lua, and the template file is in
util/pandoc-pollen-template.pm. You can use it like so from within the project root folder:
pandoc -t util/pandoc-pollen.lua -o YOUR-OUTPUT.poly.pm --template=util/pandoc-pollen-template.pm SOURCEFILE.md
Or to convert a bunch of Markdown files at once, run this Bash script:
#!/bin/bash for f in *.md; do \ pandoc --template=util/pandoc-pollen-template.pm -t pandoc-pollen.lua "$f" > "$f.poly.pm" done
You should open up
util/pandoc-pollen-template.pm and customize the code to match the Pollen markup for your project. You’ll likely still need to clean up the resulting files once they’ve been sent through the wringer, but this will do a lot of the tedious work for you.
Other good examples
Besides getting answers to my inane newbie questions in the discussion group (which I try my best to keep to a minimum), I’m greatly assisted by being able to peruse the code of a couple of other Pollen creations.
Matthew Butterick's article Making a dual typed/untyped Racket library was created with Pollen and is a good learning resource. I initially missed the links at the bottom to the Pollen source code for the article, which is very well commented.
Matthew Butterick also keeps a list of other Pollen projects and guides in the official Pollen documentation.