Plan jest prosty. Mamy pomysł na aplikację, która będzie w formie bloga. Będzie można zakładać kolejne posty oraz dawać komentarze po nimi. Warto jeszcze wspierać tagi, aby filtrować listę postów. Jekyll nie ma własnych komentarzy - trzeba podpiąć zewnętrzną usługę (np. Giscus albo Disqus).
Aktualizacja: 2026-09-26
Wsparcie dla Ruby 2.7 skończyło się 2023-03-31, więc instaluj aktualną wersję
Ruby 3.x. Dzisiejszy jekyll new sam tworzy plik Gemfile (z motywem
minima jako gemem) i inną strukturę katalogów niż ta opisana niżej, a serwer
uruchamia się poleceniem bundle exec jekyll serve.
Moje zadanie będzie dotyczyło platformy www.ecmascript6.pl.
Chciałbym, aby na niej znalazły się informacje nt. najnowszego standardu ECMAScript 6.
Ze względu na końcówkę w domenie, chciałbym, aby artykuły były w niej po polsku.
Mam też plan, aby zrobić oddzielną sekcję na angielskojęzyczne artykuły.
Wybór narzędzia
Zaczynamy od wyboru systemu na którym będziemy się opierali. Ze względu na łatwość zarządzania wybór padł na Jekylla.
Jekyll to biblioteka (gem) w środowisku Ruby.
Za chwilę dowiecie się jak zainstalować interpreter języka Ruby. Stay Tuned!
Stworzenie katalogu
Zaczynamy tworząc katalog pod nasz projekt:
mkdir NAZWA_PROJEKTU
cd NAZWA_PROJEKTU
Instalacja narzędzia - rvm
Zainstalujemy rvm, tak aby nie zaśmiecać systemowej konfiguracji. Zainstalować go można na wiele różnych sposobów. Dużo sposób na instalację jest na stronie domowej. Moim zdaniem najprostszy to:
\curl -sSL https://get.rvm.io | bash -s stable
Instalacja interpretera języka - ruby
Gdy mamy już manager wersji języka, zainstalujemy wreszcie jakąś jego wersję! Wybrałem najnowszą z “2” na początku.
rvm install 2.7.8
Możemy właśnie zainstalowaną wersję ustawić jako domyślną za pomocą:
rvm alias create default 2.7.8
A następnie przełączmy się na tą wersję:
rvm use 2.7.8
Stworzenie środowiska dla zależności - gemset
Następnie stworzymy tzw. gemset, czyli katalog na potrzeby instalacji Jekylla
oraz jego zależności.
rvm gemset create NAZWA_PROJEKTU
Po wydaniu polecenia rvm list gemsets widzimy, że jeszcze musimy się przełączyć
na ten nowo stworzony gemset. Wydajemy polecenie:
rvm use 2.7.8@NAZWA_PROJEKTU
Jesteśmy już w nowym środowisku! 🎉
Instalacja Jekylla
Aby zainstalować Jekylla postępujemy zgodnie z rozpiską na stronie: https://jekyllrb.com/.
Wykonujemy poniższe polecenie, które zainstaluje nam gem (paczkę, program), dzięki której będziemy mogli stworzyć strukturą plików i katalogów dla naszego projektu.
gem install jekyll
Gdy mamy już zainstalowane narzędzie, wykorzystajmy je!
jekyll new .
Tym samym w katalogu projektu stworzy się struktura:
.
├── _config.yml
├── _includes
│ ├── footer-tag.html
│ ├── head-tag.html
│ └── header.html
├── _layouts
│ ├── default.html
│ ├── page.html
│ └── post.html
├── _posts
│ └── 2015-06-28-welcome-to-jekyll.markdown
├── _sass
│ ├── _base.scss
│ ├── _layout.scss
│ └── _syntax-highlighting.scss
├── about.md
├── css
│ └── main.scss
├── feed.xml
└── index.html
5 directories, 15 files
Dobrym pomysłem, jest teraz stworzenie repozytorium w tym katalogu. Wykonujemy po kolei:
git init git add . git commit -am "Initialize project"
Uruchomienie
Gdy już mamy strukturę projektu możemy już uruchomić nasz projekt w przeglądarce. Wystarczy uruchomić:
jekyll serve
W terminalu dostaniemy informację na jaki adres trzeba wejść, aby wyświetlić stronę. W moim przypadku jest to http://127.0.0.1:4000/
Strona wygląda następująco:
Zwróć uwagę na port który trzeba dopisać do adresu IP maszyny.
Można go (port) łatwo zmienić:jekyll serve --port 4001.
Konfiguracja
Plik: _config.yml
Gdy już mamy uruchomioną aplikację czas na dostosowanie jej pod nasze potrzeby.
Warto zacząć od głównego pliku konfiguracyjnego _config.yml znajdujący się w głównym katalog projektu.
Zawiera on takie pola jak: tytuł strony, opis, kontakt do autora no i URL.
Katalog: _includes/
Następnie warto przyjrzeć się katalogowi _includes, w którym jest lista
partiali (plików, które zostaną użyte w innym miejscu).
Plik head-tag.html zawiera definicję całego znacznika <head>.
Polecam dodać w nim wygenerowany snippet kodu z Google Analytics
(dziś GA4, bo Universal Analytics wyłączono w 2023 roku).
Dodatkowo może jakieś pliku CSS.
Katalog: _posts/
Kolejny katalog warty uwagi (chyba najważniejszy) to katalog _posts,
w który znajduje się lista plików z naszymi postami.
Jekyll przyjmuje konwencję, że jeden plik = jeden post.
To w nim umieszczamy pliku wg schematu YYYY-MM-DD-name-of-post.ext.
Mamy kilka typów rozszerzeń do wyboru, m.in. markdown, md, html. W każdym plik post istnieje specjalna sekcja na początku tego pliku, w której to definiujemy taki informacje jak:
- layout, w jakim dany post ma być wyświetlony,
- tytuł posta,
- oraz ewentualne tagi.
Jekyll zbiera tagi w zmiennej site.tags, ale stronę z listą postów
dla tagu trzeba zbudować samemu. Ze swojej strony polecam zwykły html,
ze względu na nieograniczone możliwości edycyjny. Pierwotnie używałem Markdown-a,
ale przy bardziej skomplikowanych elementach nie radził on sobie najlepiej.
Katalog:pages/
Ostatnią rzeczą na która warto zwrócić uwagę są zwykłe strony. W katalogu głównym
istnieje plik about.md. W zawartości takiego pliku (podobnie jak w postach)
poza layoutem i tytułem jest jeszcze parametr: permalink. Oznacza on URL pod jakim
strona ma byc dostępna. I tak proponuję stworzyć katalog pages, który będzie
przechowywał strony. Jekyll sam znajdzie pliki w takim katalogu.
Ważne jest, aby nazwa nie zaczynała się od znaku podkreślenia, gdyś katalogi z prefiksem “_” są traktowane przez Jekylla specjalnie.
Plik: Gemfile
Ostatnim krokiem będzie stworzenie pliku Gemfile w katalogu głównym,
aby ustawić odpowiednie środowisko (gemset) wraz z zawartością:
source 'https://rubygems.org'
ruby '2.7.8'
#ruby-gemset=NAZWA_PROJEKTU
gem 'jekyll'
Ponowna instalacja
Kiedy będziemy instalowali ponownie aplikację, to wystarczy wtedy tylko:
# stworzyć i aktywować `gemset`
rvm gemset create NAZWA_PROJEKTU
rvm use 2.7.8@NAZWA_PROJEKTU
# (bundler jest wbudowany w Ruby od wersji 2.6)
# zainstalować zależności
bundle install
… i mamy Jekylla! 🎉
Podsumowanie
Przejście opisanego tutoriala nie zajmuje wiele czasu. Po jego zakończeniu osiągamy spory efekt - w pełni praktyczną aplikację z podstronami oraz postami.
W dzisiejszych czasach postawienie bloga to nie jest jakiś rocket science.
Jeśli masz doświadczenie z językami programowania to na pewno chciałbyś mieć nieograniczony wpływ na Twoją aplikację webową, tym samym stworzenie takie aplikacji dzięki Jekyllowi jest efektywne, szybkie i łatwe!
Cya! 👋