Book Of Traceable Heraldic Art

Preface | Terms of Use | Contributing Art | Build Code

Web Site Build Code

Source Downloads

This collection was built in a series of OmniGraffle files.

The Graffle files can be downloaded here: Volume 0, Volume 1, Volume 2, Volume 3, Volume 4, Volume 5, Volume 6, Volume 7, Volume 8, Volume 9, Volume 10, Volume 11, Volume 12, Volume 13, Volume 14, Volume 15, Volume 16, Volume 17, Volume 18, Volume 19, Volume 20, Volume 21, Volume 22, Volume A, Volume D, Volume E, Volume F, Volume M, Volume L, Volume R, Volume G, Volume W, Volume O, Volume S, Volume P

The web site is generated from those files by exporting content in PDF, PNG, and SVG format, and then running a set of build scripts which process and upload the exported files.

A copy of the build scripts is available at

Build Requirements

To generate the web site and related materials you need:
• A Mac running a recent version of MacOS.
• OmniGraffle 7 Pro ($199 from
• The free software listed below.
• A working directory containing the Graffle files and build scripts.

Specifically, the working directory should contain:
• a folder named "Graffles" with the the individual Graffle files.
• a folder named "Build" with the build scripts and static files.

Open-Source Software

Install Chrome, or make sure your existing installation is on version 59 or later.
    Download from

Install HomeBrew:
    Download from or run
    $ ruby -e "$(curl -fsSL"

Install node.js:
    Download from or run
    $ brew install node

Install yarn:
    $ brew install yarn

Install Puppeteer:
    $ yarn add puppeteer

Make sure CPAN is configured
    $ cpan

If you've never configured CPAN before, you'll be asked if you'd like to configure automatically; press return for yes, and when asked "What approach do you want?," either press return to choose local::lib, or choose sudo and run the below commands:
    cpan> o conf makepl_arg "INSTALLBIN=/usr/local/bin INSTALLSCRIPT=/usr/local/bin"
    cpan> o conf commit

Install MicroMason
    cpan Text::MicroMason

Build Process

The build folder includes a Perl script named that reads and combines the source files to create the web site. There's also a related configuration file, make.conf, which contains definitions used by the script.

Adjust the configuration in Build/make.conf to include your web hosting target in the "[Web Destination]" section. If the web hosting target is on a remote server, you may want to set up SSH keys or hold a session open so that you're not prompted to re-enter your password every time you re-generate the site.

Within the working folder, make empty folders named Book, PDF, PNG, and SVG.

In OmniGraffle, open each file and export it four times using the default file name and the following settings:
• As PDF in "Entire Document" and "Multi-Page" mode into the Book folder.
• As PNG in "Artboards only" mode at 300 DPI into the PNG folder.
• As SVG in "Artboards only" mode into the SVG folder.
• As PDF in "Artboards only" mode set to "Individual Files" into the PDF folder.

Any time you edit one of the Graffle files, export it again in the same way.

(I have my fingers crossed that OmniGraffle will eventually expose the artboard export feature to AppleScript so that this process can be automated.)

Then run "perl Build/" and wait a few minutes for it to finish. The amount of time required depends on how many of the source files have been edited since the last run; on my computer this process takes around twenty minutes if starting from scratch, and about two minutes if running it again without any changes to the source documents.

The build process will generate files named Output/contents.txt and Output/index.txt; if you've added or renamed pages, you should copy-n-paste this into the relevant pages of the Vol0 Graffle file and re-run the export and build process.

File Size

The Graffle files are currently about 375 MB.

The website build is about 2.25 GB for over twenty-five thousand files.

Total material uploaded to your web host will also include 1.25 GB for the printable PDFs of the individual volumes and compiled book, 0.9 GB for the zip files of all images, and 0.5 GB for the zip files of the Graffle sources, for a total of about 5 GB.