Tutorial: Tworzenie bloga z Jekyll i GitHub Pages

Na podstawie artykułu Tomasza Dunii z blog.tomaszdunia.pl

Spis treści

Wprowadzenie
Tworzenie repozytorium GitHub
Struktura projektu
Konfiguracja _config.yml
Tworzenie postów
Tworzenie layoutu
Implementacja wyszukiwarki
Konfiguracja domeny
Ustawienia GitHub Pages

Wprowadzenie

Jekyll to generator statycznych stron, który w połączeniu z GitHub Pages pozwala na stworzenie darmowego bloga bez konieczności posiadania zaawansowanych umiejętności technicznych. Blog korzysta z Markdown - prostego języka znaczników, który zapewnia przenośność i niezależność treści.

Zalety tego rozwiązania:

Darmowy hosting na GitHub Pages
Własna domena (opcjonalnie)
Markdown - wolność i przenośność treści
Minimalistyczny design - skupienie na treści
Brak baz danych - statyczne pliki HTML

Tworzenie repozytorium GitHub

Zaloguj się na GitHub
Utwórz nowe repozytorium o nazwie: (twoja-nazwa-użytkownika).github.io
- Przykład: jeśli Twój login to jankowalski, repozytorium powinno nazywać się jankowalski.github.io
Ustaw repozytorium jako publiczne
Zainicjalizuj z plikiem README (opcjonalnie)

Struktura projektu

Podstawowa struktura katalogów i plików:

repository-root/
├── _config.yml              # Główny plik konfiguracyjny
├── _posts/                  # Katalog z postami
│   └── YYYY-MM-DD-post-title.md
├── _layouts/                # Szablony layoutów
│   └── default.html
├── index.md                 # Strona główna
├── search.json              # Plik dla wyszukiwarki
├── about.md                 # Strona "O mnie"
├── donate.md                # Strona wsparcia (opcjonalnie)
├── rodo.md                  # Polityka prywatności (opcjonalnie)
└── CNAME                    # Auto-generowany przez GitHub

Konfiguracja _config.yml

Utwórz plik _config.yml w głównym katalogu projektu z następującą konfiguracją:

# Podstawowe informacje
title: Tytuł Twojego Bloga
description: Krótki opis bloga

# URL i ścieżki
url: "https://twoja-domena.pl"  # Twoja domena lub username.github.io
baseurl: ""                      # Puste dla domeny głównej

# Motyw
remote_theme: riggraz/no-style-please

# Permalink (struktura URL)
permalink: /:title/              # Kompatybilna z WordPress struktura

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

# Markdown
markdown: kramdown
kramdown:
  syntax_highlighter: rouge
  syntax_highlighter_opts:
    default_lang: html

Kluczowe parametry:

title - tytuł bloga wyświetlany w nagłówku
description - opis używany przez wyszukiwarki
url - pełny adres URL Twojego bloga
baseurl - pozostaw puste dla głównej domeny
remote_theme - motyw Jekyll (w tym przykładzie: minimalistyczny “no-style-please”)
permalink - struktura URL dla postów
plugins - wtyczki rozszerzające funkcjonalność Jekyll

Tworzenie postów

Konwencja nazewnictwa

Pliki postów muszą być nazwane według schematu:

YYYY-MM-DD-identyfikator.md

Przykłady:

2026-02-15-hello-world.md → URL: /hello-world/
2026-02-10-tutorial-jekyll.md → URL: /tutorial-jekyll/

Data określa kolejność publikacji (najnowsze najpierw), a identyfikator staje się częścią URL.

Front Matter (nagłówek YAML)

Każdy post wymaga nagłówka YAML:

---
layout: post
title: "Tytuł Twojego Posta"
published: true
categories:
  - Programowanie
  - Tutorial
tags:
  - Jekyll
  - GitHub
image: "/images/post-cover.png"
---

# Treść posta

Tutaj piszesz treść w Markdown...

Parametry Front Matter:

layout - szablon layoutu (domyślnie post)
title - tytuł posta
published - true (opublikowany) lub false (wersja robocza)
categories - kategorie posta
tags - tagi
image - obrazek wyróżniający (opcjonalnie)

Podstawy Markdown

# Nagłówek H1
## Nagłówek H2
### Nagłówek H3

**Pogrubiony tekst**
*Kursywa*

[Link](https://example.com)

![Obrazek](ścieżka/do/obrazka.png)

- Lista punktowana
- Punkt drugi

1. Lista numerowana
2. Punkt drugi

`kod inline`

```python
# Blok kodu
def hello():
    print("Hello World")

---

## Tworzenie layoutu

Utwórz katalog `_layouts` i plik `default.html`:

```html
<!DOCTYPE html>
<html lang="pl">
<head>
  <head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />

  <title>Tutorial: Tworzenie bloga z Jekyll i GitHub Pages</title><!-- Begin Jekyll SEO tag v2.8.0 -->
<meta name="generator" content="Jekyll v3.10.0" />
<meta property="og:title" content="Tutorial: Tworzenie bloga z Jekyll i GitHub Pages" />
<meta name="author" content="Paweł Sioda" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="Blog o programowaniu, AI, automatyzacji i data science." />
<meta property="og:description" content="Blog o programowaniu, AI, automatyzacji i data science." />
<link rel="canonical" href="https://blog.webdevmaniak.pl/docs/JEKYLL-TUTORIAL/" />
<meta property="og:url" content="https://blog.webdevmaniak.pl/docs/JEKYLL-TUTORIAL/" />
<meta property="og:site_name" content="Mój Blog" />
<meta property="og:type" content="website" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="Tutorial: Tworzenie bloga z Jekyll i GitHub Pages" />
<script type="application/ld+json">
{"@context":"https://schema.org","@type":"WebPage","author":{"@type":"Person","name":"Paweł Sioda"},"description":"Blog o programowaniu, AI, automatyzacji i data science.","headline":"Tutorial: Tworzenie bloga z Jekyll i GitHub Pages","url":"https://blog.webdevmaniak.pl/docs/JEKYLL-TUTORIAL/"}</script>
<!-- End Jekyll SEO tag -->
<link type="application/atom+xml" rel="alternate" href="https://blog.webdevmaniak.pl/feed.xml" title="Mój Blog" /><link rel="shortcut icon" type="image/x-icon" href="" />
  <link rel="stylesheet" href="/assets/css/main.css" />
	<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.css" integrity="sha384-OH8qNTHoMMVNVcKdKewlipV4SErXqccxxlg6HC9Cwjr5oZu2AdBej1TndeCirael" crossorigin="anonymous">

</head>

  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Tutorial: Tworzenie bloga z Jekyll i GitHub Pages | Mój Blog</title>
</head>
<body>
  <header>
    <nav>
      <a href="/">Strona główna</a>
      <a href="/about/">O mnie</a>
      <a href="/search/">Szukaj</a>
    </nav>
  </header>

  <main>
    <h1 id="wyszukiwarka">Wyszukiwarka</h1>

<div id="search-container">
  <input type="text" id="search-input" placeholder="Szukaj postów..." style="width: 100%; padding: 10px; font-size: 16px;" />
  <ul id="results-container" style="list-style: none; padding: 0; margin-top: 20px;"></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><a href="{url}">{title}</a> <span style="color: #666;">({date})</span></li>',
    noResultsText: 'Nie znaleziono wyników',
    limit: 10,
    fuzzy: false
  })
</script>


  </main>

  <footer>
    <p>&copy; 2026 Mój Blog</p>
  </footer>
</body>
</html>

Kluczowe elementy:

`<head> Tutorial: Tworzenie bloga z Jekyll i GitHub Pages

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.css" integrity="sha384-OH8qNTHoMMVNVcKdKewlipV4SErXqccxxlg6HC9Cwjr5oZu2AdBej1TndeCirael" crossorigin="anonymous">

</head> ` - ładuje automatyczne zależności stylów

