Article version: GitHub.com

Page build failed: Relative permalinks configured

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.

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

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

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.

  1. On GitHub, 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. You can attribute the commit to more than one author in the commit message. For more information, see "Creating a commit with multiple co-authors."

    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

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

Ask a human

Can't find what you're looking for?

Contact us