GitHub Pages’te Jekyll teması kullanırken eklenti ve sürüm sınırı

GitHub Pages’e bir Jekyll sitesi gönderdiğinizde, ayrı bir iş akışı kurmadıysanız siteyi GitHub kendi ortamında derler. Bu ortam iki şeyi sabitler: Jekyll sürümünü ve kullanılabilecek eklentileri. 20 Ekim 2026’da github/pages-gem deposunda Jekyll sürümü 3.10.0, izin verilen eklenti sayısı ise 20 olarak yazıyordu. Jekyll’ın kendisi ise o gün RubyGems’te 4.4.1 sürümündeydi. Bir temanın GitHub Pages’te sorunsuz çalışıp çalışmayacağını bu iki rakam belirler.

Klasik derleme ne yapar, ne yapmaz

GitHub’ın Jekyll belgesine göre bazı eklentiler varsayılan olarak açıktır ve kapatılamaz: jekyll-coffeescript, jekyll-default-layout, jekyll-gist, jekyll-github-metadata, jekyll-optional-front-matter, jekyll-paginate, jekyll-readme-index, jekyll-titles-from-headings ve jekyll-relative-links. Bunlara ek olarak, desteklenen listedeki eklentileri _config.yml dosyasındaki plugins ayarına ekleyerek açabilirsiniz.

İzin listesi, pages-gem deposundaki plugins.rb dosyasında tutulur. 20 Ekim 2026’da listede şunlar vardı: jekyll-coffeescript, jekyll-commonmark-ghpages, jekyll-feed, jekyll-gist, jekyll-github-metadata, jekyll-paginate, jekyll-redirect-from, jekyll-seo-tag, jekyll-sitemap, jekyll-avatar, jemoji, jekyll-mentions, jekyll-relative-links, jekyll-optional-front-matter, jekyll-readme-index, jekyll-default-layout, jekyll-titles-from-headings, jekyll-include-cache, jekyll-octicons ve jekyll-remote-theme.

Belgenin kritik cümlesi şu: GitHub Pages, desteklenmeyen eklenti kullanan siteleri derleyemez. Bu durumda siteyi yerelde derleyip oluşan statik dosyaları göndermeniz ya da derlemeyi kendi GitHub Actions iş akışınıza taşımanız gerekir.

Ölçümümüzde Jekyll temaları

İzlediğimiz 60 Jekyll temasından _config.yml dosyasını okuyabildiğimiz 59 temanın 13 tanesi izin listesinin dışında en az bir eklenti istiyordu. Bu temalarda en sık görülen izinsiz eklentiler: jekyll-archives, jekyll-email-protect ve jekyll-spaceship (her biri iki temada). Ayrıca 8 tema Gemfile’da Jekyll 4 sürümünü istiyordu; bu temalar GitHub Pages’in Jekyll 3.10.0 ortamında farklı davranabilir ya da hiç derlenmeyebilir.

Her temanın durumunu Jekyll temaları sayfasındaki “github pages uyumu” panelinde ve tema sayfasındaki teknik kontrol listesinde görebilirsiniz. Liste, _config.yml içindeki plugins (ve eski sürümlerdeki gems) satırlarını izin listesiyle karşılaştırarak üretilir.

Bu kontrolün bir sınırı var: bazı temalar eklentileri _config.yml yerine yalnızca Gemfile’daki jekyll_plugins grubunda tanımlar. Bu durumda izinsiz eklenti bizim kontrolümüzde görünmez. Temanın README’sinde “GitHub Pages’te çalışmaz” ya da “GitHub Actions ile derleyin” gibi bir not varsa ona güvenin.

Gemfile’da github-pages gem’i olan temalar

Bir Jekyll temasının GitHub Pages için yazılıp yazılmadığını anlamanın kısa yolu Gemfile’a bakmaktır. Gemfile’da github-pages gem’i varsa, yerel derleme GitHub Pages’teki sürümlerle aynı Jekyll’ı ve eklentileri kullanır; yerelde gördüğünüz, yayında göreceğinizdir. İzlediğimiz 60 temadan 14 tanesinin Gemfile’ında bu gem vardı. Gemfile’da doğrudan jekyll sürümü yazan temalar ise kendi sürümlerini seçmiştir; bunların 8 tanesi Jekyll 4 istiyordu.

Temaların 30 tanesi kökte bir .gemspec dosyası taşıyordu, yani RubyGems’e gem olarak paketlenmeye hazırdı. Gem tabanlı bir tema Gemfile’a eklenip theme: satırıyla kullanılır; GitHub Pages’te ise desteklenen listede değilse remote_theme gerekir. Gemspec’i olmayan temalar çoğunlukla depoyu doğrudan kopyalayarak ya da çatallayarak kullanılmak üzere tasarlanmıştır.

Desteklenen temalar ve remote_theme

