The following is the lightly edited script from my TechConnect presentation at ACRL 2021. The slides are available.

Hi everyone, my name is Mackenzie Brooks and I’m an Associate Professor and Digital Humanities Librarian at Washington and Lee University. I’m here today to talk about static site generators and digital literacies. I’ve titled this presentation “real talk” because I think there are some gaps in the ways we talk about the use of these tools in digital scholarship, especially when it comes to instruction. My plan for the next 20 minutes is to talk about the what/why of static site generators, share some examples from the digital scholarship world and case studies from my own projects, then discuss ways that the conversation around these tools needs to expand include curriculum, instruction, and digital pedagogy.

So what are static sites? You may be wondering, did we make it all the way through Web 2.0 just to come back to basic hand-coded websites? Not quite. The rise in popularity of static sites has come about thanks to what’s known as “static site generators.” These generators use templates, metadata, and content expressed in Markdown to generate a set of HTML/CSS/JS files necessary for your site, which are then uploaded to a server. We can compare static sites to dynamic ones where the content is generated by the web application when the web page is called, usually a database is involved. Static sites are completely built before they’re made live or accessed on the Web.

Just so you can see an example of what this looks like, here is a screen cap of my text editor when I’m working on a blog post on my personal website.

The folders labeled _includes and _layouts have snippets of code and templates that tell each page where to put the content. For example, I can write code for the footer of my website once, then simply say “include footer.html” in the page layout template. In the middle you see my post and at the top you can see the YAML metadata. Maybe I don’t want the footer to show up on the pages that hold my blog posts, so I could alter the layout for this post to remove the footer or point to another snippet of code. I can even add as many metadata fields as I want to this post so they can be called in different ways. When I’m ready to update the site, I run a build command in the command line, and all the files are generated into the _site folder, which I can then push to their final location on server somewhere.

So why might you want to use a static site? Well, one of the main attractions is their lightweight and minimal nature. My personal website takes up 4MB vs. an empty WordPress installation that takes up 60MB. This is a lighter load both for the administrator/creator of the site, as well as the end user.

In the digital scholarship world, the term “minimal computing” has emerged to describe this attention to resource constraints. You can learn more about Minimal Computing by visiting this website created by a subgroup of the Alliance of Digital Humanities Organizations (ADHO). There will also be a future issue of Digital Humanities Quarterly devoted to minimal computing and I will share my bibliography. While this is not a presentation about minimal computing specifically, I do want to be clear that minimal computing is asking these questions from a lens of social justice and from the perspective of those doing DH in the Global South. This is not just minimalism for minimalism’s sake.

But I am hoping you can imagine the trickle down benefits of sites using this technology. Not only are these sites lighter, but they might be easier to scale, to sustain, and to preserve. There are numerous static site generators so you can choose one that compliments the languages or tools you’re already using. Static sites lend themselves to the kind of practices we like to encourage in digital scholarship - version control, structured data, separation of form and content.

Finally, static sites are being touted as a vehicle for teaching digital skills and promoting digital literacies. And while I completely agree with this point, this is what I want to come back to later in my presentation.

But first, I wanted to give some examples of how static site projects are being used in and outside of the digital scholarship world.

  • Many of you may be familiar with the Programming Historian, which is a Jekyll based based site for hosting tutorials on digital scholarship methods. Their entire peer review system is run through GitHub, though its editors have admitted that the relatively high technical fluency requirements can be a barrier for editors.
  • Next we have Ed, a Jekyll theme that has been designed to display digital editions. I didn’t feature it here, but there is also Wax, a digital collections and exhibit platform built on similar methods.
  • Collection Builder is another digital exhibits tool coming out of the University of Idaho. It’s designed to import a spreadsheet of digital collections metadata and generate a site that can be pushed to GitHub Pages etc. And I will give them credit for their documentation.
  • Finally, for an example beyond digital scholarship, we have Vote.gov. The 18F group out of the GSA works to redesign agency websites, often using static site generators.

This is a short list, but there are many other examples, including Open Educational Resources.

However, for as awesome as these static site generators are, they are not without a learning curve. I made this list of skills that you would need to be able to launch a static site using a static site generator. This is a lot of things! If you work in library technology or in digital scholarship, maybe this list seems reasonable to you. But if you are outside those groups, I would argue that this is a tremendous amount of things to learn if your goal is to launch a personal website, digital exhibit, or project site. Especially when we compare it to the ease of using something like Wordpress or dare I say it, SquareSpace.

On this slide I’ve thrown up the Bryn Mawr Digital Competencies, which is my go-to framework for digital literacies. I’m not going to try to make individual connections between these two lists, but I think you can use static site generators to address any of these competencies.

Which brings us to the “real talk” part of this presentation. Static site generators as a vehicle for teaching digital literacy skills are great! Before I go any further, I want you to know that I fully endorse this and have had it validated in my personal experience.

However, I think it is a disservice to digital pedagogy and anyone who might be conducting these projects in a collaborative environment to merely gesture at these literacies, the way that most of the rhetoric around static sites tends to do.