Tutorial: Tworzenie bloga z Jekyll i GitHub Pages - tytuł strony
Mój Blog - tytuł bloga z _config.yml
`<h1 id="wyszukiwarka">Wyszukiwarka</h1>

` - miejsce na treść strony/posta

2026 - aktualny rok

Implementacja wyszukiwarki

Utwórz plik search.json w głównym katalogu:

---
layout: none
---
[
  
    {
      "title"    : "Witaj, świecie! Pierwszy post na blogu",
      "category" : "",
      "tags"     : "hello-world, blog",
      "url"      : "/pierwszy-post/",
      "date"     : "2026-02-15",
      "content"  : "Witaj, świecie!\n\nTo mój pierwszy post na blogu zbudowanym z Jekyll i GitHub Pages!\n\nDlaczego Jekyll?\n\nJekyll to świetne rozwiązanie dla programistów, którzy chcą:\n\n\n  Pisać w Markdown - prostym i przenośnym formacie\n  Mieć darmowy hosting na GitHub Pages\n  Pełną kontrolę nad swoją treścią\n  Szybkie statyczne strony bez bazy danych\n\n\nCo dalej?\n\nPlanuję pisać o:\n\n\n  Programowaniu\n  Technologii\n  Projektach, nad którymi pracuję\n  AI &amp; autiomatyzacji\n  Data Science\n\n\nKonkluzja\n\nCieszę się, że możesz odwiedzić mojego bloga. Mam nadzieję, że znajdziesz tutaj coś ciekawego!\n\nDo zobaczenia w następnym poście! 👋\n"
    } 
  
]

Ten plik generuje indeks JSON wszystkich postów, który może być wykorzystany przez bibliotekę wyszukiwania typu simple-jekyll-search.

Dodanie wyszukiwarki do strony:

Utwórz search.md:

---
layout: default
title: Wyszukiwarka
---

<div id="search-container">
  <input type="text" id="search-input" placeholder="Szukaj...">
  <ul id="results-container"></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'
  })
</script>

Konfiguracja domeny

Dla domeny głównej (apex domain):

Dodaj w ustawieniach DNS swojego dostawcy domeny:

Rekordy A (wszystkie cztery):

@    A    185.199.108.153
@    A    185.199.109.153
@    A    185.199.110.153
@    A    185.199.111.153

Rekord CNAME dla www:

www    CNAME    twoja-nazwa.github.io

Dla subdomeny (np. blog.domena.pl):

Rekord CNAME:

blog    CNAME    twoja-nazwa.github.io

Czas propagacji DNS

Zmiany DNS mogą zająć od kilku minut do 48 godzin.

Ustawienia GitHub Pages

Przejdź do repozytorium na GitHub
Kliknij Settings (Ustawienia)
W menu po lewej wybierz Pages
W sekcji Source:
- Branch: main (lub master)
- Folder: /root
Kliknij Save

Własna domena:

W sekcji Custom domain wpisz swoją domenę (np. blog.domena.pl)
GitHub automatycznie utworzy plik CNAME w repozytorium
Poczekaj na weryfikację DNS
Po weryfikacji zaznacz Enforce HTTPS dla bezpiecznego połączenia

Filozofia minimalizmu

“Treść jest kluczowa i stanowi prawdziwą wartość bloga”

Artykuł Tomasza Dunii promuje podejście minimalistyczne:

Skupienie na jakości treści zamiast wizualnych dodatków
Markdown jako wolność - przenośność treści
Brak rozpraszaczy i zbędnych widgetów
Szybkie ładowanie dzięki statycznym stronom

Podsumowanie

Gratulacje! Masz już działający blog oparty na Jekyll i GitHub Pages:

✅ Darmowy hosting ✅ Własna domena ✅ Posty w Markdown ✅ Wyszukiwarka ✅ SEO i RSS ✅ HTTPS

Źródło i licencja

Tutorial oparty na artykule Tomasza Dunii: blog.tomaszdunia.pl/blog-jekyll-github

Treść udostępniona na licencji CC BY-SA 4.0

Powodzenia z blogowaniem! 🎉