Introducing PocketPress SSG
TL;DR: PocketPress is available on GitHub and NPM
For a couple years I've maintained this site with Publii, a great desktop-based static site generator (SSG) that can deploy to GitHub Pages. I decided to look around at different SSGs because maintaining certain pieces was becoming a little tedious through the customization options it provides. I went to the JamStack list of generators to look around and saw a huge number of options (347 as of this post). After looking through many, I decided most of the well-maintained generators were quite large and complex, and I might as well write my own. Everyone else apparently does!
A Small Idea
For ultimate readability, I considered integrating a few minimal templating/preprocessing libraries such as Pug and Stylus, which I have used for small SSR frameworks previously. Ultimately, though, I went with LiveScript for everything. LiveScript is one of my favorite tools for creating domain-specific languages. It is a full programming language with a terse, functional, indentation-based syntax. I'd also used it on the client side as a hyperscript (in place of JSX) in a very similar way.
I started by scanning files and then prefixing them with a header which contained every HTML tag and CSS property as functions returning abstract nodes, then reading the tree and rendering markup. This allowed me to create very nice-looking templates:
html lang: "en", head do meta charset: "UTF-8" title "Example Page" meta name: "viewport" content: "width=device-width, initial-scale=1.0" link rel: "shortcut icon" type: "image/png" href: "/favicon.png" style do rule ".brand", color "white" font-size "24px" font-weight "bold" margin-right "30px !important" body do nav do a.brand href: "/", "Dan Finch" ul do li a href: "/", "About" li a href: "/experience/", "Experience" li a href: "/tech/", "Tech" li a href: "/blog/", "Blog" li a href: "/contact/", "Contact" main do "..."
I also put a proxy around the element functions which allows class names to be
added with the
. syntax. In the above example,
As small as my site is, the generation was quite slow. This is because I was appending a
giant list of locals to each template (the HTML element and CSS property functions) and
then compiling through LiveScript and
evaling. To fix this, I instead forked a child
process which defined these functions once, in global scope, and then ran each template.
This sped the generator up considerably and also gave me accurate line numbers when an
Update 2023-01-31: I'm now generating these symbols before build as locals in the
context where the
eval lives to remove the need for a child process, resulting in
It was annoying to have to run the generator in the terminal, switch to the browser, then
refresh each time I made a change, so I added a watch mode with chokidar.
I wanted live reload, too, but I didn't want to import or maintain an HTTP server just for
this feature - I like being able to preview the site locally.
fetch and XHR cannot be used
file: URLs, so instead PocketPress embeds a
<script> tag which stores a timestamp,
sets a timer, then removes itself. When the timer fires (one second later), the
is re-added to the page. If PocketPress has updated that script in the meantime, it will observe
that the timestamp has changed and will refresh the page.
In the weeks since I've started the project I keep thinking of new things to add, some of which I
actually need and others that just seem appropriate. PocketPress now supports complex nested CSS
rules & at-rules, many blogging features, and standalone generation of
.md files -
the latter of which I am using to create the awesome-js-runtimes
What started as a simple utility to maintain my personal site has become a very enjoyable project to work on & use. I would love feedback, issues, etc. It is published on NPM and the source code is available at GitHub. The best example of its usage is the source code for this site.