As librarians, we may have learned most of these skills on our own through trial and error, through Googling, or through our predecessor’s hodge podge documentation. And if we’re being honest, we probably enjoyed the learning process. But our collaborative partners in digital scholarship projects, our faculty/students/staff/community members are learning from us, the librarians. We are the ones responsible for teaching these skills as DH or DS librarians.

We spent a lot of energy on information literacy instruction. And as DH/DS Librarians, we have started to think more deeply about the ways we do our work. I am reminded of the “Beyond Buttonology” article by John Russell and Merinda Kaye Hensley from 2017. They remind us that DH work should not be isolated from our work as information literacy instructors. A recent issue of DH+Lib has also looked at these connections between the Framework and DH projects. We know that we need to do more than just teach people where to click - we want to do more than that.

So what concerns me about the rise of static site generators in digital scholarship projects is that we often see lip service to these literacies without the corresponding attention to the curriculum or instruction necessary to develop these literacies. Moreover, the significant learning curve means that we have to spend a lot of time on the buttonology side of getting these sites running.

This is a screen cap from the Jekyll home page, showing you how easy it is to get up and running “in seconds”. In my experience helping students install Jekyll on their computers, we’re looking at many thousands of seconds. I’ve even waited while one student called their dad to get the admin password to their computer.

Below you’ll see a quote from a software developer in an article title “Using A Static Site Generator At Scale: Lessons Learned” in Smashing Magazine. I bring it to your attention because he’s describing the perspective of the content editors rather than the software developers. In the DH context, the content people are often our faculty and students. We need to acknowledge their perspective and experiences when evaluating and choosing platforms.

Static sites are often compared to our go-to platforms like WordPress, Drupal, or Omeka. And sure, all of these platforms are weightier than a static site and require someone to administer and update them. But I work with a number of collaborative partners for whom learning these tools is challenging enough. Asking them to write in Markdown or even edit something in GitHub is a lot. But especially in a small institution, these are relationships I value and I’m going to strive to find an approach that works for them. If I decide to recommend a static site for a digital project, it’s because I have evaluated the situation and feel comfortable devoting my time or the team’s time to the necessary and corresponding instruction. A tech stack that falls more in line with our values does not magic away the responsibility we have to our collaborators. Because when we’re the ones responsible for disseminating digital scholarship methods, they are our students and this is a pedagogical relationship, not just a service.

In his piece on the Minimal Computing Website, Stewart Varner writes, “First, while “minimal computing” may be small in terms of design and server space, It is not necessarily minimal from a labor perspective. What makes a lot of our unsustainable tools so attractive is that lowered the barriers to creating digital projects. If we raise them again, there will be those who will be at least temporarily left out and it probably won’t be wealthy institutions.”

I share this quote with the acknowledgment that I’m presenting from a wealthy institution. I’m also coming from an institution where the library faculty lead a minor in Digital Culture & Information. We have the ability to teach these skills in credit-bearing situations. I have the resources and infrastructure to do this kind of work, but that doesn’t mean that all my collaborative partners now have every single of the of the digital skills I listed earlier. These are long-term projects and they require care and attention for both the tech choices, but more importantly the relationships and the pedagogy of learning together in a team.

So with all being said, now I want to share some quick case studies from the projects that I have been involved with on my campus. All of these projects use Jekyll. Like most DH projects, none of them are finished, but you should be able to easily find the GitHub repositories with our code if you want to see examples.

First, we have the Huon d’Auvergne Digital Archive, a digital edition project that presents four Franco-Italian romance epics, encoded in TEI and with the scans presented via IIIF. The overall structure of this site is relatively simple, but the reading interface becomes complex quickly, especially given some of the needs of the scholars involved. I am the main DH collaborator on this project along with the faculty and students. Using Jekyll has helped us avoid using an XML-based web app, instead we rely on JavaScript libraries and we have a lot of control over the behavior of the site (plus we don’t have write anything in XSLT). A lot of this site’s functionality relies on the metadata for each page to link up the scan and text for each folio. The lead faculty member was really interested in learning more of this technology and so I felt like it was reasonable to select a platform that we both could work on together. The faculty member can make most of the edits to the site himself and it’s been really helpful to track all of the work in GitHub. His less technically inclined project partners make issues in GitHub when they notice something that needs fixing. That being said, we do bump up against the limits of Jekyll and are considering other options for the future.

Next we have the Florence As It Was project. This project is primarily concerned with creating 3-D models of buildings in medieval Florence and reinserting the original artwork. The website serves as a project site and encyclopedia of articles about the people and places they’re studying. Using the metadata in each page, we’re able to tag each article and then use a for loop to find the pages that have been tagged a certain way to sort them into multiple categories in the encyclopedia. This project always has a lot of students working on the site, and not all of them have the technical background or the time to make major changes to the site. However, this site has been deployed using Netlify, a continuous integration service, so students edit the pages directly in GitHub without having to install Jekyll on their computers. This has made a huge difference in our workflow.

