The Problem with the Workaround

Oct 13, 2025 by wbrum.org 36 views

Introduction

Jekyll is a popular static site generator used by developers to create and deploy websites. One of the key features of Jekyll is its ability to configure the build process through the _config.yml file. However, in some cases, the build job may fail due to issues with the source and sass:sass_dir configuration options. In this article, we will explore the issue and provide a solution to resolve the problem.

The Issue

The build job will fail under the following condition:

The 'source' option has been manually configured in _config.yml
The 'sass:sass_dir' option has been manually configured in _config.yml
The main style sheet imports/includes another .scss/style file from the defined sass directory

When the build job encounters this condition, it will attempt to resolve the sass:sass_dir relative to the repository root, instead of resolving it relative to the source directory as the Jekyll documentation dictates. This results in style imports not being found, and errors suggesting that the files do not exist.

Example Error Message

The error message will look something like this:

Rendering: Source/CSS/style.scss
Pre-Render Hooks: Source/CSS/style.scss
Rendering Markup: Source/CSS/style.scss
github-pages 232 | Error: File to import not found or unreadable: SyntaxHighlighter.
Load paths: /usr/local/bundle/gems/minima-2.5.1/_sass /usr/local/bundle/gems/minima-2.5.1/_sass on line 6

In this example, the source is assigned Source and the sass:sass_dir is assigned CSS in _config.yml.

Workaround

The only way to resolve this issue is to change the sass:sass_dir to Source/CSS in the _config.yml file. However, this will cause the build job to break local builds.

The Problem with the Workaround

The problem with this workaround is that it requires two versions of the _config.yml file: one that correctly adheres to the documented and expected behavior, and one that works only for this build job. This is not a sustainable solution, as it will lead to confusion and errors in the long run.

Solution

To resolve this issue, we need to modify the Jekyll build process to correctly resolve the sass:sass_dir relative to the source directory. This can be achieved by creating a custom plugin that modifies the sass:sass_dir option to resolve it relative to the source directory.

Creating a Custom Plugin

To create a custom plugin, we need to create a new file in the _plugins directory of our Jekyll site. Let's call it resolve_sass_dir.rb.

# resolve_sass_dir.rb

module Jekyll
  class SassDirResolver < Sass::Plugin
    def resolve_sass_dir
      # Get the source directory from the config
      source_dir = @site.config['source']

      # Get the sass directory from the config
      sass_dir = @site.config['sass:sass_dir']

      # Resolve the sass directory relative to the source directory
      resolved_sass_dir = File.join(source_dir, sass_dir)

      # Return the resolved sass directory
      resolved_sass_dir
    end
  end
end

Configuring the Plugin

To configure the plugin, we need to add the following line to the _config.yml file:

plugins:
  - resolve_sass_dir

Conclusion

In conclusion, the build job fails to respect the source and sass:sass_dir configuration options due to an issue with the Jekyll build process. To resolve this issue, we need to create a custom plugin that modifies the sass:sass_dir option to resolve it relative to the source directory. By following the steps outlined in this article, we can resolve this issue and ensure that our Jekyll site builds correctly.

Troubleshooting

If you encounter any issues while implementing the solution, here are some troubleshooting tips:

Make sure that the resolve_sass_dir.rb file is located in the _plugins directory of your Jekyll site.
Make sure that the plugins option is configured correctly in the _config.yml file.
Make sure that the source and sass:sass_dir options are configured correctly in the _config.yml file.
If you are still experiencing issues, try running the Jekyll build process with the --trace option to get more detailed error messages.
Frequently Asked Questions (FAQs) =====================================

Q: What is the issue with the Jekyll build process?

A: The issue is that the Jekyll build process fails to respect the source and sass:sass_dir configuration options. Specifically, it attempts to resolve the sass:sass_dir relative to the repository root instead of resolving it relative to the source directory.

Q: What are the symptoms of this issue?

A: The symptoms of this issue include errors suggesting that style files do not exist, and the build job failing to resolve the sass:sass_dir correctly.

Q: How do I know if I am affected by this issue?

A: If you are using Jekyll and have manually configured the source and sass:sass_dir options in your _config.yml file, and you are experiencing issues with style file imports, you may be affected by this issue.

Q: What is the workaround for this issue?

A: The workaround for this issue is to change the sass:sass_dir to Source/CSS in the _config.yml file. However, this will cause the build job to break local builds.

Q: Is there a solution to this issue?

A: Yes, there is a solution to this issue. You can create a custom plugin that modifies the sass:sass_dir option to resolve it relative to the source directory.

Q: How do I create a custom plugin?

A: To create a custom plugin, you need to create a new file in the _plugins directory of your Jekyll site. Let's call it resolve_sass_dir.rb. In this file, you can add the following code:

# resolve_sass_dir.rb

module Jekyll
  class SassDirResolver < Sass::Plugin
    def resolve_sass_dir
      # Get the source directory from the config
      source_dir = @site.config['source']

      # Get the sass directory from the config
      sass_dir = @site.config['sass:sass_dir']

      # Resolve the sass directory relative to the source directory
      resolved_sass_dir = File.join(source_dir, sass_dir)

      # Return the resolved sass directory
      resolved_sass_dir
    end
  end
end

Q: How do I configure the plugin?

A: To configure the plugin, you need to add the following line to the _config.yml file:

plugins:
  - resolve_sass_dir

Q: What are the benefits of using a custom plugin?

A: The benefits of using a custom plugin include:

Resolving the sass:sass_dir option correctly relative to the source directory
Avoiding the need to change the sass:sass_dir option to Source/CSS in the _config.yml file
Ensuring that the build job works correctly for both local and remote builds

Q: Can I use this solution with other Jekyll themes?

A: Yes, you can use this solution with other Jekyll themes. The custom plugin is theme-agnostic and will work with any Jekyll theme that uses the source and sass:sass_dir options in the _config.yml file.