Jekyll - genialny silnik dla bloga na GitHub Pages

Źródło: blog.tomaszdunia.pl

🇵🇱->🇬🇧 Go to english version of this post / Przejdź do angielskiej wersji tego wpisu

Spis treści:

Niniejszy wpis łączy się częściowo z postem dotyczącym migracji mojego bloga z Wordpress na silnik Jekyll i infrastrukturę GitHub Pages. Opisałem w nim dlaczego to zrobiłem, a teraz przyszła pora na pochylenie się nad tym jak to zrobiłem. Tak jak już pisałem wcześniej, jest to bardzo proste i wierzę, że naprawdę każdy sobie z tym poradzi, bez względu na poziom zaawansowania technicznego. Na aktualny stan mojej wiedzy nie znam łatwiejszego sposobu na uruchomienie swojego osobistego bloga i to w dodatku całkowicie za darmo. Dlatego jeżeli nosisz się z myślą o utworzeniu swojego skromnego kącika w Internecie to zapinaj pasy, bo zabieram Cię w krótką podróż po świecie GitHub Pages, Jekyll, Markdown i statycznych stron HTML.

Przygotowanie środowiska GitHub

Uruchomienie Jekyll

Podstawową zaletą robienia tego z wykorzystaniem GitHub Pages jest to, że wszystko praktycznie robi się samo, a jedyne co trzeba wiedzieć to to, które opcje należy włączyć w ustawieniach.

      
# --- GŁÓWNE USTAWIENIA ---
title: Tytuł bloga # Wpisz tutaj swój tytuł bloga
description: Opis bloga # Wpisz tutaj swój opis bloga
url: "https://to3k.github.io" # Zmień tutaj mój login na swój
baseurl: "" 
favicon: favicon.png # ikonę wrzuć do głównego folderu repozytorium pod tą nazwą (najlepiej rozdzielczość 192x192 albo 512x512)

# --- MOTYW ---
remote_theme: riggraz/no-style-please # Domyślnie Jekyll używa motywu minima, ale nie podobał mi się on, więc od razu zmieniłem go na ten i tak też polecam zrobić

# --- USTAWIENIA LINKÓW ---
permalink: /:title/ # Takie permalinki są zgodne ze standardem Wordpress, co później ułatwi ewentualną migrację istniejącego bloga z WP

# --- WTYCZKI ---
plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-remote-theme
  - jekyll-sitemap

# --- DANE AUTORA ---
author:
  name: Jan Kowalski # Wypełni wedle uznania
  url: https://pajacyk.pl # Wypełni wedle uznania

# --- USTAWIENIA MARKDOWN ---
markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge



    
      
---
layout: default
title: Strona główna # Wpis tutaj tytuł strony głównej
---

<div id="all-posts">
  <h3>Spis treści:</h3>
  <ul style="list-style: none; padding-left: 0;">
    {% for post in site.posts %}
      <li style="margin-bottom: 8px;">
        <span style="color: #666; font-family: monospace; margin-right: 10px;">{{ post.date | date: "%d-%m-%Y" }}</span>
        &raquo;
        <a href="{{ post.url | relative_url }}" style="font-weight: bold;">{{ post.title }}</a>
      </li>
    {% endfor %}
  </ul>
</div>



    
      
--- 
layout: post
title: "Hello World!"
published: true # Przydatne do późniejszego tworzenia draftów wpisów przed ich oficjalną publikacją, po prostu dopóki wpis nie jest gotowy to wpisz tu false, a Jekyll będzie go ignorował
categories: # Tu wrzucasz kategorie, którymi później można sortować wpisy
  - "kategoria1"
  - "kategoria2"
tags: # Tu wrzucasz tagi, którymi później można sortować wpisy
  - "tag1"
  - "tag2"
image: "/images/COVERIMAGE.png" # Odnośnik do grafiki wiodącej wpisu, jeżeli planujesz takowych używać
---

To jest mój pierwszy wpis na nowym blogu z silnikiem Jekyll odpalonym na GitHub Pages.

Własna domena