This last example is one that I have not contributed to myself, however I have multiple students who have completed independent projects using this Jekyll theme. It’s called Flaneur and it’s built by Dawn Childress (UCLA) using Jeykll and Leaflet. It looks great, works really well, and is a great option for mapping projects. It’s easy to tinker with little pieces of this theme to change the look or functionality. Just this week I helped a student alter one option in the Leaflet code to change the way the clustering of pins works. And this is where Jekyll can really shine as a teaching tool - the student is a minor in our program, so he has encountered most of the digital skills he needs, but Jekyll is a great way to take them to the next level.

But to be clear, these DH projects are long-term and they’re led by the faculty members. I may not have the power to conduct training in the manner or amount that I think is necessary. I would imagine many of us have been in the situation of trying to back seat drive the instruction that we think we need. I’ve also worked on DH projects where the faculty member has been very upfront about not wanting to have to learn the technical pieces, so Jekyll is not something I’ve recommended for them.

So I leave you with a list of a questions. Obviously these are the type of questions to ask before embarking on any type of project. But we can all think of projects that have evolved perhaps more organically than we would like, so this is your reminder to stop and ask yourselves these things before you rush to say yes.

And I do want to end on a note of encouragement. Despite everything I’ve said, I do believe that static sites can be a great vehicle for digital literacy instruction. Believe the hype, just know what you’re getting into. Thank you.

Bibliography

  • Becker, Devin, et al. “CollectionBuilder-CONTENTdm: Developing a Static Web ‘Skin’ for CONTENTdm-Based Digital Collections.” The Code4Lib Journal, no. 49, Aug. 2020. Code4Lib Journal, https://journal.code4lib.org/articles/15326.
  • Childress, Dawn. Re-Imagining the Stack: Minimal Computing at Scale in the Digital Library. https://dawnchildress.com/2016/11/10/dlf16/. Accessed 23 Mar. 2021.
  • Connell, Ruth Sara. “Content Management Systems: Trends in Academic Libraries.” Information Technology and Libraries, vol. 32, no. 2, 2, June 2013, pp. 42–55. ejournals.bc.edu, doi:10.6017/ital.v32i2.4632.
  • Diaz, Chris. “Using Static Site Generators for Scholarly Publications and Open Educational Resources.” The Code4Lib Journal, no. 42, Nov. 2018. Code4Lib Journal, https://journal.code4lib.org/articles/13861.
  • Digital Competencies. https://www.brynmawr.edu/digitalcompetencies. Accessed 16 Mar. 2021.
  • Digital Humanities Quarterly Special Issue on Minimal Computing. http://www.digitalhumanities.org/dhq/submissions/cfps_archive.html.
  • Gil, Alex. “The User, the Learner and the Machines We Make · Minimal Computing.” Minimal Computing, 21 May 2015, https://go-dh.github.io/mincomp/thoughts/2015/05/21/user-vs-learner/.
  • Information Maintenance as a Practice of Care. Zenodo. https://zenodo.org/record/3251131#.YFEvhZkpBpQ. Accessed 16 Mar. 2021.
  • Newson, Kaitlin. “Tools and Workflows for Collaborating on Static Website Projects.” The Code4Lib Journal, no. 38, Oct. 2017. Code4Lib Journal, https://journal.code4lib.org/articles/12779.
  • Russell, John E., and Merinda Kaye Hensley. “Beyond Buttonology: Digital Humanities, Digital Pedagogy, and the ACRL Framework.” College and Research Libraries News. crln.acrl.org, doi:https://doi.org/10.5860/crln.78.11.588. Accessed 16 Mar. 2021.
  • “Using A Static Site Generator At Scale: Lessons Learned.” Smashing Magazine, https://www.smashingmagazine.com/2016/08/using-a-static-site-generator-at-scale-lessons-learned/.
  • Varner, Stewart. “Minimal Computing in Libraries: Introduction · Minimal Computing.” Minimal Computing, 15 Jan. 2017, https://go-dh.github.io/mincomp/thoughts/2017/01/15/mincomp-libraries-intro/.
  • Visconti, Amanda, et al. “Running a Collaborative Research Website and Blog with Jekyll and GitHub.” Programming Historian, Nov. 2020. programminghistorian.org, https://programminghistorian.org/en/lessons/collaborative-blog-with-jekyll-github.
  • Walsh, Brandon. The Programming Historian and Editorial Process in Digital Publishing · Brandon Walsh. http://walshbr.com/blog/the-programming-historian-and-editorial-process-in-digital-publishing/. Accessed 16 Mar. 2021.
  • “What Is a Static Site Generator? How Do I Find the Best One to Use?” Netlify, https://www.netlify.com/blog/2020/04/14/what-is-a-static-site-generator-and-3-ways-to-find-the-best-one/?utm_source=jamstackorg&utm_medium=what-are-ssg-pnh&utm_campaign=devex. Accessed 16 Mar. 2021.
  • “Why Static Site Generators Are The Next Big Thing.” Smashing Magazine, https://www.smashingmagazine.com/2015/11/modern-static-website-generators-next-big-thing/.
  • Wikle, Olivia. “What Is Static Web and What’s It Doing in the Digital Humanities Classroom?” Dh Lib, 22 June 2020, https://dhandlib.org/2020/06/22/what-is-static-web-and-whats-it-doing-in-the-digital-humanities-classroom/.