Uwaga! Trwają prace nad nową wersją serwisu. Mogą występować przejściowe problemy z jego funkcjonowaniem. Przepraszam za niedogodności!

🔥 Zgarnij PŁATNY STAŻ w 3 edycji kursu programowania front end (zapisy do 22.01) 🔥

GitHub Pages – podgląd projektu na GitHubie

Jak wygenerować link do strony swojego projektu

Każdy projekt do portfolio na GitHubie – jeśli tylko to możliwe – powinien mieć załączony link do podglądu strony czy aplikacji. To umożliwi wszystkim zainteresowanym (a przede wszystkim rekruterom) zapoznanie się z projektem i wstępną ocenę umiejętności kandydata. Jak szybko uzyskać link do podglądu projektu?

Spis treści

Czym jest usługa GitHub Pages

GitHub Pages to strony internetowe hostowane i publikowane przez GitHuba. Front-end developerzy mogą z powodzeniem wykorzystywać je do stworzenia swojego portfolio. Nie jest do tego potrzebna ani własna domena, ani wykupiony hosting.

Dlaczego mowa o front-end developerach? Ponieważ GitHub Pages to statyczna usługa hostingowa. Oznacza to, że nie obsłuży technologii back-endowych, czyli kodu wykonującego się po stronie serwera. Nie uda nam się więc pokazać działania aplikacji napisanych np. w językach Python, Java czy PHP.

Bez przeszkód jednak pokażemy działający projekt stworzony za pomocą HTML-a, CSS-a i JavaScriptu, ponieważ kod w tych językach jest wykonywany po stronie przeglądarki, a nie po stronie serwera.

Jak przygotować projekt do publikacji na GitHub Pages

Plik index.html w odpowiednim katalogu

Potrzebujesz pliku index.html – zostanie on rozpoznany jako strona główna projektu. Możesz go umieścić albo w katalogu głównym, albo w folderze o nazwie docs.

Pozostałe potrzebne pliki (np. ze stylami CSS czy kodem JavaScript) muszą znajdować się co najmniej na tym samym poziomie zagnieżdżenia co index.html lub głębiej. Masz więc wybór odnośnie do struktury projektu. Poniżej kilka przykładowych prostych struktur:

  • pliki index.html, style.css, app.js w katalogu głównym
  • plik index.html w katalogu głównym, plik style.css w katalogu ./styles i plik app.js w katalogu ./script
  • pliki index.html, style.css, app.js w katalogu ./docs
  • plik index.html w katalogu ./docs, plik style.css w katalogu ./docs/styles i plik app.js w katalogu ./docs/script.

Oczywiście wszystkie pliki i katalogi (prócz ./docs i index.html) możesz nazwać dowolnie.

Uwaga: jeśli wybierzesz opcję umieszczenia index.html w katalogu ./docs, to pamiętaj, aby nie umieszczać żadnych zasobów potrzebnych do prawidłowego działania strony poza tym katalogiem (wyżej w strukturze plików). Jeśli podczas podpinania GitHub Pages wskażesz katalog ./docs jako główny, nie zadziała import plików spoza tego katalogu.

Nawigacja na stronie w GitHub Pages

Dzięki GitHub Pages uruchomisz nie tylko landing page’a! Możesz z powodzeniem tworzyć podstrony oraz nawigację i przekierowywać użytkownika za pomocą linków z odpowiednimi ścieżkami, np. <a href='./contact.html'>Kontakt</a>.

Jak podpiąć GitHub Pages do projektu

Gdy masz już repozytorium z plikami projektu na GitHubie (a przynajmniej z plikiem index.html), kliknij ustawienia (Settings) i wejdź w zakładkę Pages.

W sekcji Source wybierz gałąź, na której masz projekt. Jeśli nie tworzyłeś żadnych gałęzi, to wybierz po prostu gałąź główną: main lub master (tak nazywa się gałąź główna w starszych projektach).

Ustawianie gałęzi projektu w zakładce Pages

Po wybraniu gałęzi wyświetli Ci się nowe pole. Ustaw w nim katalog, w którym umieściłeś plik index.html. Jeśli jest to katalog główny, to wybierz opcję / (root), a jeśli utworzyłeś wcześniej katalog ./docs, to wybierz opcję /docs.

Ustawianie katalogu pliku index.html w zakładce Pages

Motyw i domena nie są teraz do niczego potrzebne, więc pola zostają puste.

Na koniec zapisz zmiany (Save).

Publikowanie strony może chwilę potrwać. Póki wyświetla Ci się informacja „Your site is ready to be published at https://twojprofil.github.io/twoje-repozytorium/” strona będzie jeszcze nieaktywna.

