If you have relative permalinks set up in your _config.yml file, then you should receive a page build failure advising you to remove the relative_permalink option from your _config.yml file and replace any relative permalinks in your site with absolute permalinks.

If your GitHub Pages site is configured for relative permalinks in your _config.yml file, then you'll get an email that looks like this:

Subject: Page build failed

The page build failed with the following error:

Your site is using the relative_permalinks configuration option. This

setting is deprecated as has been removed from the latest version of

Jekyll. To ensure your site continues to build as expected, remove the

option from your site's configuration and update any post or page

permalinks to be absolute to the site root, not the parent folder.

Understanding relative and absolute permalinks

Permalinks are permanent URLs that reference a particular post or page on your GitHub Pages site.

  • Absolute permalinks are URLs that begin with the root of the site.
  • Relative permalinks are modified URLs that begin with parent folder (the folder containing the referenced webpage) instead of the root of the site.

For more information, see Jekyll's official documentation on permalinks.

Troubleshooting relative permalink errors

GitHub Pages and Jekyll no longer support relative permalinks. You must remove the relative_permalinks configuration option from your GitHub Pages site's _config.yml file and reformat any relative permalinks in your site to absolute permalinks.

Removing relative_permalinks: from config.yml

  1. On GitHub Enterprise, navigate to the main page of the repository.

  2. In your repository, browse to _config.yml.

  3. In the upper right corner of the file view, click to open the file editor. open file editor with edit icon
  4. Find the line that starts with relative_permalinks: and delete the whole line. relative-permalinks-value in config.yml

  5. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file. Commit message for your change

  6. Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. If your current branch is master, you should choose to create a new branch for your commit and then create a pull request. Commit branch options

  7. Click Propose file change. Propose file change button

Replacing relative permalinks with absolute permalinks

  1. Search your site's posts or pages for relative permalinks.
  2. Replace any relative permalinks with absolute permalinks.