Izradite svoj web u 4 sata! (radionica)

Nastavak i praktična strana predavanja Zašto i kako izraditi web sjedište istraživačke grupe s Mutimira 2023.

Najava radionice

Penkalin web kaže:

Za koga:

• Doktorande, poslijedoktorande, voditelje grupa ili bilo koga!
• Za one kojima nije baš do istraživanja sami kako to napraviti, i žele brzo, jednostavno i besplatno rješenje bez potrebe za kasnijim održavanjem
• Za one koji ne vole kodirati, niti ih zanimaju postavljanje domena i servera

Od koga: doc. dr. sc. Vedran Miletić i Matea Turalija, GASERI, FIDIT/MedRi, Sveučilište u Rijeci

Kada i gdje: Online, u 2 termina po 2h, 24.4. i 8.5.2024.

Najava radionice (nast.)

Penkalin web dalje kaže:

Zašto:

• Svi projekti vam ne stanu na CV, a web stranice su pravo rješenje za portfolio vaših istraživanja, projekata, publikacija, kodova itd.
• Vlastite web stranice povećavanju vašu vidljivost kao znanstvenika
• Znanstvena komunikacija vam je u planu, ali nikad niste sjeli i smislili kako
• Osobni web ili web grupe povećava šanse za suradnjama
• Izrada weba može biti jednostavna i brza ako znate prave alate

Ishod učenja

Imati na javnom webu postavljeno vlastito sjedište slično onome kakvo ima Matea Turalija.

Neishodi učenja

• Kupnja i konfiguracija vlastite domene.
• Optimizacija sadržaja za tražilice.
• Dizajn web sjedišta.
• Suradnički razvoj i verzioniranje.

CMS ili Jamstack?

• sustav za upravljanje sadržajem (content management systems, CMS)
  • WordPress, Shopify, Wix, Squarespace, Joomla, Drupal i brojni drugi
• generator statičkog web sjedišta, kolokvijalno Jamstack
  • Hugo, Jekyll, Docusaurus, MkDocs i brojni drugi

Sadržaj radionice

• 24. 4. 2024.
  • Stvaranje projekta web sjedišta (Python, MkDocs)
  • Pisanje web stranica u Markdownu (Visual Studio Code i proširenja markdownlint, Markdown Theme Kit i Word Count)
• 8. 5. 2024.
  • Postavljanje sjedišta na web (Git, GitHub, GitHub Pages)
  • Mogućnosti konfiguracija projekta web sjedišta (Material for MkDocs)

Priprema za radionicu

Potrebno je registrirati korisnički račun na GitHubu.

Potrebni softveri

• Windows Terminal (samo na Windowsima)
• Microsoft PowerToys (samo na Windowsima)
• Visual Studio Code
  • markdownlint, Markdown Theme Kit i Word Count
• Python
  • MkDocs i Material for MkDocs
• Git

Upute za instalaciju potrebnih softvera

Preduvjeti za instalaciju potrebnih softvera

sudo apt update && sudo apt upgrade

Naredbe za instalaciju potrebnih softvera

winget install --id Microsoft.PowerToys -e

Radno okruženje Visual Studio Code:

winget install --id Microsoft.VisualStudioCode -e

curl -L -o code.deb 'https://code.visualstudio.com/sha/download?build=stable&os=linux-deb-x64'
sudo apt install ./code.deb

Proširenja markdownlint, Markdown Theme Kit i Word Count:

code --install-extension DavidAnson.vscode-markdownlint
code --install-extension ms-vscode.Theme-MarkdownKit
code --install-extension ms-vscode.wordcount

Python:

winget install --id Python.Python.3.12 -e

sudo apt install python-is-python3 python3-pip

MkDocs i Material for MkDocs:

pip install mkdocs-material

Git:

winget install --id Git.Git -e

sudo apt install git

U slučaju da imate pitanja, obratite se Vedranu Miletiću putem e-maila.

Osnovna literatura

Visual Studio Code i proširenja:

• Basic Editing in Visual Studio Code
• Terminal Basics in Visual Studio Code
• Markdown and Visual Studio Code
• Collaborate on GitHub

MkDocs i Material for MkDocs:

• Command Line Interface -- MkDocs
• Writing your docs -- MkDocs
• Deploying your docs -- MkDocs
• Configuration -- MkDocs
• Material for MkDocs

Sadržaj prvog dijela radionice

• Stvaranje projekta web sjedišta (Python, MkDocs)
• Pisanje web stranica u Markdownu (Visual Studio Code i proširenja markdownlint, Markdown Theme Kit i Word Count)

