I’ve been writing this blog as a Jekyll for quite some time now. There’s a lot I really do love about the idea of static sites, but also a lot I’ve cooled on. One of those things was the writing experience.
My first encounter with Jekyll was at CFPB and I briefly switched to Octopress while I was learning how it worked. At 18F, I decided it’d be prudent to eat my own dog food, as it were, and host my blog the same way we hosted the site I was managing, 18f.gsa.gov. It’s been three years on Jekyll now and while I love a lot about Jekyll and the paradigm of static sites, I’ve grown tied of the work I have to do just to publish a new post. I’ve written about this before and won’t repeat myself but I was hopeful that there would be a product, open source or otherwise, that would give all the advantages of static hosting with a writing and publishing experience that was just as simple and powerful. The fact is, there’s not.
And it turns out easy publishing on a trustable platform is all I really want.
Getting here meant I had to write a Jekyll plugin and a page to generate a WordPress eXtended RSS (WRX) file out of the old Jekyll site. Most of the work was done in the liquid page, except for custom fields which were filled in with the plugin. The only problem I’ve noticed so far was about 22 pages with no title that were in the WRX file — these were Jekyll paginator pages and the WRX file itself also generated as HTML 🤷♂️.
Earlier this week I wrote another post comparing static site generators to
content management systems using Jekyll and WordPress (perhaps unfairly) as representatives of their respective technologies. It got me thinking that in writing it I was compairing apples to oranges. Static site generators are not content management systems. They are generators, converting properly formatted input into webpages. To compare it to a content management system is like comparing TeX to Microsoft Office. Perhaps a better metaphor than apples and oranges is apples to farmland.
The things I outlined that static site generators don’t quite have down are really all management tasks. A built-in text editor, management of categories and tags, clearly defined content types, automatic rewrite rules for if you rename a page, I could go on and on: These are all features a good content manager should have built in. With static site generators you have to do all that yourself, particularly if you’re hosting your site with Jekyll on GitHub pages or want to add commenting to your blog posts.
I am under no illusion that this blog will probably never have anonymous, inline commenting like it did when I hosted it on WordPress, but it was a conscious move to encourage my readers to comment through GitHub issues and pull requests. Most of my comments were fixing my typos anyway and now I don’t have to log in to my admin screen to fix them. They fix themselves! That is all to say, if I wanted to get away from a particular content management system I could have easily switched to a different one, and if I wanted a DIY content management system I could have used Django or learned Rails to build one. Switching to a static site generator was an intentional decision to reassess the value of all the things a CMS would give me by eliminating most of them completely.
Jekyll has become one of my favorite things lately. At 18F we’re using it to power our website but also our Hub project which includes serving up snippets, our weekly team updates submitted by Google Form, as well as a tremendous amount of information that is a mix of pages restricted to our team and some that is public. The Hub uses Prose to allow people less comfortable with GitHub and Markdown to edit Jekyll pages with something closer to a What you See is What You Get (WYSIWYG) interface than a typical markdown document has. Prose is a great tool, and I’m not just saying that because we use it. But for many static sites haven’t quite gone far enough, and that’s okay.
Early adopters like static sites a lot. People who bought one of the first Blackberries or used WordPress in 2006, for example, might like static site generators a lot. People who like Markdown or other markup languages enjoy static site generators. And some appreciate the simplicity of configuration found in static sites, especially the lack of a database. For many people like me it is a refreshing focus on writing without the complications of The Admin UI that have plagued even the best CMS platforms.
An example of these complications? I recently helped my wife with some settings on her blog and was reminded how confusing the WordPress Admin can be. Where do you think you should go to set your front page to display a page instead of latest posts? Settings > General? Settings > Writing? Settings > Media? The answer: None of the above. It’s Settings > Reading. I guess when I think about it that makes sense, you’re changing a setting that changes the experience for someone reading your site.
At the same time, there are still some things that a CMS does really well that static site generators
lack. At least to me, Jekyll’s simplicity is a feature that forces me to think about the value of, for example, a tag archive or automatic image formatting before implementing it. With a CMS these features are there waiting for you to use or extend. WordPress for example provides a really simple API to extend the WYSIWYG interface with ‘shortcodes.’ All of this comes in handy when you need to create a blog post with images floated left and right and center, or when building that tag archive (easy as it may
be) means taking away time from publishing real content.
If I’m not a developer, needing to become one or hire one just to start writing a blog post is a pretty high barrier to entry. Feeling like I need to become one just to write a blog post is even higher. The reason I became a developer in the first place was that in 2006 when I needed to reboot my college radio station’s website WordPress was insanely easy to install and configure and gave us almost everything we needed (with the right theme and plugins), and in 2009 when I built the first version of HarmsBoone.org and International Underground I didn’t need to learn much beyond CSS and a few WordPress methods. When I eventually needed to know more it was still a fairly low barrier to entry and we always had a website that everybody could edit. In particular, Child themeing is particularly useful for learning WordPress on the fly.
Static sites, for all their simplicies and technical advantages, still have a pretty high barrier to entry, especially if you need to overcome the limitations GitHub pages puts on Jekyll sites. And to be fair, WordPress has significant (read: 8-10 year) head start over Jekyll plus the entire WordPress Core and Automattic teams nurturing the developer base.
Nevertheless, without lowering that bar and adding some of those features it will be really hard to get broader adoption among people who want a Just Start Writing Already. For many, logging in to the WordPress Admin and using the WYSIWYG either to write or to paste in copied text will always be preferable to editing monospaced text with strange formatting signals around it, even if there are buttons to help them out. (Let’s not belittle the bar-lowering power or Prose, Dillinger, and other Markdown helpers, though, for some they may be exactly the right tool.)
It will remain preferable even if they rely on a bookmark in their browser, or an icon on their desktop to get them to the admin screen. Clicking “Preview” will be preferable to navigating to running a shell command and then heading to localhost:4000 because what’s a localhost? What’s that colon all about? And what’s so special about 4000? And clicking “Publish” will definitely be preferable over committing a git workflow to memory.
These are problems Static Site Generators can solve, and part of what makes them beautiful is how they are malleable to each user’s needs. And if you put
a developer on the comms team you’ll be able to build the site you need on the platform that works because you’ll ask your users what they need and how they work. If your users need to
copy and paste blog posts from Google Docs, give them that. If they want a WYSIWYG editor for writing and collaborating on posts, give them that. If the need the full WordPress UI, give them that. I’m not trying to sound flippant. Building a WYSIWYG on top of Jekyll would be a difficult problem, but it’s not
impossible. Using Google Drive as a CMS will also take work, it’s not impossible. Building GUI applications to abstract away the command line is difficult, but not impossible.
There are hundreds of content management
systems and static site generators operating on nearly every language in existence (including FORTRAN). And there are WordPress plugins for nearly everything imaginable at this point, and usually there are three of four of them to choose from. Your mileage will almost certainly vary from one solution to another but go with the solution that will make your content creators most comfortable.
Note: I’m not maintaining this open source project anymore. There was a pretty cool reception to it and I didn’t have time to maintain it for just myself. I still think it’s a good idea, though. 🙂
About five months ago I left the riveting world of WordPress development for the greener pastures of helping a government startup manage its website, and while I’ve become pretty taken with Jekyll lately, there will always be a part of me that loves WordPress. And so, like a good hacker, I started a side project I’m calling rePress (a name that, admittedly, needs work—see below).
The first two of these solutions are WordPress plugins, and the second generates content from an API. This combines the two ideas by creating generator plugin for Jekyll sites that relies on the REST API currently being integrated into WordPress Core. Right now that API is only available as a plugin, but it will one day (soon, I think) require only a clean WordPress installation.
Once you have the API exposed, you need only point Jekyll to the root endpoint and run jekyll build on your server or your local environment. Right now it will grab the 9 most recent posts and parse out the published title, date, tags, authors, and excerpts, and, of course, the post content and generate HTML files with proper Jekyll frontmatter. This has a couple benefits: it allows you to import your WordPress posts without exporting any files and it allows you to choose whether to write Jekyll Markdown or use the WordPress editing interface.
It definitely has a long way to go, but it’s something I’ve been excited about creating pretty much since the REST API project was first announced. I’ll be pushing updates to GitHub, and would love any suggestions you have. In particular, I kind of hate the name I came up with, but all the original ideas like JekyllPress, StaticPress, and Hyde all mean other things related to Jekyll and WordPress. So here I am, with a name that means subdue by force which is not at all what this does or is intended to do. I’m open to name suggestions but know that it’ll probably change at some point.
I’ve been thinking a lot about static site generators lately. We use Jekyll at 18f, a generator platform I had previously only used in the context of Octopress and very briefly and fleetingly at CFPB. My past life as a
WordPress developer effectively ended in September when I began shifting careers a bit to go back to my pervious role of hybrid communications-web developer, and begin a new adventure building a full website without a CMS, without a database.
The most challenging part of this has been thinking about data and content first. In my experience developing on WordPress a request to put something new into the website usually involved one of two things: adding more custom fields and relying on the intentionally lackluster UI to accomplish that, or creating a new menu on a wp-admin screen. If you’re going the latter route you have to think about form validation, design, and what the appropriate method for saving might be just when building the menu. Displaying the saved content to the user requires a whole other step of ensuring you have the right information coming
out of the database.
Jekyll (which I’m using as a stand-in for any static site generator) simplifies that whole system by abstracting away the UI altogether. Let’s use guest authors as an example. Here’s the problem: you have an author on a blog post who is not a regular contributor and maybe they’ll never write a post again. In WordPress I’ve seen this problem solved two ways:
Create a new user in your system, give them a minimal role, and assign post authorship ex post facto
Create a custom field called, e.g., guest-autho and use template logic to replace the name in the byline
Both of these have problems. In the first, you’re adding users with no relationship to the rest of the site. In the second, you’re adding extra data
to a post, and confusing data at that. Either way, the semantic representation of the post in the database is messy.
How to approach this in Jekyll? The easiest way is to just use the author’s name in the author field of the post front matter. But this solution is not
without it’s problems either. On the 18F site we keep all our team members in a long YAML file inside the _data directory and we reference post authorship out of that file and wrote a little Jekyll plugin to fill in their full name and (maybe someday in the future) extra information about the author. If we have guest authors we have to break that pattern or write logic into either the template or the plugin to address it.
In this example, both WordPress and Jekyll fail to give you a perfect
solution. On the one hand, WordPress (and most CMSs) give you that “about the author” information out of the box, especially if you go with option 1. But in exchange you get a new problem Jekyll’s minimalist, database-free paradigm seems to answer: authors needn’t relate to any part of the system except the posts they author.
I’m not sure which is best. I loved hacking away at WordPress even when it drove me mad. It gives you 90% of what you need out of the box, and querying a database is convenient, especially if you’re site is really complex. By not having a database, Jekyll forces you think broadly about what data you really need for a post and for your site because everything is built before a user loads their first webpage. As we’ve scaled 18f.gsa.gov
from basically a blog to a more functional site, these questions haven’t held us back as much as they have forced us to think differently about the problem.