Witaj w repozytorium strony internetowej koła naukowego "Gradient". Poniżej zamieściliśmy kilka informacji, które mogą się przydać podczas Twojego wkładu w rozwój strony. Prosimy Cię o dostosowanie się do panującego regulaminu!
W przypadku problemów śmiało pisz do Administratorów lub Zarządu Koła. Na pewno ktoś Ci pomoże :)
Poniżej zamieszczamy sporą ilość pytań i odpowiedzi, które zapewne będą się pojawiać na bieżąco :)
Chęci :)
Nowy post albo projekt można dodać poprzez utworzenie nowego pliku Markdown (.md/.markdown) w folderze _posts.
Posty oraz projekty należy przygotować w dwóch wersjach językowych, których miejsce znajduje się w katalogu _i18n.
Przykładowe projekty możesz znaleźć w folderze examples.
Ważnym jest odpowiednie nazewnictwo pliku! W przeciwnym przypadku silnik strony może nie wykryć Twojej treści. Prosimy o dostosowanie się do przyjętej konwencji nazwenictwa w odpowiednim formacie:
[ROK]-[MIESIĄC]-[DZIEŃ]-[tytul-posta-malymi-literami-bez-pl-znakow].markdown
Do kontrybucji będziemy wykorzystywać następujący flow:
- Zrób forka repozytorium (przycisk "Fork"), a następnie sklonuj repozytorium gdzieś u siebie na komputerze:
$ git clone https://github.com/TWOJ_GITHUB_LOGIN/GradientPG.git- Stwórz brancha, na którym będziesz pracować (proszę o zachowanie konwencji nazewniczej):
$ git checkout -b imie_nazwisko/tytul_posta_lub_projektu- Zmodyfikuj stronę oraz przetestuj ją lokalnie.
- Zacommituj swoje zmiany:
$ git add .
$ git commit -m "Opis wprowadzonych zmian"- Wyślij swoje zmiany na GitHuba:
$ git push origin imie_nazwisko/tytul_posta_lub_projektu- Wejdź na GitHuba, a następnie utwórz Pull Request (więcej informacji znajdziesz tutaj).
Git stał się obecnie najpowszechniejszym narzędziem do kontroli wersji. Prędzej czy później każdy z nas będzie się go musiał nauczyć :)
W Internecie znajduje się mnóstwo kursów (polecam http://gitimmersion.com/), a także interaktywnych tutoriali. Główny workflow zamieściliśmy powyżej - na pewno sobie poradzisz :) W przypadku problemów prosimy o kontakt - spróbujemy pomóc.
Postaraliśmy się, aby stronę można było postawić jak najszybciej oraz jak najwygodniej. Istnieją trzy możliwe drogi, których wybór zależy od Ciebie.
Jest to najwygodniejsza możliwa droga do przetestowanie swojej treści u siebie lokalnie. Wymaga, aby na Twoim komputerze znajdował się:
- VirtualBox (im nowsza wersja tym lepiej - przynajmniej v5.1.0),
- Vagrant.
Gdy upewnisz się, że wszystkie narzędzia już posiadasz, wymagane są poniższe kroki:
- Wejdź do terminala i przejdź do katalogu z poniższym projektem.
- Uruchom polecenie:
$ vagrant upW tym momencie Vagrant przygotuje dla Ciebie maszynę wirtualną z Linuxem oraz wszelkimi potrzebnymi zależnościami. Cierpliwości - to może chwilę potrwać! :)
- Połącz się z maszyną wirtualną poprzez SSH:
$ vagrant ssh- Uruchom skrypt odpalający stronę na Twojej maszynie:
ubuntu@ubuntu-xenial:~$ cd /vagrant
ubuntu@ubuntu-xenial:/vagrant$ ./run_server.sh --watch- Gotowe! Strona powinna być dostępna pod adresem
http://10.0.0.99/i zmieniać swoją treść wraz z Twoimi modyfikacjami.
TIP: Jeżeli masz problemy z automatycznym odświeżaniem zawartości strony podczas modyfikacji treści, usuń opcję --watch i restartuj
serwer manualnie po każdej zmianie. Bardzo możliwe, że jest to bug po stronie Jekylla.
Ta opcja jest dobra, jeżeli chcesz zobaczyć wynik swoich prac i korzystasz z Linuxa/macOS (Windows może nie być w pełni wspierany).
Instrukcja:
- Zainstaluj na swoim komputerze Dockera wraz z Docker Compose. Szczegółowe instrukcje znajdziesz na ich stronie i dokumentacji.
- Sklonuj repozytorium gdzieś u siebie na komputerze:
$ git clone https://github.com/jpowie01/GradientPG.git- W folderze ze źródłami użyj polecenia:
$ docker-compose upUWAGA! Polecenie za pierwszym razem może chwilę potrwać ze względu na pobranie obrazu z Internetu!
- Gotowe! Przejdź do swojej przeglądarki i wejdź na stronę
http://127.0.0.1:4000/. Gdy tylko dodasz swoją treść do kodu
- strona powinna zostać automatycznie wygenerowana oraz będzie sama aktualizowała swoją treść.
TIP: Z powodu buga (prawdopodobnie w samym Jekyllu) sugerujemy trzymanie niniejszego projektu w miejscu, do którego ścieżka będzie zawierała tylko i wyłącznie kody ASCII (bez polskich znaków). W przeciwnym wypadku możesz mieć problemy z długą (bądź nawet wyłączoną) automatyczną aktualizacją strony.
Jest to opcja szczerze mówiąc masochistyczna. Wymaga ona instalacji wszystkich składników osobno. Jest to o tyle trudniejsza droga do opisania, gdyż zależy ona od posiadanego systemu operacyjnego.
Przykładowo - dla Ubuntu należy wykonać następujące kroki:
- Zainstaluj na swoim komputerze następujące paczki:
$ sudo apt-get install make gcc ruby ruby-dev nodejs- Zainstaluj następujący pakiet za pomocą Gema:
$ gem install bundler- Sklonuj repozytorium gdzieś u siebie na komputerze:
$ git clone https://github.com/jpowie01/GradientPG.git- W folderze ze źródłami wykonaj następujące polecenie:
$ bundle install- Następnie uruchom stronę następującym poleceniem:
$ bundle exec jekyll serve- Gotowe! Przejdź do swojej przeglądarki i wejdź na stronę
http://127.0.0.1:4000/. Gdy tylko dodasz swoją treść do kodu - strona powinna zostać automatycznie wygenerowana.
Jak widzisz - nie jest to prosta droga. Co więcej, możesz zrobić sobie niezły syf na komputerze. Jest to niestety jedyna droga w przypadku, gdy z jakiejś przyczyny (np. słaby komputer, brak odpowiedniego systemu, itd.) nie jesteś w stanie użyć Dockera/Vagranta.
Pomocne mogą się okazać następujące źródła:
Nie, nie musisz, ale nie będziesz mógł upewnić się, że Twoje dzieło będzie wyglądało poprawnie na stronie.
Rekomendujemy, aby testować swoje posty i projekty lokalnie!
Strona aktualizuje się o każdej pełnej godzinie. Staraliśmy się o auto-deployment przy każdym merge'u, ale wymaga to trochę więcej wysiłku... Może pewnego dnia ulepszymy ten proces.
Aby dodać kod, wystarczy, że użyjesz następującej składni:
{% highlight python %}
def demo(arg1, arg2):
print(arg1 + ', ' + arg2 + '!')
demo('hello', 'world')
{% endhighlight %}
Na stronie można swobodnie umieszczać wzory matematyczne zapisane w formacie LaTeX. Wystarczy je owinąć w znacznik podwójnego dolara, a reszta zostanie sparsowana auto-magicznie. Biblioteka, którą zainstalowaliśmy powinna także poradzić sobie z innymi formatami.
Przykład użycia wzoru zapisanego w LaTeX:
$$
\begin{equation}
{\sum\limits_{n=1} }'C_n
\end{equation}
$$
Więcej przykładów znajdziecie tutaj.
Tip: Pobierzcie sobie dany przykład na dysk (prawy przycisk myszy na linku -> zapisz jako) i przejrzyjcie kod źródłowy danego przykładu :)
Przechowywanie dużych plików w repozytorium jest dość "upierdliwe". Każdy pull/fetch wymagać będzie od wszystkich osób pobierania całego folderu ze wszystkimi plikami, których prawie na pewno nie użyjesz :) Dlatego też... przygotowaliśmy osobne repozytorium na takie pliki :) Jak zapewne zauważyłeś w katalogu głównym znajduje się podmoduł gita (ang. submodule). Jest to nic innego jak link do innego repozytorium, które znajdziesz tutaj. Wystarczy, że zrobisz pull request tak samo jak to robiłeś/-aś podczas dodawania nowego postu.
Plik będzie dostępny na stronie internetowej pod linkiem: http://gradient.eti.pg.gda.pl/pliki/<ŚCIEŻKA>. Pliki pobierane są podczas deploymentu, który odpala się o każdej pełnej godzinie, a więc mogą się pojawić na serwerze z lekkim opóźnieniem.
UWAGA nr1! Mniejsze pliki (np. zdjęcia do postów) proponujemy trzymać w folderze assets w niniejszym repozytorium. Będzie to wygodniejsze :)
UWAGA nr2! Prosimy o zdjęcia JPG o wadze max. 150KB!
Użyliśmy Jekylla ze skórką Centrarium. Całość jest kompatybilna z GitHub Pages, gdzie testowaliśmy całość zanim zahostowaliśmy stronę na serwerach KASKu. Dodatkowo, użyliśmy biblioteki MathJax oraz HighlightJS, żeby dodać trochę życia do HTMLa :)
Warto zapoznać się również z tym cheatsheetem, który zawiera wszelkie potrzebne informacje o developmencie stron w Jekyllu.
Do internacjonalizacji wykorzystaliśmy plugin "jekyll-multiple-languages-plugin", który całkiem przyjemnie zapewnia nam obsługę standardu i18n. Po więcej szczegółów zapraszamy do powyższego linka, gdzie znajdziesz wszystkie informacje o tym jak z nim pracować.
- Każdy Członek Koła ma możliwość uczestnictwa w życiu strony internetowej (w tym publikacji treści).
- Tylko Administratorzy oraz Zarząd Koła mają możliwość merge'owania kodu do głównego brancha
master. - Każda osoba publikująca treść powinna przetestować swoją publikację na lokalnym komputerze.
- Publikujący powinien dostosować się do zasad formatowania nazw plików stosowanych w ramach projektu.
- Niedostosowanie się do powyższych zasad może skutkować odebraniem możliwości kontrybucji.