1. Ogólna informacja o blogu

Blog został utworzony w celu napisania projektu inżynierskiego. Strona znajduje się pod domeną projektinzynierski.pl, która będzie aktualna tylko przez rok, ale strona jest także hostowana od strony platformy Github. Strona realizuje sporo fajnych i ciekawych funkcjonalności. Takie jak możliwość dodania komentarzy, renderowanie kodu LaTeX, integrację z Jupyterem, hostowanie w ramach własnej domeny, generowana jest z pomocą silnika Jekyll, jest możliwość dodania tagów i później przeszukania po tych tagach. Także jest możliwość dodania postów z pliku z rozszerzeniem .md.

2. Struktura kodu

Projekt zawiera wygodny szablon który składa się z folderów oraz podfolderów.

Folder _data zawiera tylko jeden plik z rozszerzeniem .yml i nazwą ui-text. Ten plik jest odpowiedzialny za tekst i etykiety interfejsu użytkownika. Plik zawiera dużo języków, takie jak Hiszpański, Francuski, Portgugalski, Włoski, Angielski, Polski i sporo innych.

Folder _includes zawiera dużo plików, przy tym te pliki tylko z rozszerzeniem .html, które odpowiadają za różne rzeczy. Niektóre odpowiadają za komentarze, niektóre tagi, za stopke, są także pliki, które renderują LaTeX.

Z bardziej interesujących plików, które znajdują się w tym folderze to są:

1. disqus.html - który odpowiada za polączenie z usługą hostingową, która jest odpowiedzialna za pozostawianie komentarzy.
2. head.html - jest to plik, który odpowiada za rzeczy działające na stronie głównej blogu. Także w tym pliku znajduje się renderowanie kodu LaTeX.
3. search.html - odpowiada za przeszukanie słów kluczowych znajdujących się na stronie.

Folder _layouts zawiera sześć plików, które odpowiadają za takie rzeczy jak: integrację z plikami css oraz js, za strone początkową, za minimalizację strony, za ustawianie postów.

1. base.html - odpowiada za integrację z plikami css, js.
2. default.html - odpowiada za stronę domyślną oraz konfigarcji na niej.
3. home.html - odpowiada za ustawienie informacji znajdujących się na stronie głównej, takich jak: tagi, datę, opisu o konkretnym poście.
4. minimal.html - odpowiedzialny za minimalizację strony.
5. page.html - odpowiada za konfigurację po stronie blogu .
6. post.html - plik dzięki któremu odybywa się dodawanie postów, także jest dołączona część kodu, która umożliwia dodawanie komentarzy pod każdym postem.

Folder _posts zawiera pliki .md, które później wyświetlają się na stronie statycznej blogu.

Folder assets zawiera kolejne podfoldery, odpowiedzialne za css, js oraz przechowywanie zdjęć potrzebnych dla dodania ba blogu. Podfolder css zawiera pliki, które odpowiadają za stylizację strony. Podfolder img zawiera zdjęcia z których korzysta się na blogu. Podfolder js zawiera dwa plik. Pierwszy z nich jest to beautifuljekyll.js, który jest silnikiem blogu, tzw. Jekyll. Kolejnym plikiem jest staticman.js, odpowiedzialnym za komunikaty oraz błędy.

Folder docs zawiera tylko jeden plik index.html, który prawie zawsze jest w takich rodzajach projektów, jest to plik główny projektu. Także zawiera takie pliki jak:

1. _config.yml - odpowiedzialny za ustawianie różnych informacji o autorze, tytule, linki do różnych platform, ustawianie domyślnych wartości YAML.
2. aboute.md - w tym pliku jest przechowywana informacja o autorze, która jest widoczna przy kliknięciu na przycisk ‘O mnie’ znajdujący się w górnym pasku.
3. tags.html - odpowiada za tagi znajdujące się na blogu.
4. staticman.yml - odpowiada za ustawienie domyslnych wartości YAML.

3. Hostowanie blogów z wykorzystaniem statycznych generatorów stron (Jekyll)

Strony GitHub są obsługiwane przez Jekyll za kulisami, więc są świetnym sposobem na hostowanie witryny opartej na Jekyll za darmo.

Jekyll to statyczny generator witryn z wbudowaną obsługą stron GitHub i uproszczonym procesem kompilacji. Jekyll pobiera pliki Markdown i HTML i tworzy kompletną statyczną stronę internetową na podstawie wybranych układów. Jekyll obsługuje Markdown i Liquid, język szablonów, który ładuje dynamiczną zawartość w Twojej witrynie.

4. Dodawanie postów

