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.
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:
- 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.
- 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.
- 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).
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:
Or directly from your terminal using the Tugboat Command Line Interface (CLI):
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.
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.
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.
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.
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.