Započinjanje projekta

U (Windows) Terminalu:

mkdocs new mojnoviweb

U Visual Studio (VS) Code: izbornik File pa Open Folder... pa pronađite mapu mojnoviweb i otvorite ju.

U VS Code ugrađenom terminalu:

mkdocs serve

pa Ctrl i klik na http://127.0.0.1:8000/ u izlazu naredbe za otvaranje pregleda weba.

Pisanje Markdowna

• Writing with Markdown (Writing your docs -- MkDocs)
• Suradnički uređivač teksta HackMD i jezik Markdown
• (Zettlr workshop)

Sadržaj drugog dijela radionice

• Postavljanje sjedišta na web (Git, GitHub, GitHub Pages)
• Mogućnosti konfiguracija projekta web sjedišta (Material for MkDocs)

Postavljanje web sjedišta na GitHub

Preduvjeti:

• postavljanje imena i e-maila u konfiguraciji Gita
• stvaranje SSH ključa
• dodavanje ključa na GitHub
• provjera mogućnosti povezivanja
• stvaranje repozitorija
• povezivanje repozitorija
• uključivanje GitHub Pages

Postavljanje imena i e-maila u konfiguraciji Gita

git config --global user.name "Cool Gaser"
git config --global user.email "cool@gaser.zg"

Stvaranje SSH ključa

U Terminalu pokrenite naredbu (pripazite da ne prepišete ključ koji već postoji):

ssh-keygen

Dodavanje SSH ključa na GitHub

Na GitHubovom web sjedištu u web pregledniku:

1. Klik na svoj avatar u gornjem desnom uglu pa u izborniku s desne strane Settings pa u izborniku s lijeve strane SSH and GPG keys ili otvorite izravno https://github.com/settings/keys.

2. GPG ključevi nam zasad nisu bitni. Klik na New SSH key ili otvorite izravno https://github.com/settings/ssh/new, postavite naslov u polju Title po želji, Key type neka bude Authentication key i u Key zalijepite izlaz naredbe:

   cat .ssh/id_rsa.pub
   

Provjera mogućnosti povezivanja na GitHub

U Terminalu:

ssh -T git@github.com

U slučaju da je sve ispravno konfigurirano:

Hi coolgaser! You've successfully authenticated,
but GitHub does not provide shell access.

Stvaranje repozitorija web sjedišta na GitHubu

Klik na + gore desno pa New repository ili otvorite izravno https://github.com/new. Ime u polju Repository name postavite da bude oblika vasekorisnickoime.github.io, pri čemu na mjesto vasekorisnickoime umetnite svoje korisničko ime (npr. coolgaser).

Repozitorij neka bude javan (Public), a pod Initialize this repository: ne uključujte ništa (ni README, ni .gitignore, ni licencu).

Stvaranje lokalnog repozitorija i povezivanje s repozitorijem na GitHubu

U VS Code terminalu nakon otvaranja projekta mojnoviweb:

1. stvaranje lokalnog repozitorija:

   git init
   git add .
   git commit -m "first commit"
   git branch -M main
   

2. povezivanje s repozitorijem na GitHubu:

   git remote add origin git@github.com:vasekorisnickoime/vasekorisnickoime.github.io.git
   git push -u origin main 
   

3. priprema web sjedišta za prvo postavljanje

   mkdocs gh-deploy
   

Uključivanje GitHub Pages

1. Na stranici repozitorija odaberite karticu Settings pa u izborniku s lijeve strane Pages. Pod Build and deployment:

   1. Source postavite na Deploy from a branch.
   2. Branch postavite na gh-pages i zatim prisnite gumb Save.

2. (Uočite da postoji i odjeljak Custom domain.)

3. Otvorite u web pregledniku adresu:

   https://vasekorisnickoime.github.io/
   

Postavke značajki web sjedišta

• Boje
• Oblici pisma
• Jezik
• Pretraga
• Zaglavlje
• Podnožje
• Oznake

Postavke značajki web sjedišta (nast.)

• Blog
• Slike
• Tablice
• Fusnote
• Matematika
• Blokovi izvornog koda
• Dijagrami

Za one koji žele znati više

• Ikone
• Navigacija
• Analitika
• Kartice za društvene mreže
• Povezivanje repozitorija
• Komentari
• Proširenja
• Rešetke
• Opisi

Zahvale

• Una Pale i ostali aktivni članovi Udruge Penkala
• Martin Donath (autor teme Material for MkDocs) i čitava zajednica oko MkDocsa

Author: Vedran Miletić, Matea Turalija