Posty można dodać w bardzo prosty sposób, warto tylko wejść w kod źródłowy repozytorium. Do folderu _posts trzeba dodać plik z rozszerzeniem .md o którym wspomniano w poście “O Markdown”, w którym należy zdefiniować według plików które znajdują się w tym folderze. A także dodać kolejną linijkę kodu do pliku _layouts/post.html, która odpowiada za wyświetlenie tego postu na stronie statycznej.

gdzie n jest liczbą postu.

5. Dodawanie komentarzy

Dodawanie komentarzy jest możliwe zarówno na stronie statycznej, jak i po stronie repozytorium na Github.

Po stronie repozytorium konfiguracja wyglądała w ten sposób, że Github ma coś takiego jak GitHub Discussions. Jest to forum, które można włączyć w każdym repozytorium GitHub. Ułatwia programistom omawianie nowych funkcji, uzyskiwanie opinii społeczności, tworzenie ankiet, zamieszczanie ogłoszeń i nie tylko. W tym przypadku należalo poprawić niektóre ustawienia w Github. I wygląda to w następujący sposób:

Drugim sposobem jest dodanie z pomocą Disqus. Jest to amerykańska usługa hostingowa komentarzy blogowych oferująca platformę między innymi do integracji społecznej, sieci społecznościowych, profili użytkowników i analityki.

Usługa została utworzona w 2007 roku przez Daniela Ha i Jasona Yana. W 2011 roku usługa zajęła pierwsze w rankingu Quantcast ze 379,8 miliona unikalnych wizyt. W 2016 roku usługa zajęła 278 miejsce w rankingu Alexa Internet. Disqus jest umieszczony na 750 tysiącach ston internetowych.

Zalety korzystania z Dyskusji jako systemu czatu na blogu:

1. Jest całkowicie darmowy
2. Nie ma reklam ani śledzenia
3. Jest super potężny
4. Mamy pełną kontrolę nad komentarzami i pełne uprawnienia do moderacji.
5. Jest wiele tematów
6. Jest dość konfigurowalny
7. Można hostować na własnych serwerach

Tak wygląda dodawanie zdjęć na stronie statycznej. Jest ono możliwe w tym przypadku jeśli użytkownik, który chce dodać komentarz musi mieć konto na Disqus. Jest tak dlatego, że dodanie komentarzy na stronie statycznej jest zrealizowane z pomocą amerykańskiej usługi hostingowej komentarzy blogowych.

Za podłączenie usługi hostingowej Disqus odpowiada kawałek kodu w pliku _layouts/post.html od linijki 99 do linijki 110

  <!--Adding comments under each post-->
  <div id="disqus_thread"></div>
  <script>
      (function() { // DON'T EDIT BELOW THIS LINE
      var d = document, s = d.createElement('script');
      s.src = 'https://newwww.disqus.com/embed.js';
      s.setAttribute('data-timestamp', +new Date());
      (d.head || d.body).appendChild(s);
      })();
  </script>
  <noscript>Włącz JavaScript, aby wyświetlić <a href="https://disqus.com/?ref_noscript">komentarze stworzene po stronie Disqus.</a></noscript>
<!--Adding comments under each post-->

Jest także w tych komentarzach możliwość dodawania reakcji. Da się ich wyłączyć w ustawieniach admina na stronie Disqus.

6. Renderowanie LaTeX

LaTeX – oprogramowanie do zautomatyzowanego składu tekstu, a także związany z nim język znaczników, służący do formatowania dokumentów tekstowych i tekstowo-graficznych (na przykład: broszur, artykułów, książek, plakatów, prezentacji, a nawet stron HTML).LaTeX nie jest samodzielnym środowiskiem programistycznym: jest to zestaw makr stanowiących nadbudowę dla systemu składu automatyzujących czynności związane z procesem składania tekstu. Jednak, ze względu na dużą popularność LaTeX-a (w porównaniu z czystym TeX-em) nazwy te bywają używane zamiennie.

Zasada działania LaTeX: Tworzenie tekstu w LaTeX-u opiera się na zasadzie WYSIWYM (What You See Is What You Mean – to, co widzisz, jest tym, o czym myślisz). Od zasady WYSIWYG odróżnia go to, że autor tekstu określa jedynie logiczną strukturę dokumentu (tzn. zaznacza, gdzie zaczyna się rozdział, co jest przypisem itp.), natomiast samym graficznym „ułożeniem” tekstu na stronie zajmuje się TeX, zwalniając tym samym użytkownika z tego zadania.

LaTeX zajmuje się również odpowiednim rozmieszczeniem i sformatowaniem wzorów matematycznych, rysunków i diagramów, zwalniając użytkownika ze żmudnej pracy związanej z integracją tych elementów z właściwym tekstem.

W sposób automatyczny tworzone są:

1. Spisy treści, ilustracji oraz tabel
2. Numerowanie i referencje do rozdziałów i podrozdziałów
3. Numerowanie i referencje elementów takich jak wzory i rysunki
4. Skorowidze
5. Bibliografia

Dokument LaTeX-owy zawiera de facto kod źródłowy właściwego dokumentu, którego uzyskanie wymaga przeprowadzenia procesu kompilacji. W jej wyniku powstaje plik wynikowy w formacie DVI, specyficzny tylko dla środowiska TeX. Plik DVI można następnie przetworzyć na jeden z popularnych formatów, takich jak PostScript, PDF lub HTML.

Umieszczanie LaTeX-a na swoim blogu jest obowiązkową funkcją dla każdego, kto chce umieszczać wzory matematyczne w swoim blogu.

Renderowanie kodu LaTeX zrobiłem w ten sposób, że dodałem script kodu do pliku includes/head i dlatego LaTeX będzie obsługiwany wszędzie, bo będzie jest podłączony do pliku głównego postów. Konfiguracja odbywa się w pliku _includes/head.html w samym końcu od linijki 153 do 163.

<!--Rendering latex code-->
  <script type="text/x-mathjax-config">
    MathJax.Hub.Config({
      tex2jax: {
        skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
        inlineMath: [['$','$']]
      }
    });
  </script>
  <script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script> 
<!--Rendering latex code-->

Tak wygląda dodanie wzoru LaTeX w pliku .md

$\mathcal{\[ a_1^2 + a_2^2 = a_3^2 \]}$

7. Integracja z Jupyterem

JupyterLab to najnowsze internetowe interaktywne środowisko programistyczne dla notatników, kodu i danych. Jego elastyczny interfejs pozwala użytkownikom konfigurować i organizować przepływy pracy w nauce o danych, obliczeniach naukowych, dziennikarstwie obliczeniowym i uczeniu maszynowym. Modułowa konstrukcja zachęca do rozszerzenia i wzbogacenia funkcjonalności.

Notatnik Jupyter to oryginalna aplikacja internetowa do tworzenia i udostępniania dokumentów obliczeniowych. Oferuje proste, usprawnione, zorientowane na dokumenty doświadczenie.

Do czego służy Jupyter? Jedną z nich jest Jupyter i jego notebook, który pozwala na tworzenie interaktywnych arkuszy mogących zawierać kod wykonywalny, opisy, tabele, wykresy i wiele innych danych, które służyć mogą nam między innymi do prezentacji wyników naszych prac.

Początkowe założenia były takie, że dodanie Jupytera miało być po stronie statycznej, tzn. dodanie konfiguracji bezpośrednio w kodzie źródłowym. Tak jak to jest trudne do zrobienia, to zdecydowałem zrobić to z pomocą zewnętrznej internetowej platformy.

CoCalc to internetowa platforma do przetwarzania w chmurze (SaaS) i zarządzania kursami dla matematyki obliczeniowej. W ramach projektu Sage obsługuje edycję arkuszy roboczych Sage, dokumentów LaTeX i notatników Jupyter. CoCalc uruchamia środowisko Ubuntu Linux, z którym można komunikować się za pośrednictwem terminala, dodatkowo dając dostęp do większości możliwości Linuksa.

Zanim załadujemy plik Jupytera musimy go utworzyć, w moim przypadku zrobiłem to na stronie [cocalc.com], stworzyłem tam notatnik Python z instrukcją w jednej komórce. Później dodałem nowo utworzony plik w swoim repozytorium. W ten sposób Jupyter Notebook będzie dodany bezpośrednio w repozytorium jako plik.

W rzeczywistości możemy wyświetlić podgląd notatnika, klikając go. GitHub automatycznie wyrenderuje notes, tak aby był wyświetlany w przeglądarce. To może być świetny sposób, aby szybko pokazać innym, to co robimy. Notatniki Jupyter udostępniane za pośrednictwem usługi GitHub są renderowane, ale są statyczne. GitHub nie uruchamia notesów w repozytorium.

8. Dodanie tagów Możemy zobaczyć, że tagi są wyświetlone pod każdym postem.

Zdefiniować tagi możemy w nagłówku każdego pliku z rozszerzeniem .md w ten sposób.

tags: [jupyter, test]

Także istnieje możliwość przeszukania po tagach. Dzieje się to w ten sposób, że jak wciskamy na tag to idzie przekierowanie na wszystkie możliwe taki, które istnieją.

9. Hostowanie w ramach własnej domeny

Hosting można określić jako „miejsce”, w którym przechowujemy swoje pliki, aby były dostępne w internecie. Domena może zostać połączona z serwerem w celu np. wyświetlania jego zawartości pod adresem domeny lub chęci utworzenia skrzynek e-mail w adresie domeny (np. biuro@twojadomena.pl).