Oczywiście jest możliwość podpięcia bloga pod własną domenę np. blog.tomaszdunia.pl. W tym przypadku jest to raczej subdomena domeny tomaszdunia.pl, ale nie ma to większego znaczenia, bo jest to możliwe zarówno dla domeny najwyższego poziomu jak i subdomen.

Ustawienia po stronie GitHub

Ustawienia dla domeny najwyższego poziomu (np. tomaszdunia.pl)

Musisz ustawić następujące rekordy:

Uwaga: pamiętaj, że jeżeli były tam wcześniej jakieś rekordy to musisz je wyczyścić.

Ustawienia dla subdomeny (np. blog.tomaszdunia.pl)

Jeżeli domena wyższego poziomu należy do Ciebie (tomaszdunia.pl) to wchodzisz w ustawienia jej rekordów DNS i ustawiawsz:

Uwaga: pamiętaj, że jeżeli były tam wcześniej jakieś rekordy to musisz je wyczyścić.

Wracamy do ustawień GitHub

Teraz pozostaje tylko czekać aż DNSy rozprzestrzenią się po sieci. Czasem może to być chwila, a w innym przypadku nawet 24 godziny… O zakończeniu całego procesu będziemy pewni, gdy po wejściu w Settings -> sekcja Code and automation -> Zakładka Pages -> w sekcji Custom domain zobaczymy zielony napis DNS check successful. W tym momencie musimy przejść jeszcze odrobinę niżej by zaznaczyć opcję Enforce HTTPS co spowoduje wygenerowanie certyfikatu SSL dla naszej strony. Zarządza tym GitHub, więc absolutnie nie musimy się tym przejmować.

Teraz można już wpisać w pasek adresu przeglądarki podpiętą domenę i cieszyć się blogiem widniejącym pod nowym adresem.

Menu

Przeważnie blog to nie tylko wpisy. Warto wzbogacić go o dodatkowe strony jak O autorze, Polityka prywatności czy chociażby Wesprzyj / Donate. Zróbmy sobie zatem takie przykładowe menu, które później każdy będzie mógł dostosować pod siebie.

      
<!DOCTYPE html>
<html lang="{{ site.lang | default: "pl" }}">
  {% include head.html %}

  <body>
    <div style="max-width: 700px; margin: 0 auto; padding: 20px;">

      <header class="masthead" style="margin-bottom: 40px;">
        <h1 style="margin-bottom: 10px;">
          <a href="{{ "/" | relative_url }}" style="text-decoration: none; color: inherit;">{{ site.title }}</a>
        </h1>
        <nav style="border-bottom: 1px solid #eee; padding-bottom: 10px;">
          <a href="{{ "/about" | relative_url }}">Autor</a> /
          <a href="{{ "/donate" | relative_url }}">Wesprzyj</a> /
          <a href="{{ "/rodo" | relative_url }}">Polityka prywatności</a>
          
        </nav>
      </header>

      <main>
        {{ content }}
      </main>

      <footer style="margin-top: 80px; padding-top: 20px; border-top: 1px dashed #ccc; font-size: 0.8em; color: #666;">
        <p>
          &copy; {{ site.time | date: '%Y' }} {{ site.author.name }}.
          Treść dostępna na licencji <a href="https://creativecommons.org/licenses/by-sa/4.0/deed.pl" target="_blank">CC BY-SA 4.0</a>.
        </p>
        <p>
          Blog powstał na podstawie poradnika dostępnego na<a href="https://blog.tomaszdunia.pl/blog-jekyll-github/">blog.tomaszdunia.pl</a>!
        </p>
        <p>Zachęcam również do subskrybowania tego bloga poprzez <a href="/feed.xml">kanał RSS</a>.</p>
      </footer>

    </div>
  </body>
</html>

Wyszukiwarka

