How to Check for Broken Links in Jekyll

Search engines will dock you points (or give you bad points, however you see it) if you have links on your site pointing internally or externally to broken links.

So for the next few hours, please check every link on each of your sites….

Now that’s a waste of time.

Instead, let’s use jekyll’s (or rather Ruby’s) ability to just do it on it’s own. Namely, we are going to use a module called html-proofer to check the links for us.

Note: There is a way to have Travis do this for us. But I am just going to run it normally.

Let’s install html-proofer. You can do it however you want, but to do so using bundle, add this to your Gemfile:

gem 'rake'
gem 'html-proofer'

Now bundle up with bundle install.

And now that it’s installed, build your site and have htmlproofer check for the broken links:

bundle exec jekyll build
bundle exec htmlproofer ./_site

The first command builds the site, and the second runs the html-proofer against the site files.

And you’ll get something like this:

Running ["ImageCheck", "LinkCheck", "ScriptCheck"] on ["./_site"] on *.html...

Checking 23 external links...
Ran on 69 files!

- ./_site/create-self-extracting-running-archive/index.html
  *  internally linking to /create-your-own-repeater/, which does not exist (line 202)
- ./_site/digitalocean-manage-vps/index.html
  *  internally linking to /create-self-extracting-and-running-archive/, which does not exist (line 424)
  *  internally linking to /create-your-own-repeater/, which does not exist (line 54)
...
- ./_site/setup-jekyll-sitemap/index.html
  *  internally linking to /path-to-main-jekyll-post-or-category, which does not exist (line 198)
- ./_site/systems/network/create-your-own-repeater/index.html
  *  linking to /categories/#network, but network does not exist (line 523)
  *  linking to /categories/#systems, but systems does not exist (line 527)
- ./_site/tags.html
  *  {{ base_path }}{{ tag_word | slugify | prepend: path_type | prepend: site.tag_archive.path }} is an invalid URL (line 24)
- ./_site/vpn/setup-openvpn-easyrsa3/index.html
  *  External link broken-site.whatever failed: 404 No error
- ./_site/wptool/index.html
  *  linking to internal hash # that does not exist (line 1010)
htmlproofer 3.0.6 | Error:  HTML-Proofer found 21 failures!

As you can see, I had been moving things around to get my site just right, and there were a few things that needed to be corrected. But it worked out in the end, as I saw the errors and was able to correct them!

Hurray for simplicity!

Checking before it’s Published

If you want to check the site before it’s published, you can. First, here’s my _config.localhost.yml file:

url:                     "http://localhost:4000"

# Analytics
analytics:
  provider               : false
  google:
    tracking_id          :

sass:
  sass_dir: _sass
  style: expanded

And then use the following commands to first build the site, then serve it (in the background), and finally to check the links against the running server:

echo "Building site."
bundle exec jekyll build --config "_config.yml,_config.localhost.yml"
echo "Serving files"
bundle exec jekyll server --config "_config.yml,_config.localhost.yml" --skip-initial-build >/dev/null 2>&1 &
bundle exec htmlproofer --allow-hash-href ./_site
killall bundle

It’s kinda hackish, but it does the job.

Hrefs

You’ll notice the --allow-hash-href option which hides errors like

- ./_site/index.html
  *  linking to internal hash # that does not exist (line 421)
     <a href="#" class="disabled"><span aria-hidden="true">Previous</span></a>
  *  linking to internal hash # that does not exist (line 426)
     <a href="#" class="disabled current">1</a>
- ./_site/jekyll-check-for-broken-links/index.html
  *  linking to internal hash # that does not exist (line 473)
     <a href="#" class="pagination--pager disabled">Next</a>

Checking before it’s Published#

Hrefs#

Checking before it’s Published

Hrefs