Book Of Traceable Heraldic Art

Preface | Contribute Your Art | Terms of Use | Build Code | JSON Data

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 M, Volume E, Volume L, Volume O, Volume A, Volume F, Volume D, Volume R, Volume G, Volume S, Volume W, 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 ($250 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

Make sure CPAN is configured by running the command-line tool:
    $ 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?," press return to choose the local::lib approach to installation. Then exit the cpan shell.

You may need to add the following lines to your ~/.zshrc file:
    PATH="~/perl5/bin${PATH:+:${PATH}}"; export PATH;
    PERL5LIB="~/perl5/lib/perl5${PERL5LIB:+:${PERL5LIB}}"; export PERL5LIB;
    PERL_MB_OPT="--install_base \"~/perl5\""; export PERL_MB_OPT;
    PERL_MM_OPT="INSTALL_BASE=~/perl5"; export PERL_MM_OPT;

Install the MicroMason and JSON packages:
    cpan Text::MicroMason
    cpan JSON

Install HomeBrew:
    Download from or run
    $ /bin/bash -c "$(curl -fsSL"

You may need to add the following lines to your ~/.zshrc file:
    export HOMEBREW_PREFIX="/opt/homebrew";
    export HOMEBREW_CELLAR="/opt/homebrew/Cellar";
    export HOMEBREW_REPOSITORY="/opt/homebrew";
    export PATH="/opt/homebrew/bin:/opt/homebrew/sbin${PATH+:$PATH}";
    export MANPATH="/opt/homebrew/share/man${MANPATH+:$MANPATH}:";
    export INFOPATH="/opt/homebrew/share/info:${INFOPATH:-}";

Install ImageMagick:
    $ brew install imagemagick

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

Install chromium:
    $ brew install chromium
    $ xattr -cr /Applications/

You may need to add the following lines to your ~/.zshrc file:
    export PUPPETEER_EXECUTABLE_PATH=`which chromium`

Install Puppeteer:
    $ npm i puppeteer

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 Work/contents.txt and Work/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 500 MB.

The website build is about 5 GB for over fifty thousand files.

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