Jiří Hýbek
GitHub Pages & Jekyll

GitHub Pages & Jekyll

Jak na tvorbu github.io stránek za pomoci Jekyllu.

Už delší dobu narážím na stránky projektů, které jsou hostované na doméně github.io, a tak jsem začal pátrat o co jde. Zjistil jsem, že GitHub nabízí hosting stránek pro repozitáře.

GitHub Pages podporují:

  • Statické HTML stránky
  • Jekyll – „CMS“ systém v Ruby, který generuje statické HTML stránky, GitHub jej podporuje nativně, a tudíž se sám stará o kompilaci obsahu vždy, když aktualizujete repozitář.
  • Před-definované stránky – GitHub nabízí automatický generátor stránek s několika předefinovanými šablonami. Toto je velmi užitečné pro malé projekty či knihovny. Ovšem generátor umí vygenerovat jen jednu statickou stránku.

Osobně se již druhý den snažím zprovoznit dokumentaci k projektu na GitHubu pomocí GitHub pages a Jekyllu a konečně jsem přišel na to, jak se co dělá. Nabízím tedy stručný český návod.

#Jak fungují GitHub Pages?

GitHub nabízí dva typy hostingů:

  • Stránky uživatele / organizace
  • Stránky pro repozitář

#Uživatel & Organizace

Pro uživatele či organizace jsou stránky dostupné na adrese:

http://<uzivatel/organizace>.github.io/

Stránky pro uživatele či organizaci můžete publikovat tím, že vytvoříte repozitář s výše uvedeným jménem domény. Já bych tedy vytvářel repozitář s názvem: jirihybek.github.io.

#Repozitář

Pokud chcete publikovat stránky pro repozitář (projekt), je potřeba v repozitáři vytvořit větev s názvem gh-pages.

Stránky jsou poté dostupné na adrese:

http://<uzivatel/organizace>.github.io/<repozitar>

V případě mého repozitáře s názvem downgen by byly stránky dostupné na adrese: http://jirihybek.github.io/downgen/.

Návodů na toto téma naleznete spoustu, já se v tomto příspěvku zaměřím na použití Jekyllu.

#Používáme Jekyll

Jednoduchý systém pro správu obsahu, který generuje statické HTML stránky. Je tedy bezpečný, jednoduchý a rychlý. Ve zkratce funguje tak, že vytvoříte HTML či Markdown soubory a Jekyll je podle konfigurace „zkompiluje“ do statických HTML stránek.

Jekyll podporuje:

  • Šablony
  • Styly
  • Pluginy

#Instalace

Jekyll je aplikace psaná v jazyce Ruby, potřebujete tedy Ruby, NodeJS a pár dalších utilit. V Ubuntu jej nainstalujete z repozitáře například pomocí následujícího příkazu.

1
sudo apt-get install nodejs ruby-dev rubygems

Dále je potřeba nainstalovat Jekyll a Bundler.

1
2
sudo gem install bundler
sudo gem install jekyll

#Vytvoření projektu

Upozornění – musíme vytvořit Jekyll projekt ještě před repozitářem, jelikož cílový adresář musí být prázdný!

Projekt založíme pomocí příkazu:

1
jekyll new moje-stranky

Poté se přesuneme do složky s projektem:

1
cd moje-stranky

A vytvoříme v ní nový soubor Gemfile, který obsahuje konfiguraci pro bundler. To nám umožní nainstalovat a spouštět verzi Jekyllu, kterou používá GitHub a tudíž nemusíme řešit problémy s kompatibilitou.

Gemfile:

1
2
source 'https://rubygems.org'
gem 'github-pages'

Poté spustíme bundler a nainstalujeme potřebné balíčky:

1
bundle install

Jekyll obsahuje webový server, který nám umožňuje lehce přistupovat k vygenerovaným stránkám a automaticky sleduje změny a poté aktualizuje statické HTML soubory.

Spustíme:

1
bundle exec jekyll server

Nyní můžeme v prohlížeči otevřít adresu http://localhost:4000/ a podívat se na naše stránky.

Proč spouštíme příkaz bundle exec? Můžete též spustit Jekyll přímo pomocí jekyll serve, avšak bundle exec nám spustí stejnou verzi, jako používá GitHub Pages a tudíž nebudeme mít problémy s kompatibilitou.