Po chwili (lub nawet po paru minutach) po odświeżeniu repozytorium zobaczysz informację „Your site is published at https://twojprofil.github.io/twoje-repozytorium/”. Strona powinna już działać.

Projekt na podstawie Reacta lub podobnej technologii

Zwykłe podpięcie GitHub Pages tu nie wystarczy. Aby podgląd był dostępny, powinieneś wygenerować wersję produkcyjną aplikacji, czyli zrobić builda i pushować go na repozytorium. W tak utworzonym katalogu będzie znajdować się plik HTML (zapewne index.html, choć nazwa jest zależna od konfiguracji narzędzia).

Gdy podepniesz GitHub Pages zgodnie z instrukcją powyżej, podgląd aplikacji będzie dostępny pod adresem podobnym do tego: https://twojprofil.github.io/twoje-repozytorium/build/src/index.html. Wyboldowany fragment to ścieżka do Twojego zbudowanego pliku HTML w katalogu utworzonym przez wygenerowanie wersji produkcyjnej (może się więc różnić w zależności od zastosowanej biblioteki, frameworka czy konfiguracji np. webpacka).

Co jeśli moja strona nie działa

Upewnij się, że Twój plik index.html jest w odpowiednim katalogu oraz sprawdź błędy w konsoli (F12 -> Console) – jeżeli dokonywałeś jakichś zmian w strukturze plików, to możesz mieć nieprawidłowe ścieżki importów. Wówczas w konsoli zobaczysz informację, że nie udało się załadować konkretnego zasobu.

Błąd w konsoli wskazujący na nieprawidłową ścieżkę do pliku

Zmiany wprowadzone w plikach nie będą widoczne na stronie w GitHub Pages od razu. Musisz chwilę poczekać – podobnie jak podczas pierwszego podpinania strony do projektu.

Zmiany w kodzie nie są widoczne na stronie mimo odświeżania

Być może musisz jeszcze chwilę poczekać. Jeśli jednak informacja w Settings -> Pages mówi jednoznacznie, że Twoja strona jest już opublikowana („Your site is published at…”), to być może wina leży po stronie przeglądarki.

Niektóre zasoby, np. style czy obrazy, są cache’owane przez przeglądarkę (zapisywane w jej pamięci podręcznej). Aby to zresetować, wejdź w ustawienia swojej przeglądarki i znajdź opcję czyszczenia danych przeglądania (w Chrome i Firefoxie możesz też użyć skrótu ctrl+F5). Po odświeżeniu strony nowe/zmodyfikowane zasoby powinny się już załadować.

Gdzie umieścić link do podglądu strony

Najlepszym na to miejscem jest plik README projektu. Informację o możliwości podglądu strony zamieść na samym jego początku, aby nikomu ona nie umknęła.

Link do podglądu projektu warto zamieścić także w sekcji About. W tym celu wejdź na stronę główną swojego repozytorium na GitHubie. Po prawej stronie znajdziesz sekcję About. W jej ustawieniach w polu Website wklej link z GitHub Pages. Zapisz i gotowe.

Sekcja About i pole Website na repozytorium GitHuba

Uwaga: w sekcji About nie próbuj zamieszczać linku w polu Description – to po prostu nie zadziała.

 

Oto Twoja strona zaistniała w Internecie – wykorzystaj to! Możesz np. zamieścić uzyskany link w swoich mediach społecznościowych. Im więcej osób dowie się, że programujesz, tym większe będziesz miał szansę na znalezienie pracy w IT. Chcesz zobaczyć, jakie jeszcze możliwości kryje publikowanie przez GitHuba? Zajrzyj do oficjalnej dokumentacji GitHub Pages.

Udostępnij ten artykuł:

Mentoring to efektywna nauka pod okiem doświadczonej osoby, która:

  • przekazuje Ci swoją wiedzę i nadzoruje Twoje postępy w zdobywaniu umiejętności,
  • uczy Cię dobrych praktyk i wyłapuje złe nawyki,
  • wspiera Twój rozwój i zwiększa zaangażowanie w naukę.

Mam coś dla Ciebie!

W każdy piątek rozsyłam motywujący do nauki programowania newsletter!

Dodatkowo od razu otrzymasz ode mnie e-book o wartości 39 zł. To ponad 40 stron konkretów o nauce programowania i pracy w IT.

PS Zazwyczaj wysyłam 1-2 wiadomości na tydzień. Nikomu nie będę udostępniał Twojego adresu e-mail.