Jako zawartość serwera należy rozumieć pliki (np. pliki strony WWW), które mogą zostać wyświetlone po wpisaniu adresu domeny w przeglądarce. Tymi plikami jest najczęściej sama strona internetowa, ale domena kierując na określone zasoby, może wyświetlać znacznie więcej informacji, np. faktyczne pliki do pobrania (zdjęcia z wakacji), spakowane archiwa .zip itp.

Domena ma możliwość posiadania tzw. subdomen czyli adresów dodatkowych utworzonych w adresie domeny, np. blog.domena.pl itp. Tworząc je bezpłatnie w ramach swojej domeny. Możemy je przekierować na różne lokalizacje, utworzyć wiele stron lub udostępnić wiele zasobów.

Czy domena GitHub Pages jest bezpłatna? GitHub Pages to właśnie rozwiązanie tego problemu. Można hostować swoją witrynę, w tym niestandardowe nazwy domen (https://dhrumil.xyz), stronę błędu 404, subdomenę (https://blog.dhrumil.xyz) i cały bezpieczny https.

Dla każdego zarejestrowanego konta GitHub (reprezentującego użytkownika lub organizację) można zarejestrować jedną stronę użytkownika, ale nieograniczoną liczbę stron projektu.

Czy potrzebuję hostingu internetowego, jeśli mam nazwę domeny? Tak. Nazwa domeny to tylko adres witryny, podczas gdy hosting przechowuje wszystkie dane i pliki witryny. Bez hostingu witryna nie istnieje, a nazwa domeny nie prowadziłaby donikąd.

10. Sklonowanie usługi do konkurencyjnej platformy

Sklonowanie do konkurencyjnej platformy odbywa się dlatego, żeby sprawdzić czy wszystkie funkcjonalności, które działają w ramach platformy Github będą działać również na innych platformach. Spróbuję sklonować repozytorium na dwie następujące platformy: Gitlab oraz Bitbucket.

10.1. Sklonowanie usługi do konkurencyjnej platformy - Gitlab

GitLab – hostingowy serwis internetowy przeznaczony dla projektów programistycznych oparty o system kontroli wersji Git oraz otwartoźródłowe oprogramowanie, stworzone przez Dmitrija Zaporozhets, których obecnie właścicielem jest GitLab Inc. Serwis umożliwia bezpłatne wykorzystanie usługi lub zainstalowanie samodzielnie zarządzanego oprogramowania wraz z opcjonalnymi, płatnymi planami. Usługa jest jedną z najpopularniejszych tego typu na rynku, z której korzystają takie firmy, jak IBM, Sony, NASA, Oracle, GNOME Foundation, NVIDIA, czy SpaceX. Serwis był notowany w rankingu Alexa na miejscu 2855 (maj 2020).

Usługa oprócz repozytoriów opartych na systemie kontroli wersji oferuje także platformę dla metodyki DevOps oraz CI/CD.

Oprogramowanie serwisu GitLab zostało stworzone w języku Ruby (Ruby on Rails), a wygląd serwisu w języku JavaScript (Vue.js).

Strony GitLab są bardzo podobne do stron GitHub. GitLab Pages obsługują również niestandardowe nazwy domen i certyfikaty SSL oraz zawiera platformę ciągłej integracji. Można wdrażać witryny na stronach GitLab z lub bez domeny niestandardowej.

GitHub Pages jest znacznie łatwiejszy w konfiguracji i obsłudze, a średnie witryny uzyskują kilka milionów odwiedzin rocznie GitLab Pages ma więcej funkcji i elastyczność dla zaawansowanych użytkowników.

10.2. Sklonowanie usługi do konkurencyjnej platformy - Bitbucket

Bitbucket to strona internetowa, która pozwala programistom Git zarządzać swoimi kodami i współpracować ze sobą w czasie rzeczywistym. Jedną z głównych funkcji Bitbucket są strony Bitbucket, które są repozytoriami, w których użytkownicy mogą przechowywać i udostępniać swoje kody, pracować nad kodami jako zespół i wizualnie zobaczyć swoje produkty.

Czy Bitbucket ma strony takie jak GitHub? Jeśli lubisz GitHub Pages, wypróbuj podobną funkcję Bitbucket. Zapewnia wszystko, co jest potrzebne do hostowania osobistych lub prostych witryn statycznych

Jaka jest różnica między Bitbucket i GitHub? Zawartość. Jeśli sprowadzimy to do najbardziej podstawowej różnicy między GitHub i Bitbucket, to jest to, że GitHub koncentruje się na kodzie publicznym, a Bitbucket jest prywatny. GitHub ma ogromną społeczność open-source, a Bitbucket ma głównie użytkowników korporacyjnych i biznesowych.