Screenshot of a MKDocs static site preview with the Tugboat preview URL circled

Static site generators such as Jekyll, Hugo, and MkDocs, are great tools for quickly generating minimal-infrastructure websites. Many of the popular static site generators have great community support, and offer a wide variety of themes and advanced customization options. One drawback of static site generators, though, is that before pushing updates live to production, changes are only visible in local development environments. The ability to see a working preview of your site, that is decoupled from your local dev environment, is a great tool for collaborating, code review, testing changes, and debugging.

The challenges

Collaborating pre-production requires a local development environment

The biggest challenge of making updates to a static site generator website is that reviewing changes, code review, and testing infrastructure changes all require a local development environment. If you’re collaborating with other folks, this means would-be site viewers must pull down your changes from the source control provider, typically a git service such as GitHub, GitLab, or Bitbucket, and then view those changes locally. Unfortunately, this review process alienates a variety of stakeholders.

This makes effective collaboration with “less technical” stakeholders difficult, as a product manager or member of leadership may be unable or unwilling to set up a local environment to view changes to the static site. Even other developers who have access to the git repository and are comfortable pulling down changes and viewing them locally may delay doing it, as they might not want to disrupt their own work on their local dev environment.

Even non-technical changes require a local dev environment

What if you want to change the text on a static site generator page, and need a product team or management stakeholder to review? Even a simple non-technical change requires a local dev environment, which many collaborators may lack. Want to share a design update with a UX/UI team? You can send them a screenshot or do a demo where a dev with a local environment “drives,” but that doesn’t give these users the ability to click around and verify the changes work as expected. Removing the collaboration barrier for non-technical changes is key to faster and more effective development when working with any stakeholder.

Code review and testing requires a local development environment

If you’re a developer asking other developers to review code changes to your static site generator website, that requires the other devs to also have a local dev environment set up for the project. If you request a code review at the end of the day, and the reviewer starts out the next day ready to work on their own task, what happens? They’re likely to do their own work before updating their local with your code to review and test your changes. That means a day lost on your own work. Over the life of the project, these delays add up, resulting in slow delivery times, potentially missed deadlines, and deteriorating relationships with stakeholders both within and outside of the team.

Debugging can get thorny with only a local development environment

“Can’t reproduce the bug” is a common issue for devs debugging on a local development environment. There are a ton of reasons why having only a local environment for debugging is sub-optimal, but many of them are related to having a local that doesn’t exactly match production. Alternately, if you’re collaborating with other devs to debug a tricky problem, the most common way of tackling this is to pair and have one of you “drive” - but that may not be the fastest or most effective way to find and debug an issue. Giving multiple devs access to a shared environment that matches production simplifies debugging.

The solution: production-like environments for your changes

The common theme in the challenges above is the constraint of working with only a local development environment. The solution, then, is to have a production-like environment where you can review, debug, and share your changes. The nice thing about something like Tugboat, which builds a new deploy preview for every pull request, is that you can have many of these environments at the same time, so you’re not constrained by a limited number of staging or QA servers, and you don’t have to worry about whether another PR has been reviewed before your changes can get loaded for review.

How to configure Tugboat to build working website previews for your static site generators

Set up Tugboat to create working previews of Jekyll, Hugo, MkDocs or other static sites

Here’s how to get working website previews for your static site generator using Tugboat:

  1. Sign up for a Tugboat account; Tugboat’s free account provides enough storage and resources to build multiple Previews from an average static site generator setup.
  2. Create a project in Tugboat for your static site generator builds, and link Tugboat to the git repository where your static site builder code is stored.
  3. Add a Tugboat config.yml to your repository (our documentation site offers starter configs for several popular static site builders, or ask in Tugboat’s Support Slack if you need help setting one up for your flavor of SSG).

Build Previews

With those pieces in place, there are a couple of ways for Tugboat to build working Previews of your static site generator website:

  • Build branches, tags, or pull requests manually within Tugboat
  • Automatically build Previews for every pull request

Build branches, tags, or pull requests manually within Tugboat

You can manually trigger a build from branches, tags, or pull requests any time. You can do this from the Tugboat UI:

The Build Preview button on a branch in Tugboat

Or directly from your terminal using the Tugboat Command Line Interface (CLI):

Tugboat command to build a Preview within a terminal window

Automatically build Previews for every pull request

You can also configure Tugboat to automatically build a preview of your static site generator website for every new pull request, and automatically delete previews when pull requests are merged. To do this, you’ll need to connect Tugboat to GitHub, GitLab, or Bitbucket via the optional integrations. Then, whenever a new pull request is made to the linked repository, Tugboat will build a preview from the PR - and delete it once the Preview is merged. Tugboat will also rebuild previews automatically when a pull request is updated.

Tugboat's Repository Settings screen with options selected to build, update, and delete pull requests automatically

Share Previews

Once the Previews are built, you can share those Previews in few different ways:

  • Manually share a Preview URL with anyone
  • Configure Tugboat to set a pull request deployment status on the pull request
  • Configure Tugboat to post a Preview link as a comment on the pull request

Manually share a website preview with anyone

If you want to share a website preview with a stakeholder, the design team, the community, or even another developer, you can manually share the website preview URL. The recipient can then click the link, and they’re taken to a fully functional preview of your website. The person viewing your site can be anyone; they don’t need to have a local development environment to view your commits, and they don’t need access to the git repository where your code is stored.

Screenshot of a MKDocs static site preview with the Tugboat preview URL circled

Share your website preview as a deploy environment on the pull request

With this setting enabled, Tugboat can post an environment deployment on your pull request. In GitHub, for example, this displays as a View deployment button on your pull request.

Screenshot of a GitHub Pull Request with an arrow pointing to the View deployment button

Anyone with access to the pull request can click this button and view your website preview.

Post a website preview link as a comment on the pull request

The other option to share your working website previews is to configure Tugboat to post a comment on your pull request. The comment contains a link to the website preview, as well as a link to the Tugboat dashboard, where a user with appropriate Tugboat permissions could clone the preview, rebuild or refresh it, or delete it.

Screenshot of a GitHub Pull Request Comment with links to a Tugboat preview and the Tugboat dashboard

Try out working website previews for your static site generator pull requests

With a free tier capable of building multiple previews for most static site generator websites, trying out Tugboat in your website development workflow is a low-risk way to explore how this process can improve your work. Collaborate more easily with stakeholders, developers, design teams, or the community at large, and remove one of the barriers of working with static site generator websites.