Використання SASS файлів з Ruby Gems у Jekyll

Це було спочатку опубліковано на моєму особистому блозі (який тоді був на базі Jekyll) до того, як його перенесли на Medium.

TL;DR — Джерела для плагіна jekyll-gem-resolver можна знайти на моєму GitHub.

Попередня версія цього блогу, а також мої інші статичні сайти, були створені з використанням Jekyll. Це чудовий інструмент, і з ним дуже легко працювати, тому що він бере на себе всі пов’язані етапи збірки, такі як компіляція ваших SCSS-джерел у CSS. Під час рефакторингу я захотів перейти від використання попередньо зібраної версії Bootstrap CSS фреймворку до створення його з вихідних файлів SCSS.

Це включає три етапи (як описано в документації Bootstrap):

1. Отримати файли SCSS для Bootstrap
2. Перетворити файли SCSS в чистий CSS
3. Перетворити отримані файли CSS за допомогою Autoprefixer, щоб додати префікси для постачальників

Як: побудувати Bootstrap з вихідних файлів за допомогою Jekyll

Як описано в цьому блозі, це досить просто:

1. Скопіюйте всі файли SCSS з Bootstrap у ваш репозиторій.
2. Використовуйте плагін jekyll-sass-converter. Оскільки він вже за замовчуванням вбудований у Jekyll, нам не потрібно робити нічого особливого.
3. Використовуйте плагін jekyll-autoprefixer для додавання префіксів CSS для постачальників.

Що ж... це добре, окрім першого етапу “Скопіюйте всі файли SCSS з Bootstrap”. Хіба для цього не існують менеджери пакетів? Вже є офіційний bootstrap rubygem, тому було б краще використати саме його.
Просто додайте це до нашого Gemfile, і вкажіть у _config.yml:

# Gemfile  
gem "bootstrap", "~> 5.3.2"

# _config.yml  
sass:  
 load_paths:  
 - ???

... але як саме вказати bootstrap gem у вашому _config.yml?

Виявляється, що Jekyll не має вбудованої можливості для безпосереднього посилання на файли з Gems, тому я просто написав маленький плагін для Jekyll, який дозволяє мені це робити:

# _config.yml  
sass:  
 load_paths:  
 - 'gem:bootstrap/assets/stylesheets'  

gem_resolver:  
 transform: # Вказуємо, де можуть бути знайдені посилання на gems   
 - sass.load_paths

Замість того, щоб просто перетворювати кожен рядок, що починається з gem: у конфігурації (що може мати непередбачувані побічні ефекти) або жорстко вказувати шляхи для пошуку посилань на gems (що погано працює з додатковими плагінами), я зробив частини конфігурації, де замінюються посилання на gems, повністю налаштовуваними.

Повна конфігурація

Увага: зафіксуйте execjs на версії 2.7.0 для уникнення помилок під час виконання
Хоча це не пов'язано з моїм плагіном, а з jekyll-autoprefixer, сподіваюся, що це заощадить деяким людям головний біль, з яким я зіткнувся:

Через помилку в ExecJS (яка використовується внутрішньо в jekyll-autoprefixer/autoprefixer-rails для виконання autoprefixer), потрібно явно примусово встановити gem ExecJS на останню версію, що не вплинута помилкою, а саме на версію 2.7.0, щоб уникнути деяких плутаних помилок виконання:

# Gemfile  
# Потрібно для уникнення помилок виконання в jekyll-autoprefixer, спричинених ExecJS 2.8.0 і пізнішими  
gem "execjs", "= 2.7.0"

Моя вся конфігурація (окрім зовсім не пов'язаних частин) для побудови Bootstrap з bootstrap rubygem, включаючи Autoprefixer, виглядає тепер так:

# _config.yml  
plugins:  
 - jekyll-gem-resolver  
 - jekyll-autoprefixer  

sass:  
 load_paths:  
 - 'gem:bootstrap/assets/stylesheets'  

gem_resolver:  
 transform:  
 - sass.load_paths

Окрім bootstrap gem, також потрібно вказати jekyll-gem-resolver і jekyll-autoprefixer gems у вашому Gemfile:

# 📄 Gemfile  
source "https://rubygems.org"  

gem "jekyll", "~> 4.3.3"  

# Отримуємо bootstrap для використання його SASS джерел  
gem "bootstrap", "~> 5.3.2"  

# Якщо у вас є плагіни, розміщуйте їх тут!  
group :jekyll_plugins do  
 gem "jekyll-gem-resolver", "~> 1.1.1"  
 gem "jekyll-autoprefixer", "~> 1.0"  
end  

# Потрібно для уникнення помилок виконання в jekyll-autoprefixer, спричинених ExecJS 2.8.0 і пізнішими  
gem "execjs", "= 2.7.0"  

# Решта цього файлу - це просто за замовчуванням Jekyll:  
# Windows та JRuby не включають zoneinfo файли, тому включаємо gem tzinfo-data  
platforms :mingw, :x64_mingw, :mswin, :jruby do  
 gem "tzinfo", ">= 1", "< 3"  
 gem "tzinfo-data"  
end  

# Для підвищення продуктивності при спостереженні за каталогами на Windows  
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]  

# Блокуємо gem `http_parser.rb` на `v0.6.x` на збірках JRuby, оскільки новіші версії не мають Java-еквівалента  
gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

Імпорт файлів з Bootstrap gem виглядає як будь-який інший SCSS код:

// assets/css/default.scss  
// ...  
@import "bootstrap";  
// ...

Чудово!

Висновки

Я опублікував плагін на GitHub і RubyGems. Ви можете знайти документацію та вихідний код плагіна тут.

Перекладено з: Using SASS Files from Ruby Gems with Jekyll