Testing your blog may sound like an odd thing to do, but if you’re running a Jekyll blog hosted on GitHub it is simple to set up and really useful for notifying you about broken links and other issues.
Things you should test
You should check for good practice items in your article which you might forget to do. Things like including alt tags for your images or making sure your links actually go somewhere. These are the kind of things you leave blank while writing and think “I’ll fill that in later” and then never do so.
There are also things which may break over time without you realising. This is mainly external urls and image links which may have changed and no longer exist.
Finally you should ensure your html complies to standards. This is more to do with the Jekyll theme rather than the articles you’re writing but you always want to ensure your website is going to display correctly for everyone.
This is where Travis CI comes in. Travis CI is a continuous integration platform which watches for you to commit code to your GitHub repository and then runs your code on an external server to test and even deploy it for you.
You tell Jekyll what to do with your code by including a YAML file in your repository
.travis.yml. We will be specifying ruby as the language which will cause Travis
to ensure ruby is installed and will automatically install any gems you specify in
a file called
Gemfile is basically a set of dependencies for your application, if you haven’t got one
in your Jekyll blog repository you’ll want to create one with the following content.
source 'https://rubygems.org' gem 'github-pages' gem 'html-proofer'
This tells Travis to use bundler to install the GitHub pages dependencies which include Jekyll and also a tool called HTML Proofer which we will use to test our blog.
So once Travis has ensured ruby is installed to the version we want and the gems are installed
we then need to specify what commands we want it to run. We want it to build our Jekyll
site and then run HTML proofer, to do this your
.travis.yml will want to look
something like this.
language: ruby rvm: - 2.1 script: - bundle exec jekyll build - bundle exec htmlproofer ./_site --only-4xx --check-favicon --check-html env: global: - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
This will build your site into
_site on the Travis server and then run HTML Proofer
on the generated HTML.
HTML proofer will by default follow all of the links in your website and ensure that the destination exists. It will ensure all the referenced images exist and also check whether you have specified alt tags for those images.
It also has some optional extended functionality which I have enabled in my tests.
The first is
--only-4xx. This tells HTML Proofer to only throw an error when it
hits an error message in the 400-499 range. This means it ignores errors like 500 or 503
on external urls which are usually temporary issues and down to the external service
to resolve, we don’t want things which are out of our control to fail our build.
--check-favicon. This does exactly what it says on the tin, it ensures
you have correct favicons configured for your site.
--check-html. This uses Nokogiri to check that your HTML is well formed.
It will throw errors when you do things like not closing divs correctly or double
declaring attributes. As I said before this is down to your theme rather than
your content but you still want to test it.
Setting this up means that whenever you commit to your Jekyll blog it will test you code and make sure it is correct, if it isn’t it will send you an email saying that the build has failed and will allow you to see the output of HTML Proofer so that you can fix the problem.
It will also do this when someone (or you) submits a pull request. Travis will see the pull request, test the code and then advise within the pull request window whether it is safe to merge.
So if the build fails you will get a message like this:
Or if it succeeds you get given the go ahead to merge:
If you’re following a GitHub workflow using pull requests this can be a great way to make sure that everything which goes into the master branch is already tested.
This is just one simple way of testing your blog. If you wanted to take it further you could get Travis to install additional tools and scripts for checking spelling and grammar, ensuring your images are hosted on a CDN or even making sure you don’t have any emoji in your article.
If you don’t want to host your website on GitHub Pages you can also get Travis
to deploy your
_site to another server such as a VPS or maybe an Amazon S3 Bucket.