Każdy szanujący się blog powinien mieć narzędzie do wyszukiwania odpowiednich fraz w tytułach, treści i tagach jego wpisów. My jesteśmy szanującymi się autorami, więc oczywiście udostępnimy takie narzędzie swoim czytelnikom.

      
---
layout: null
---
[
  {% for post in site.posts %}
    {
      "title"    : {{ post.title | jsonify }},
      "url"      : "{{ site.baseurl }}{{ post.url }}",
      "date"     : "{{ post.date | date: "%d-%m-%Y" }}",
      "content"  : {{ post.content | strip_html | strip_newlines | jsonify }}
    } {% unless forloop.last %},{% endunless %}
  {% endfor %}
]



    
      
---
layout: default
title: Strona główna # Wpis tutaj tytuł strony głównej
---

<div style="margin-bottom: 30px;">
  <input type="text" id="search-input" placeholder="Szukaj..." style="width: 100%; padding: 8px; font-family: monospace; border: 1px solid #ccc; border-radius: 4px;">
  <ul id="results-container" style="list-style: none; padding-left: 0; margin-top: 10px;"></ul>
</div>

<div id="all-posts">
  <h3>Spis treści:</h3>
  <ul style="list-style: none; padding-left: 0;">
    {% for post in site.posts %}
      <li style="margin-bottom: 8px;">
        <span style="color: #666; font-family: monospace; margin-right: 10px;">{{ post.date | date: "%d-%m-%Y" }}</span>
        &raquo;
        <a href="{{ post.url | relative_url }}" style="font-weight: bold;">{{ post.title }}</a>
      </li>
    {% endfor %}
  </ul>
</div>

<script src="https://unpkg.com/simple-jekyll-search@latest/dest/simple-jekyll-search.min.js"></script>
<script>
  SimpleJekyllSearch({
    searchInput: document.getElementById('search-input'),
    resultsContainer: document.getElementById('results-container'),
    json: '/search.json',
    searchResultTemplate: '<li style="margin-bottom: 8px;"><span style="color: #666; font-family: monospace; margin-right: 10px;">{date}</span> &raquo; <a href="{url}" style="font-weight: bold;">{title}</a></li>',
    noResultsText: 'Nie znaleziono pasujących wpisów.',
    limit: 500,
    fuzzy: false
  })
</script>

Markdown

Dla osób przyzwyczajonych do Worda lub klasycznego edytora WordPressa (Gutenberg), Markdown może na pierwszy rzut oka wydawać się krokiem wstecz. W końcu zamiast klikać w wygodne ikonki, musimy wpisywać jakieś “dziwne znaczki”.

W rzeczywistości Markdown to wolność. To lekki język znaczników, który pozwala formatować tekst bez odrywania rąk od klawiatury. Jest uniwersalny (działa na GitHubie, w Notion, Obsidianie, Discordzie) i – co najważniejsze – jest czystym tekstem. Oznacza to, że za 10 lat bez problemu otworzysz swoje wpisy w dowolnym edytorze, nie martwiąc się o to, że baza danych WordPressa się rozjechała.

W Jekyll to właśnie pliki Markdown .md są źródłem treści. Podczas budowania strony, Jekyll automatycznie zamienia je na gotowy kod HTML.

Szybka ściąga z Markdowna

Oto absolutne podstawy, których używam przy pisaniu każdego wpisu:

Słowa końcowe

To tylko tyle i aż tyle. W mojej ocenie technicznie blog nie potrzebuje niczego więcej. Tworząc swoją stronę, szczególnie pierwszą, przeważnie łapiemy się na tym, że chcemy wycisnąć z niej co tylko się da - żeby była “na wypasie”. Zarówno jeżeli chodzi o wygląd jak i bajery (np. widżety). W praktyce nie są to istotne rzeczy. Zapominamy natomiast o tym co jest najważniejsze, czyli o treści. To właśnie ona jest kluczowa i stanowi prawdziwą wartość bloga. Dlatego na wypasie powinna być treść, a wszystko wokół niej winno być możliwie jak najbardziej minimalistyczne, żeby nie przyćmiewać swoim pozornym blaskiem tego co powinno naturalnie lśnić najjaśniej. Jasny gwint, ale ze mnie filozof… Wracając już na Ziemię, mam nadzieję, że ten poradnik komuś się przyda i jeżeli będziesz to Ty to koniecznie pokaż mi swojego bloga, gdy już go opublikujesz!