Greg Boone

Tag: Static site generators

The Lasting Power of WYSIWYG

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.

rePress: Jekyll with a WordPress Frontend

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).

There have been a few different ways people have approached the task of marrying WordPress with static site generators. Ben Balter’s WordPress to Jekyll exporter is one that takes on Jekyll specifically, then there’s StaticPress, a plugin for WordPress that transforms your installation into a static site, and finally CFPB is taking on the task of building a static site generator that will pull from WordPress and other APIs. rePress takes a different tack but is inspired by these other initatives.

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.

Discuss on HackerNews.

Static sites revisited

jekyll logo

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:

  1. Create a new user in your system, give them a minimal role, and assign post authorship ex post facto
  2. 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.