Již můžeme server vypnout stisknutím kláves Ctrl+C.

#Adresářová struktura stránek

Jekyll nám vygeneroval spoustu adresářů, ve kterých nalezneme různé soubory:

1
2
3
4
5
6
_includes       # Soubory "šablony" - hlavička, patička, apod...
_layouts        # Šablony obsahu pro typy stránek - stránka, příspěvek, apod...
_posts          # Příspěvky pokud využíváme Jekyll jako blog
_sass           # CSS soubory používající preprocessor SASS
_site           # Vygenerované statické HTML soubory
css             # Proměnné a konfigurace pro CSS styly

Pokud budeme vytvářet pouze „statické“ stránky, můžeme bez obav smazat následující soubory a adresáře:

1
2
./_layouts/post.html
./_posts

Úpravy šablony nechám již na vás. Je k dispozici pár pěkných šablon, které nainstalujete tak, že jen zkopírujete veškeré soubory do své lokální kopie stránek.

Pozor – šablony většinou obsahují i výchozí stránky a příspěvky, nejprve tedy použijte šablonu a až poté tvořte obsah jinak budete muset ručně zkopírovat jen vybrané soubory týkající se vzhledu a poté upravit názvy šablon v jednotlivých stránkách.

#Publikujeme stránky na GitHub

Máme funkční strukturu pro Jekyll a nyní můžeme stránky publikovat na GitHub.

#Stránky pro uživatele či organizaci

V případě, že vytváříme stránky pro GitHub uživatele či organizaci, publikujeme stránky přímo do hlavní větvě repozitáře. Založíme si tedy na GitHubu repozitář s názvem uživatele či organizace.

Poté si z naší lokální kopie stránek vytvoříme GIT repozitář:

1
git init

Dále přidáme soubory do repozitáře a provedeme commit:

1
2
git add .
git commit -a -m "Site import"

Nyní přidáme do konfigurace vzdálený repozitář GitHubu a provedeme push.

1
2
git remote add origin [email protected]:<uzivatel>/<repozitar>.git
git push -u origin master

Napoprvé chvíli potrvá, než GitHub naše stránky publikuje, přibližně 10 minut.

#Stránky pro projekt

Jelikož musíme vytvořit v GITu novou vývojovou větev (branch) je začátek trochu komplikovanější.
V případě, že u sebe nemáme lokální repozitář projektu, stáhneme si jej:

1
git clone <url> <nazev>

Nyní se přesuneme do složky repozitáře a vytvoříme novou větev gh-pages:

1
git checkout --orphan gh-pages

Větev musí být orphan aby byla nezávislá.

Dále smažeme veškeré soubory:

1
git rm -rf .

Poté všechny soubory našich Jekyllovských stránek nakopírujeme do repozitáře (kromě adresáře .git, pokud jej tam máme).

Nyní musíme upravit konfiguraci stránek a změnit proměnnou baseurl, jelikož stránky projektu leží v „pod-adresáři“ našich GitHub stránek.

Příklad úpravy _config.yml:

1
2
3
4
5
6
7
8
9
10
# Site settings
title: Pages Sandbox
email: [email protected]
description: "Lorem ipsum dolor sit amet..."
baseurl: "/pages-sandbox" # the subpath of your site, e.g. /blog/
url: "http://jirihybek.github.io/" # the base hostname & protocol for your site
github_username: jirihybek

#Build setting
smarkdown: kramdown

Dále přidáme soubory do repozitáře a provedeme commit:

1
2
git add .
git commit -a -m "Site import"

Nakonec změny pushneme na GitHub:

1
git push origin gh-pages

Poprvé opět chvíli potrvá, než GitHub naše stránky publikuje.

Stránky již nyní editujeme ve větvi repozitáře.

#Závěrem

GitHub Pages jsou velmi pěkný způsob, jak zdarma publikovat informace a dokumentaci k našim projektům. Chvíli potrvá, než si na Jekyll zvyknete a vytvoříte si vlastní „base“ šablonu, kterou můžete bez obav kopírovat a vše si usnadnit.

Dále uvádím pár odkazů na užitečné zdroje:

Doufám, že vám návod pomohl a budu rád za případné připomínky.