Covered in this doc
How to integrate Percy into a Jeykll static site
Node 10.0.0 or higher
PERCY_TOKEN. Your token can be found on your Percy project settings page
The first step is to make your
PERCY_TOKEN available in your environment. The
percy package relies on the
PERCY_TOKEN environment variable for authenticating and authorizing access to each project.
On Linux and Mac, run:
$ export PERCY_TOKEN=aaabbbcccdddeeefff
On Windows, run:
$ set PERCY_TOKEN=aaabbbcccdddeeefff
PERCY_TOKENsecret. Anyone with access to your token can consume your account quota, though they cannot read data.
Before your site can be visually tested with Percy, you must build your Jekyll site. If you're using the defaults provided by Jeykll, your built site is output into a
$ bundle exec jekyll build
To take snapshots of the built site, simply run:
$ npx percy snapshot _site/
And that's it! Percy will create a build and snapshot by default all of the HTML files inside
$ npx percy snapshot _site/ Creating build... percy has started. serving static site at http://localhost:5339/ snapshot taken: 'http://localhost:5339/index.html' snapshot taken: 'http://localhost:5339/404.html' snapshot taken: 'http://localhost:5339/contact.html' shutting down static site at http://localhost:5339/ stopping percy... done! finalized build...
You can do the above steps locally for testing, but to get continuous visual integration for your static site you’ll need to run the
npx percy snapshot _site/ command in CI.
You'll also want to make sure your
PERCY_TOKEN is setup for that run. See the CI setup guides for how to securely set environment variables in your CI service.
An example CircleCI
.circleci/config.yml file might look something like the config below. We have added a few comments throughout the file to explain:
version: 2.1 jobs: test: docker: - image: circleci/ruby:2.6.3-node-browsers # Make sure your image has both `node` and is able to launch a browser steps: - checkout - run: name: Install dependencies command: bundle install - run: name: Build the static site command: bundle exec jekyll build - run: name: Visual Tests command: npx percy snapshot _site # snapshot built Jekyll site workflows: version: 2.1 build_and_test: jobs: - test
Changing the base url
Jeykll allows you to set the path your built site becomes hosted at by configuring a
baseurl option in the
If you have configured a
baseurl, you will want to also pass that as a command line option to the
snapshot command. For example, if your site outputs to
_site and your
baseurl is set to
blog, you'll pass the
--base-url /blog flag.
$ npx percy snapshot _site/ --base-url /blog
You may want to exclude a section of your website from being visually tested. You can configure this with the
For example, let's say you want to snapshot everything on your website except draft blog posts. You can do so like this:
$ npx percy snapshot _site/ --ignore-files blog/drafts/**
A reference integration of Percy and Jeykll is available.
Updated almost 3 years ago