GitHub’ın tema belgesi, kutudan çıktığı hâliyle desteklenen temaları listeler. pages-gem deposundaki tema listesinde 20 Ekim 2026’da 15 kayıt vardı: minima, jekyll-swiss ve jekyll-theme- ile başlayan on üç tema (primer, cayman, minimal, slate gibi). Bu listedeki bir temayı _config.yml’de theme: satırıyla kullanırsınız.

GitHub’da yayımlanmış başka herhangi bir Jekyll teması için belge remote_theme: ayarını gösterir ve jekyll-remote-theme eklentisinin bu iş için mevcut olduğunu söyler. Eklentinin README’si sözdizimini ayrıntılı verir:

remote_theme: kullanici/tema
remote_theme: kullanici/[email protected]
remote_theme: kullanici/tema@latest
plugins:
  - jekyll-remote-theme

@v1.0.0 gibi bir etiket, temayı belirli bir sürüme sabitler. @latest en son yayımlanan sürümü alır; README’ye göre deponun hiç sürümü (release) yoksa HEAD’e, yani ana daldaki son duruma düşer. Etiket yazmamak da ana dalı izlemek demektir. Bir yıl sonra temanın ana dalında yapılan bir değişikliğin sitenizi bozmasını istemiyorsanız sürüm etiketi kullanın.

README iki sınırlamayı da yazar: uzak tema herkese açık bir GitHub deposunda olmalıdır ve uzak temayı kullanmak için temanın RubyGems’e yüklenmesi ya da .gemspec dosyası taşıması gerekmez. Yerel klasör yolu ise GitHub Pages’in güvenli modunda desteklenmez.

Önemli nokta: remote_theme temanın dosyalarını getirir, temanın eklentilerini değil. Tema izin listesi dışında bir eklentiye dayanıyorsa, uzak tema olarak eklemek bu sorunu çözmez.

Özel iş akışına geçince ne değişir

Kendi GitHub Actions iş akışınızla derlemeye geçtiğinizde iki kısıt birden kalkar: istediğiniz Jekyll sürümünü (ör. 4.4.1) ve istediğiniz eklentiyi kullanabilirsiniz. Karşılığında birkaç sorumluluk size geçer. Ruby sürümünü iş akışında yazmanız, Gemfile.lock dosyasını depoda tutmanız ve derlemenin başarısız olduğu durumları kendiniz takip etmeniz gerekir. Klasik derlemedeki varsayılan eklentiler (ör. jekyll-optional-front-matter, jekyll-titles-from-headings) de artık kendiliğinden açık olmaz; siteniz bu eklentilerin davranışına alıştıysa, ön bilgisi (front matter) olmayan Markdown dosyaları ya da başlıktan türetilen sayfa adları farklı görünebilir. Bu eklentileri Gemfile’a ve _config.yml dosyasına açıkça ekleyerek eski davranışı geri alabilirsiniz.

Temayı kendi dosyalarınızla değiştirmek

Jekyll belgeleri, gem tabanlı bir temada bir düzeni (layout) ya da include dosyasını değiştirmek için o dosyanın bir kopyasını kendi sitenizin _layouts ya da _includes klasörüne koymanızı söyler; Jekyll önce sitenizin içeriğine, sonra temanın varsayılanlarına bakar. Uzak temalarda da aynı mantık işler; eklentinin README’sine göre yalnızca geçersiz kıldığınız dosyalar sizin sürümünüzü kullanır.

Gem olarak kurulmuş bir temanın dosyalarını görmek için belge bundle info --path komutunu ve ardından temanın gem adını önerir (ör. bundle info --path minima). Değiştirmek istediğiniz dosyayı buradan bulup aynı göreli yolla sitenize kopyalayın.

Stil dosyalarında bir incelik var: belgeye göre bir Sass parçasını değiştirmek istediğinizde temanın ana Sass dosyasını da kopyalamanız gerekebilir; örneğin minima için _sass/minima.scss.

Karar şeması

1. Tema pages-gem listesindeki temalardan biri mi? Evet ise theme: ile kullanın, klasik derleme yeterli.
2. Değilse, _config.yml’deki eklentilerin hepsi izin listesinde mi? Evet ise remote_theme: ile kullanın ve bir sürüm etiketi seçin.
3. Gemfile Jekyll 4 istiyor ya da izin listesi dışında eklenti var mı? Evet ise klasik derlemeyi bırakın; siteyi kendi GitHub Actions iş akışınızla derleyin. GitHub’ın “Using custom workflows with GitHub Pages” belgesi bu yolun adımlarını anlatıyor.

Jekyll temalarının bakım durumu Hugo ve Astro’dan farklı bir tablo çiziyor; en çok yıldızlı Jekyll temalarının bir kısmı yıllardır commit almıyor ve terk edilmiş temalar listesinin çoğunluğunu oluşturuyor. Üç üreticinin karşılaştırması karşılaştırma sayfasında.